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 that we’ll use to discuss the various parts:

telegram-text-source.kamelet.yaml
apiVersion: camel.apache.org/v1
kind: Kamelet
metadata:
  name: telegram-text-source (1)
  annotations: (2)
    camel.apache.org/kamelet.icon: "data:image/svg+xml;base64,PD94bW..."
  labels: (3)
    camel.apache.org/kamelet.type: "source"
spec:
  definition: (4)
    title: "Telegram Text Source"
    description: |-
      Receive all text messages that people send to your telegram bot.

      # Instructions
      Description can include Markdown and guide the final user to configure the Kamelet parameters.
    required:
      - botToken
    properties:
      botToken:
        title: Token
        description: The token to access your bot on Telegram
        type: string
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password

  dataTypes: (5)
    out:
      default: text
      types:
        text:
          mediaType: text/plain
          # schema:
  template: (6)
    from:
      uri: telegram:bots
      parameters:
        authorizationToken: "#property:botToken"
      steps:
        - convert-body-to:
            type: "java.lang.String"
            type-class: "java.lang.String"
            charset: "UTF8"
        - filter:
            simple: "${body} != null"
        - log: "${body}"
        - to: "kamelet:sink"
1 The Kamelet ID, to be used in integrations that want to leverage the Kamelet
2 Annotations such as icon provide additional display features to the Kamelet
3 Labels allow users to query Kamelets e.g. by kind ("source" vs. "sink")
4 Description of the Kamelets and parameters in JSON-schema specification format
5 The data type that the Kamelet produces. Data type specifications contain the media type of the output and also may include a schema.
6 The route template defining the behavior of the Kamelet

At a high level (more details are provided later), a Kamelet resource describes:

  • A metadata section containing the ID (metadata → name) of the Kamelet and other information, such as the type of Kamelet (source or sink)

  • A JSON-schema specification (definition) containing a set of parameters that you can use to configure the Kamelet

  • An optional section containing information about input and output expected by the Kamelet (types)

  • A Camel flow in YAML DSL containing the implementation of the Kamelet (flow)

Once installed on a Kubernetes namespace, the Kamelet can be used by any Integration in that namespace. Kamelets can be installed on a Kubernetes namespace with a simple command:

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 possibly provide auto-completion.

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 telegram-text-source Kamelet in the default namespace on Kubernetes, then you can write the following integration to use the Kamelet:

kamlet-route.yaml
- from:
    uri: "kamelet:telegram-text-source?botToken=XXXXYYYY"
    steps:
      - to: "log:info"
URI properties ("botToken") 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:

kamlet-multi-route.yaml
- 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".

Configuration

When using a Kamelet, the instance parameters (e.g. "botToken", "bucket") can be passed explicitly in the URI or you can use properties. Properties can be also loaded implicitly by the operator from Kubernetes secrets (see below).

URI based configuration

You can configure the Kamelet by passing directly the configuration parameters in the URI, as in:

- 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).

Property based configuration

An alternative way to configure the Kamelet is to provide configuration parameters as properties of the integration.

Taking for example a different version of the integration above:

kamelet-properties-route.yaml
- 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"
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:

kamelet-example.properties
# Configuration for the Telegram source Kamelet
camel.kamelet.telegram-text-source.botToken=the-token-value

# General configuration for the Company Log Kamelet
camel.kamelet.my-company-log-sink.bucket=general
# camel.kamelet.my-company-log-sink.xxx=yyy

# Specific configuration for the Company Log Kamelet corresponding to the named configuration "mynamedconfig"
camel.kamelet.my-company-log-sink.mynamedconfig.bucket=special
# When using "kamelet:my-company-log-sink/mynamedconfig", the bucket will be "special", not "general"

Then the integration can be run with the following command:

kamel run kamelet-properties-route.yaml --property file:kamelet-example.properties

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. For instance:

kamlet-namedconfig-route.yaml
- from:
    uri: "timer:tick?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.

Troubleshooting

A Kamelet is translated into a Route used from the Integration. In order to troubleshoot any possible issue, you can have a look at the dedicated troubleshoot section.

Back to top