From d102eaaa8d0887f103cfc3361a018bcaf98b3d4e Mon Sep 17 00:00:00 2001 From: Joan Edwards <42442393+joaedwar@users.noreply.github.com> Date: Wed, 24 Jul 2019 19:18:36 +0100 Subject: [PATCH] Document usage of Camel K in sources (#1569) * Document usage of Camel K in sources * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md --- .../samples/apache-camel-source/README.md | 102 ++++++++++++------ 1 file changed, 68 insertions(+), 34 deletions(-) diff --git a/docs/eventing/samples/apache-camel-source/README.md b/docs/eventing/samples/apache-camel-source/README.md index de2babf3b..6fbf09968 100644 --- a/docs/eventing/samples/apache-camel-source/README.md +++ b/docs/eventing/samples/apache-camel-source/README.md @@ -1,6 +1,5 @@ -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) +These samples show how to configure a Camel Source. It is an Event Source that +can leverage one of the [250+ Apache Camel components](https://github.com/apache/camel/tree/master/components) for generating events. ## Prerequisites @@ -11,29 +10,29 @@ for generating events. 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). + [Camel K v0.3.3](https://github.com/apache/camel-k/releases/tag/0.3.3). 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-contrib/releases): +1.(Optional) Download Kail binaries for Linux or OSX, which can be found on the [latest release](https://github.com/boz/kail/releases/latest) page. You can use `kail` instead of `kubectl logs` to tail the logs of the subscriber. + +1. Install the Camel Source from the `camel.yaml` in the [Eventing Sources release page](https://github.com/knative/eventing-contrib/releases): ```shell kubectl apply --filename camel.yaml ``` + -## Create a Channel and a Subscriber +### Create a Channel and a Subscriber -In order to check if a `CamelSource` is fully working, we will create: +To verify that the `CamelSource` is 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 +- an 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): @@ -41,34 +40,45 @@ Deploy the [`display_resources.yaml`](./display_resources.yaml): kubectl apply --filename display_resources.yaml ``` -## Run a CamelSource using the Timer component +### Run a CamelSource using the Timer component -The simplest example of CamelSource, that does not require additional -configuration, is the "timer" source. +The samples directory contains some sample sources that can be used to generate +events. + +The simplest one, 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). +[Apache Camel GitHub repository](https://github.com/apache/camel/tree/master/components). -Install the [`source_timer.yaml`](source_timer.yaml) resource: +Install the [timer CamelSource](source_timer.yaml) from source: ```shell -kubectl apply --filename source_timer.yaml +kubectl apply -f 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`. - +We will verify that the published message was sent to the Knative eventing +system by looking at the downstream of the `CamelSource`. + ```shell kubectl logs --selector serving.knative.dev/service=camel-event-display -c user-container ``` +or -If you've deployed the timer source, you should see log lines appearing every 3 +You can also use [`kail`](https://github.com/boz/kail) to tail the logs of the subscriber. + +```shell +kail -d camel-event-display --since=10m +``` + +If you have deployed the timer source, you should see log lines appearing every 3 seconds. -## Run a CamelSource using the Telegram component + +### 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 @@ -82,9 +92,8 @@ 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 `` -placeholder. +First, edit the [telegram CamelSource](source_telegram.yaml) and put the +authorization token, replacing the `` placeholder. To reduce noise in the event display, you can remove the previously created timer CamelSource from the namespace: @@ -93,19 +102,44 @@ timer CamelSource from the namespace: kubectl delete camelsource camel-timer-source ``` -Install the [`source_telegram.yaml`](source_telegram.yaml) resource: +Install the [telegram CamelSource](source_telegram.yaml) from source: ```shell -kubectl apply -f source_telegram.yaml +kunbectl 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: +Start `kail` again and keep it open on the event display: ```shell -kubectl logs --selector serving.knative.dev/service=camel-event-display -c user-container +kail -d camel-event-display --since=10m ``` -Each message you send to the bot will be printed by the event display as a -cloudevent. +Now, you can contact your bot with any Telegram client. Each message you send +to the bot will be printed by the event display as a cloudevent. + + +### Run a Camel K Source + +For complex use cases that require multiple steps to be executed before event data is ready to be published, you can use Camel K sources. +Camel K lets you use Camel DSL to design one or more routes that can define complex workflows before sending events to the target sink. + +If you have previously deployed other CamelSources, to reduce noise in the event display, you can remove them all from the namespace: + +```shell +kubectl delete camelsource --all +``` + +Install the [Camel K Source](source_camel_k.yaml) from source: + +```shell +kubectl apply -f source_camel_k.yaml +``` + +Start `kail` again and keep it open on the event display: + +```shell +kail -d camel-event-display --since=10m +``` + +The event display will show some JSON data periodically pulled from an external REST API. +The API in the example is static, but you can use your own dynamic API by replacing the endpoint.