From 28321b39a5aa7b74f587a69c875af05199b61b04 Mon Sep 17 00:00:00 2001 From: Thomas Diesler Date: Wed, 15 May 2024 12:55:06 +0200 Subject: [PATCH] (#5489) Groovy > Yaml - docs architecture & kamlets & running --- .../advanced/multi-architecture.adoc | 6 +- .../ROOT/pages/kamelets/kamelets-user.adoc | 71 +++++++++++-------- docs/modules/ROOT/pages/languages/groovy.adoc | 5 +- docs/modules/ROOT/pages/running/running.adoc | 30 ++++---- 4 files changed, 66 insertions(+), 46 deletions(-) diff --git a/docs/modules/ROOT/pages/installation/advanced/multi-architecture.adoc b/docs/modules/ROOT/pages/installation/advanced/multi-architecture.adoc index d082b32d12..c801f1e550 100644 --- a/docs/modules/ROOT/pages/installation/advanced/multi-architecture.adoc +++ b/docs/modules/ROOT/pages/installation/advanced/multi-architecture.adoc @@ -21,14 +21,14 @@ The logs should indicate the architecture at the start of the operator pod: === Example -Once you've installed the operator you will need to specify the platform target you whish to use. This is required as each of the different publishing tasks may need to know how to create a manifest accordingly. You can use `builder.platforms` trait option to control this behavior. +The operator will by default build integrations for the same platform it is running on. It is however also possible to explicitly define the set of target platforms integrations should be built for. You can use `builder.platforms` trait option to control this behavior. NOTE: you can set the property at IntegrationPlatform level to have it for all Integrations. -Send the groovy file to kamel operator to build, publish and run it +Send the integration to the kamel operator to build, publish and run it [source,shell] ---- -kamel run hello.groovy -t builder.platforms=linux/arm64 -t builder.platforms=linux/amd64 +kamel run hello.yaml -t builder.platforms=linux/arm64 -t builder.platforms=linux/amd64 ---- You should observe base image in the logs of the operator pod: diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc index 10eec3afe1..6011b4877d 100644 --- a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc +++ b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc @@ -1,7 +1,7 @@ = Kamelets user guide Speaking technically, a Kamelet is a resource that can be installed on any Kubernetes cluster. -The following is an example of Kamelet that we'll use to discuss the various parts: +The following is an example of a Kamelet that we'll use to discuss the various parts: .telegram-text-source.kamelet.yaml [source,yaml] @@ -74,7 +74,7 @@ Kamelets can be installed on a Kubernetes namespace with a simple command: [source,shell] ---- -kubectl apply -f yourkamelet.kamelet.yaml +kubectl apply -f telegram-text-source.kamelet.yaml ---- Kamelets are standard YAML files, but their common extension is `.kamelet.yaml` to help IDEs to recognize them and provide auto-completion (in the future). @@ -86,11 +86,13 @@ Kamelets can be used in integrations **as if they were standard Camel components suppose that you've created the `telegram-text-source` Kamelet in the `default` namespace on Kubernetes, then you can write the following integration to use the Kamelet: -.example.groovy -[source,groovy] +[source,yaml] +.kamlet-route.yaml ---- -from('kamelet:telegram-text-source?botToken=XXXXYYYY') - .to('log:INFO') +- from: + uri: "kamelet:telegram-text-source?botToken=XXXXYYYY" + steps: + - to: "log:info" ---- NOTE: URI properties ("botToken") match the corresponding parameters in the Kamelet definition @@ -99,13 +101,16 @@ Kamelets can also be used multiple times in the same route definition. This happ Suppose that you've defined a Kamelet named "my-company-log-sink" in your Kubernetes namespace, then you can write a route like this: -.example.groovy -[source,groovy] +[source,yaml] +.kamlet-multi-route.yaml ---- -from('kamelet:telegram-text-source?botToken=XXXXYYYY') - .to("kamelet:my-company-log-sink?bucket=general") - .filter().simple('${body} contains "Camel"') - .to("kamelet:my-company-log-sink?bucket=special") +- from: + uri: "kamelet:telegram-text-source?botToken=XXXXYYYY" + steps: + - to: "kamelet:my-company-log-sink?bucket=general" + - filter: + simple: '${body} contains "Camel"' + - to: "kamelet:my-company-log-sink?bucket=special" ---- The "my-company-log-sink" will obviously define what it means to write a log in the enterprise system and what is concretely a "bucket". @@ -119,10 +124,11 @@ loaded implicitly by the operator from Kubernetes secrets (see below). You can configure the Kamelet by passing directly the configuration parameters in the URI, as in: -[source,groovy] +[source,yaml] ---- -from("kamelet:telegram-text-source?botToken=the-token-value") -// ... +- from: + uri: "kamelet:telegram-text-source?botToken=the-token-value" +... ---- In this case, "the-token-value" is passed explicitly in the URI (you can also pass a custom property placeholder as value). @@ -133,20 +139,24 @@ An alternative way to configure the Kamelet is to provide configuration paramete Taking for example a different version of the integration above: -[source,groovy] +[source,yaml] +.kamelet-properties-route.yaml ---- -from('kamelet:telegram-text-source') - .to("kamelet:my-company-log-sink") - .filter().simple('${body} contains "Camel"') - .to("kamelet:my-company-log-sink/mynamedconfig") +- from: + uri: "kamelet:telegram-text-source" + steps: + - to: "kamelet:my-company-log-sink" + - filter: + simple: '${body} contains "Camel"' + - to: "kamelet:my-company-log-sink/mynamedconfig" ---- NOTE: The integration above does not contain URI query parameters and the last URI ("kamelet:my-company-log-sink/mynamedconfig") contains a path parameter with value "mynamedconfig" The integration above needs some configuration in order to run properly. The configuration can be provided in a property file: -.example.properties [source,properties] +.kamelet-example.properties ---- # Configuration for the Telegram source Kamelet camel.kamelet.telegram-text-source.botToken=the-token-value @@ -164,7 +174,7 @@ Then the integration can be run with the following command: [source,shell] ---- -kamel run example.groovy --property file:example.properties +kamel run kamelet-properties-route.yaml --property file:kamelet-example.properties ---- ==== 3. Implicit configuration using secrets @@ -174,8 +184,8 @@ determine the Kamelets configuration. To use implicit configuration via secret, we first need to create a configuration file holding only the properties of a named configuration. -.mynamedconfig.properties [source,properties] +.mynamedconfig.properties ---- # Only configuration related to the "mynamedconfig" named config camel.kamelet.my-company-log-sink.mynamedconfig.bucket=special @@ -194,12 +204,15 @@ kubectl label secret my-company-log-sink.mynamedconfig camel.apache.org/kamelet= You can now write an integration that uses the Kamelet with the named configuration: -.example.groovy -[source,groovy] ----- -from('timer:tick') - .setBody().constant('Hello') - .to('kamelet:my-company-log-sink/mynamedconfig') +[source,yaml] +.kamlet-namedconfig-route.yaml +---- +- from: + uri: "timer:tick" + steps: + - setBody: + constant: "Hello" + - to: "kamelet:my-company-log-sink/mynamedconfig" ---- You can run this integration without specifying other parameters, the Kamelet endpoint will be implicitly configured by the Camel K operator that will diff --git a/docs/modules/ROOT/pages/languages/groovy.adoc b/docs/modules/ROOT/pages/languages/groovy.adoc index ac8f56849b..0c3eb99b92 100644 --- a/docs/modules/ROOT/pages/languages/groovy.adoc +++ b/docs/modules/ROOT/pages/languages/groovy.adoc @@ -16,9 +16,10 @@ from('timer:tick') You can run it with the standard command: -``` +[source] +---- kamel run example.groovy -``` +---- == Configuring the Application diff --git a/docs/modules/ROOT/pages/running/running.adoc b/docs/modules/ROOT/pages/running/running.adoc index 9dd1a46084..5980c2ee3a 100644 --- a/docs/modules/ROOT/pages/running/running.adoc +++ b/docs/modules/ROOT/pages/running/running.adoc @@ -6,27 +6,33 @@ and have the `kamel` CLI correctly configured. Ensure you're connected to the cluster by executing a simple command using the Kubernetes CLI: -``` +[source] +---- kubectl get pod -``` +---- Just replace `kubectl` with `oc` if you're using OpenShift. If everything is correctly configured you should get a response from the Kubernetes API server (you should see at least the `camel-k-operator` running). -You are now ready to create your first integration using Camel K. Just create a new Groovy file with the following content: +You are now ready to create your first integration using Camel K. Just create a new Yaml file with the following content: -.hello.groovy -```groovy -from('timer:tick?period=3000') - .setBody().constant('Hello world from Camel K') - .to('log:info') -``` +[source,yaml] +.run-hello.yaml +---- +- from: + uri: "timer:tick?period=3000" + steps: + - setBody: + constant: "Hello world from Camel K" + - to: "log:info" +---- You can run it on the cluster by executing: -``` -kamel run hello.groovy -``` +[source] +---- +kamel run run-hello.yaml +---- Integrations can be written in any supported Camel DSL. We are collecting examples in our https://github.com/apache/camel-k/[Camel K GitHub repository].