Skip to content

Commit

Permalink
(apache#5489) Groovy > Yaml - docs architecture & kamlets & running
Browse files Browse the repository at this point in the history
  • Loading branch information
tdiesler committed May 15, 2024
1 parent 37ff998 commit 28321b3
Show file tree
Hide file tree
Showing 4 changed files with 66 additions and 46 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
71 changes: 42 additions & 29 deletions docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
Original file line number Diff line number Diff line change
@@ -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]
Expand Down Expand Up @@ -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).
Expand All @@ -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
Expand All @@ -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".
Expand All @@ -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).
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
5 changes: 3 additions & 2 deletions docs/modules/ROOT/pages/languages/groovy.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ from('timer:tick')

You can run it with the standard command:

```
[source]
----
kamel run example.groovy
```
----

== Configuring the Application

Expand Down
30 changes: 18 additions & 12 deletions docs/modules/ROOT/pages/running/running.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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].

Expand Down

0 comments on commit 28321b3

Please sign in to comment.