Add example about using CamelSource (#1107)

* Add example about using CamelSource

* Fix doc after review

* Fix typo

docs/eventing/samples/apache-camel-source/README.md

@@ -0,0 +1,92 @@
+These samples show how to configure a Camel source. It is a event source that
+can leverage one of the [250+ Apache Camel components](https://github.com/apache/camel/tree/master/components)
+for generating events.
+
+## Prerequisites
+
+1. [Install Knative Serving and Eventing](../../../install).
+
+1. Install the [Apache Camel K](https://github.com/apache/camel-k) Operator in any namespace where you want to run Camel sources.
+
+   The preferred version that is compatible with Camel sources is [Camel K v0.2.0](https://github.com/apache/camel-k/releases/tag/0.2.0).
+
+   Installation instruction are provided on the [Apache Camel K Github repository](https://github.com/apache/camel-k#installation).
+   Documentation includes specific instructions for common Kubernetes environments, including development clusters.
+
+1. Install the Camel Source from the `camel.yaml` in the [Eventing Sources release page](https://github.com/knative/eventing-sources/releases):
+
+   ```shell
+   kubectl apply --filename camel.yaml
+   ```
+
+## Create a Channel and a Subscriber
+
+In order to check if a `CamelSource` is fully working, we will create:
+
+- a simple Knative event display service that prints incoming events to its log
+- a in-memory channel named `camel-test` that will buffer events created by the event source
+- a subscription to direct events from the test channel to the event display service
+
+Deploy the [`display_resources.yaml`](./display_resources.yaml):
+
+```shell
+kubectl apply --filename display_resources.yaml
+```
+
+## Run a CamelSource using the Timer component
+
+The simplest example of CamelSource, that does not require additional configuration, is the "timer" source.
+
+If you want, you can customize the source behavior using options available in the Apache Camel documentation for the
+[timer component](https://github.com/apache/camel/blob/master/components/camel-timer/src/main/docs/timer-component.adoc).
+All Camel components are documented in the [Apache Camel github repository](https://github.com/apache/camel/tree/master/components).
+
+Install the [`source_timer.yaml`](source_timer.yaml) resource:
+
+```shell
+kubectl apply --filename source_timer.yaml
+```
+
+We will verify that the published events were sent into the Knative eventing
+system by looking at what is downstream of the `CamelSource`.
+
+```shell
+kubectl logs --selector serving.knative.dev/service=camel-event-display -c user-container
+```
+
+If you've deployed the timer source, you should see log lines appearing every 3 seconds.
+
+## Run a CamelSource using the Telegram component
+
+Another useful component available with Camel is the Telegram component. It can be used to forward messages of
+a [Telegram](https://telegram.org/) chat into Knative channels as events.
+
+Before using the provided Telegram CamelSource example, you need to follow the instructions on the Telegram website for
+creating a [Telegram Bot](https://core.telegram.org/bots).
+The quickest way to create a bot is to contact the [Bot Father](https://telegram.me/botfather), another Telegram Bot,
+using your preferred Telegram client (mobile or web).
+After you create the bot, you'll receive an **authorization token** that is needed for the source to work.
+
+First, download and edit the [`source_telegram.yaml`](source_telegram.yaml) file and put the authorization token, replacing the `<put-your-token-here>` placeholder.
+
+To reduce noise in the event display, you can remove the previously created timer CamelSource from the namespace:
+
+```shell
+kubectl delete camelsource camel-timer-source
+```
+
+Install the [`source_telegram.yaml`](source_telegram.yaml) resource:
+
+```shell
+kubectl apply -f source_telegram.yaml
+```
+
+Now, you can **send messages to your bot** with any Telegram client.
+
+Check again the logs on the event display:
+
+```shell
+kubectl logs --selector serving.knative.dev/service=camel-event-display -c user-container
+```
+
+Each message you send to the bot will be printed by the event display as a cloudevent.

docs/eventing/samples/apache-camel-source/_index.md

@@ -0,0 +1,8 @@
+---
+title: "Apache Camel source"
+linkTitle: "Camel source"
+weight: 5
+type: "docs"
+---
+
+{{% readfile file="README.md" relative="true" markdown="true" %}}

docs/eventing/samples/apache-camel-source/display_resources.yaml

@@ -0,0 +1,46 @@
+# Channel for testing events.
+
+apiVersion: eventing.knative.dev/v1alpha1
+kind: Channel
+metadata:
+  name: camel-test
+spec:
+  provisioner:
+    apiVersion: eventing.knative.dev/v1alpha1
+    kind: ClusterChannelProvisioner
+    name: in-memory-channel
+
+---
+
+# Subscription from the CamelSource's output Channel to the Knative Service below.
+
+apiVersion: eventing.knative.dev/v1alpha1
+kind: Subscription
+metadata:
+  name: camel-source-display
+spec:
+  channel:
+    apiVersion: eventing.knative.dev/v1alpha1
+    kind: Channel
+    name: camel-test
+  subscriber:
+    ref:
+      apiVersion: serving.knative.dev/v1alpha1
+      kind: Service
+      name: camel-event-display
+
+---
+
+# This is a very simple Knative Service that prints the input event to its log.
+
+apiVersion: serving.knative.dev/v1alpha1
+kind: Service
+metadata:
+  name: camel-event-display
+spec:
+  runLatest:
+    configuration:
+      revisionTemplate:
+        spec:
+          container:
+            image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/event_display@sha256:bf45b3eb1e7fc4cb63d6a5a6416cf696295484a7662e0cf9ccdf5c080542c21d

docs/eventing/samples/apache-camel-source/source_telegram.yaml

@@ -0,0 +1,24 @@
+# Apache Camel Telegram Source
+#
+# Telegram Component documentation: https://github.com/apache/camel/blob/master/components/camel-telegram/src/main/docs/telegram-component.adoc
+#
+# List of available Apache Camel components: https://github.com/apache/camel/tree/master/components
+#
+apiVersion: sources.eventing.knative.dev/v1alpha1
+kind: CamelSource
+metadata:
+  name: camel-telegram-source
+spec:
+  source:
+    component:
+      uri: telegram:bots
+      properties:
+        # Camel Telegram component option (ask it to the Botfather: https://telegram.me/botfather)
+        camel.component.telegram.authorizationToken: "<put-your-token-here>"
+
+        # Camel K option to enable serialization of the component output
+        camel.component.knative.jsonSerializationEnabled: "true"
+  sink:
+    apiVersion: eventing.knative.dev/v1alpha1
+    kind: Channel
+    name: camel-test

docs/eventing/samples/apache-camel-source/source_timer.yaml

@@ -0,0 +1,19 @@
+# Apache Camel Timer Source
+#
+# Timer Component documentation: https://github.com/apache/camel/blob/master/camel-core/src/main/docs/timer-component.adoc
+#
+# List of available Apache Camel components: https://github.com/apache/camel/tree/master/components
+#
+apiVersion: sources.eventing.knative.dev/v1alpha1
+kind: CamelSource
+metadata:
+  name: camel-timer-source
+spec:
+  source:
+    component:
+      # Using 'period' URI option (see component documentation)
+      uri: timer:tick?period=3s
+  sink:
+    apiVersion: eventing.knative.dev/v1alpha1
+    kind: Channel
+    name: camel-test