This is an automated email from the ASF dual-hosted git repository.
pcongiusti pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
The following commit(s) were added to refs/heads/main by this push:
new 91572eee8 fix(docs): temporary workaround
91572eee8 is described below
commit 91572eee88acb7af7242ae3a27f63de7098de8a2
Author: Pasquale Congiusti <[email protected]>
AuthorDate: Mon Oct 13 09:31:35 2025 +0200
fix(docs): temporary workaround
---
.../modules/ROOT/pages/kamelets/kamelets-user.adoc | 247 +++++++++++++++++++++
1 file changed, 247 insertions(+)
diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
new file mode 100644
index 000000000..7e1b866d9
--- /dev/null
+++ b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
@@ -0,0 +1,247 @@
+= How to configure a Kamelet
+
+Speaking technically, a Kamelet is a resource that can be installed on any
Kubernetes cluster or used as a plain yaml configuration in Apache Camel
runtimes. The following is an example of a Kamelet source which can be
programmed to trigger events with a `timer`. This is coming directly from
Apache Camel Kamelets catalog:
+
+.timer-source.kamelet.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Kamelet
+metadata:
+ name: timer-source
+ annotations:
+ camel.apache.org/kamelet.support.level: "Stable"
+ camel.apache.org/catalog.version: "4.16.0-SNAPSHOT"
+ camel.apache.org/kamelet.icon:
data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4w[...]
+ camel.apache.org/provider: "Apache Software Foundation"
+ camel.apache.org/kamelet.group: "Timer"
+ camel.apache.org/kamelet.namespace: "Scheduling"
+ labels:
+ camel.apache.org/kamelet.type: "source"
+ camel.apache.org/kamelet.verified: "true"
+spec:
+ definition:
+ title: "Timer Source"
+ description: Produces periodic messages with a custom payload.
+ required:
+ - message
+ type: object
+ properties:
+ period:
+ title: Period
+ description: "The interval (in milliseconds) to wait between producing
the next message."
+ type: integer
+ default: 1000
+ message:
+ title: Message
+ description: The message to generate.
+ type: string
+ example: hello world
+ contentType:
+ title: Content Type
+ description: The content type of the generated message.
+ type: string
+ default: text/plain
+ repeatCount:
+ title: Repeat Count
+ description: Specifies a maximum limit of number of fires
+ type: integer
+ dependencies:
+ - "camel:core"
+ - "camel:timer"
+ - "camel:kamelet"
+ template:
+ from:
+ uri: timer:tick
+ parameters:
+ period: "{{period}}"
+ repeatCount: "{{?repeatCount}}"
+ steps:
+ - setBody:
+ constant: "{{message}}"
+ - setHeader:
+ name: "Content-Type"
+ constant: "{{contentType}}"
+ - to: kamelet:sink
+----
+
+From a user perspective it's important to understand the parameter exposed
(`.spec.definition.properties`) and the execution flow (`.spec.template`).
+
+The flow defines the business logic and generally use the parameter that you,
as a user have to provide in your integration.
+
+The Kamelet can be installed on the cluster as a Kamelet custom resource, and
the operator is already in charge to preinstall the Kamelets coming from the
Apache Camel Kamelets bundled catalog. If you create your own Kamelet you can
install it on the cluster in the following way:
+
+[source,shell]
+----
+kubectl apply -f timer-source.kamelet.yaml
+----
+
+Kamelets are standard YAML files, but their common extension is
`.kamelet.yaml` to help IDEs to recognize them and possibly provide
auto-completion.
+
+[[kamelets-usage-integration]]
+== Using Kamelets in Integrations
+
+Kamelets can be used in integrations **as if they were standard Camel
components**. For example, suppose that you've created the `timer-source`
Kamelet in the `default` namespace on Kubernetes, then you can write the
following integration to use the Kamelet:
+
+[source,yaml]
+.kamlet-route.yaml
+----
+- from:
+ uri: "kamelet:timer-source?message=Hello!"
+ steps:
+ - to: "log:info"
+----
+
+NOTE: URI properties ("message") match the corresponding parameters in the
Kamelet definition.
+
+Kamelets can also be used multiple times in the same route definition. This
happens usually with sink Kamelets. Suppose that you've defined a Kamelet named
"my-company-log-sink" in your Kubernetes namespace, then you can write a route
like this:
+
+[source,yaml]
+.kamlet-multi-route.yaml
+----
+- from:
+ uri: "kamelet:timer-source?message=Hello!"
+ 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".
+
+[[kamelets-usage-pipe]]
+== Binding Kamelets into a Pipe
+
+Kamelets are the main reason why we have introduced the `Pipe` custom
resource. They provide a very easy connector style approach as, each Kamelet,
can be defined naturally as an event source or event sink. Usage of a Kamelet
from a Pipe would be like:
+
+[source,yaml]
+.pipe.yaml
+----
+apiVersion: camel.apache.org/v1
+kind: Pipe
+metadata:
+ name: timer-to-log
+spec:
+ source:
+ ref:
+ kind: Kamelet
+ apiVersion: camel.apache.org/v1
+ name: timer-source
+ properties:
+ message: Hello pipe!
+ sink:
+ ref:
+ kind: Kamelet
+ apiVersion: camel.apache.org/v1
+ name: log-sink
+----
+
+=== Configuration
+
+When using a Kamelet, the instance parameters (e.g. "message", "bucket") can
be passed explicitly in the URI or you can use Camel properties. For example:
+
+[source,yaml]
+.kamlet-route.yaml
+----
+- from:
+ uri: "kamelet:timer-source?message={{my-message}}"
+ steps:
+ - to: "log:info"
+----
+
+The application should run with Camel properties set, such as
`my-message=Hello!`.
+
+=== Kamelet versioning
+
+Kamelets provided in a catalog are generally meant to work with a given
runtime version (the same for which they are released). However, when you
create a Kamelet and publish to a cluster, you may want to store and use
different versions. If the Kamelet is provided with more than the `main`
version, then, you can specify which version to use in your Integration by
adding the version parameter.
+
+NOTE: multiple version Kamelets is an exclusive feature of Camel K.
+
+For instance, take the following multi version Kamelet:
+
+[source,yaml]
+.kamlet-namedconfig-route.yaml
+----
+apiVersion: camel.apache.org/v1
+kind: Kamelet
+metadata:
+ name: my-source
+ labels:
+ camel.apache.org/kamelet.type: "source"
+spec:
+ definition:
+ title: "Timer Example"
+ description: "Emit Kamelet Main body"
+ types:
+ out:
+ mediaType: text/plain
+ template:
+ from:
+ uri: timer:tick
+ steps:
+ - setBody:
+ constant: "Kamelet Main"
+ - to: "kamelet:sink"
+ versions:
+ v1:
+ definition:
+ title: "Timer Example 1"
+ description: "Emit Kamelet V1 body"
+ types:
+ out:
+ mediaType: text/plain
+ template:
+ from:
+ uri: timer:tick
+ steps:
+ - setBody:
+ constant: "Kamelet V1"
+ - to: "kamelet:sink"
+ v2:
+ definition:
+ title: "Timer Example 2"
+ description: "Emit Kamelet V2 body"
+ types:
+ out:
+ mediaType: text/plain
+ template:
+ from:
+ uri: timer:tick
+ steps:
+ - setBody:
+ constant: "Kamelet V2"
+ - to: "kamelet:sink"
+----
+
+You can see it specifies the `main` specification, which it is the default to
use. It also specifies two additional versions, `v1` and `v2`. This is nice if
you want to provide versioning changes maintaining the same resource. When you
use it, you will therefore need to specify the version you want to adopt by
setting the `kameletVersion` parameter. For example, you want to use the `v2`
version:
+
+[source,yaml]
+.kamlet-namedconfig-route.yaml
+----
+- from:
+ uri: "kamelet:my-source?kameletVersion=v2"
+ steps:
+ - to: "log:info"
+----
+
+The operator will be able to automatically pick the right version and use it
at runtime. If no version is specified, then you will use the default one.
+
+=== Kamelet namespace
+
+A Kamelet can be installed in any cluster namespace. By default, the operator
will expect the Kamelet to be in the same namespace of the Integration (or
Pipe), the operator namespace (where the bundled kamelets are stored) or any
other repository defined in the `IntegrationPlatform`. If you want to use a
Kamelet stored in another namespace, you will need to use the
`kameletNamespace` parameter. For example, say you have a dedicated namespace
called `kamelets` where you're installing your [...]
+
+NOTE: namespace Kamelets is an exclusive feature of Camel K.
+
+Now, you can instruct the operator to find the Kamelet you're using into such
namespace, for example:
+
+[source,yaml]
+.kamlet-namedconfig-route.yaml
+----
+- from:
+ uri: "kamelet:my-source?kameletNamespace=kamelets"
+ steps:
+ - to: "log:info"
+----
+
+The operator will be therefore loading the Kamelets from that namespace,
unless the same Kamelet exists in the same Integration namespace or the
operator namespace.
