SupportConsoleDevelopersStart a trialContact

Chapter 5. Customizing existing Kamelet catalog

This document guides you through customizing an existing kamelet. It involves the following stages:

  1. Create a simple kamelet.
  2. Customizing existing kamelet catalog
Note

Red Hat does not support implementing your own kamelet from scratch.

5.1. Creating a simple Kamelet

Apache Camel provides more than 300 components, and it is easy to create a Kamelet starting from one of the components already available. Most of the Kamelets available in the official catalog are simple ones that contain only a remapping of the Kamelet properties into Camel endpoint parameters.

Consider the following example, to provide a Kamelet that allows you to search data on Twitter, providing a stream of information about a given keyword. To create such a Kamelet, you can use the options of the "camel-twitter" component without any rectification.

  1. To write a simple Kamelet, start building a new Kamelet resource using the kamel CLI: 

    kamel init twitter-search-source.kamelet.yaml

    This produces a YAML file like the following :

    twitter-search-source.kamelet.yaml

    apiVersion: camel.apache.org/v1alpha1
kind: Kamelet
metadata:
  name: twitter-search-source
  labels:
    camel.apache.org/kamelet.type: "source"
spec:
  definition:
    title: "Timer"
    description: "Produces periodic events with a custom payload"
    required:
      - message
    properties:
      period:
        title: Period
        description: The time interval between two events
        type: integer
        default: 1000
      message:
        title: Message
        description: The message to generate
        type: string
  types:
    out:
      mediaType: text/plain
  template:
    from:
      uri: timer:tick
      parameters:
        period: "{{period}}"
      steps:
        - set-body:
            constant: "{{message}}"
        - to: "kamelet:sink"

  2. Change the file to create a route that searches a given keyword on Twitter.

    The route provided in the initial scaffold (timer-to-log) is inaccurate, so change it to the following:

    twitter-search-source.kamelet.yaml

    apiVersion: camel.apache.org/v1alpha1
kind: Kamelet
# ...
spec:
# ...
  template:
    from:
      uri: "twitter-search:{{keywords}}" (1)
      parameters:
        accessToken: "{{accessToken}}" (2)
        accessTokenSecret: "{{accessTokenSecret}}"
        consumerKey: "{{apiKey}}" (3)
        consumerSecret: "{{apiKeySecret}}"
      steps:
      - marshal: (4)
          json: {}
      - to: "kamelet:sink" (5)

  3. keywords is a path parameter in Camel Twitter-search. Some endpoint parameters are just mapped 1-1. The Camel component consumerKey is named apiKey to reflect the actual name in the Twitter developer portal.
  4. The Camel Twitter component generates Java objects, you must marshal them to JSON. A Source Kamelet sends data to the special endpoint "kamelet:sink", which is replaced at runtime by a different target.

  5. The YAML route template above uses the twitter-search component to search on Twitter. You added a marshaling step to JSON because the output of a Kamelet must have a value to transfer over the wire. To complete the Kamelet, you must document the parameters in a JSON schema format. It is specified in the spec definition part:

    twitter-search-source.kamelet.yaml

    apiVersion: camel.apache.org/v1alpha1
kind: Kamelet
metadata:
  name: twitter-search-source
# ...
spec:
  definition:
    title: "Twitter Search Source" (1)
    description: |-
      Allows to get all tweets on particular keywords from Twitter.

      It requires tokens that can be obtained by creating an application
      in the Twitter developer portal: https://developer.twitter.com/.
    required: (2)
    - keywords
    - apiKey
    - apiKeySecret
    - accessToken
    - accessTokenSecret
    properties:
      keywords: (3)
        title: Keywords
        description: The keywords to use in the Twitter search (Supports Twitter standard operators)
        type: string
        example: "Apache Camel"
      apiKey:
        title: API Key
        description: The API Key from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password (4)
      apiKeySecret:
        title: API Key Secret
        description: The API Key Secret from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
      accessToken:
        title: Access Token
        description: The Access Token from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
      accessTokenSecret:
        title: Access Token Secret
        description: The Access Token Secret from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
# ...

General information about the Kamelet in textual format:

  1. List of required parameters to create a Kamelet.
  2. A specification for each one of the parameters (flat structure, no nested options allowed)

  3. Optional graphical customization for a specific UI (OpenShift Console)

    The final Kamelet looks like the following:

    twitter-search-source.kamelet.yaml

    apiVersion: camel.apache.org/v1alpha1
kind: Kamelet
metadata:
  name: twitter-search-source
  annotations:
    camel.apache.org/kamelet.icon: "data:image/svg+xml;base64,..." # Truncated
    camel.apache.org/provider: "Apache Software Foundation"
  labels:
    camel.apache.org/kamelet.type: "source"
    camel.apache.org/kamelet.group: "Twitter"
spec:
  definition:
    title: "Twitter Search Source"
    description: |-
      Allows to get all tweets on particular keywords from Twitter.

      It requires tokens that can be obtained by creating an application
      in the Twitter developer portal: https://developer.twitter.com/.
    required:
    - keywords
    - apiKey
    - apiKeySecret
    - accessToken
    - accessTokenSecret
    properties:
      keywords:
        title: Keywords
        description: The keywords to use in the Twitter search (Supports Twitter standard operators)
        type: string
        example: "Apache Camel"
      apiKey:
        title: API Key
        description: The API Key from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
      apiKeySecret:
        title: API Key Secret
        description: The API Key Secret from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
      accessToken:
        title: Access Token
        description: The Access Token from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
      accessTokenSecret:
        title: Access Token Secret
        description: The Access Token Secret from the Twitter application in the developer portal
        type: string
        format: password
        x-descriptors:
        - urn:alm:descriptor:com.tectonic.ui:password
  types:
    out:
      mediaType: application/json
  template:
    from:
      uri: "twitter-search:{{keywords}}"
      parameters:
        accessToken: "{{accessToken}}"
        accessTokenSecret: "{{accessTokenSecret}}"
        consumerKey: "{{apiKey}}"
        consumerSecret: "{{apiKeySecret}}"
      steps:
      - marshal:
          json: {}
      - to: "kamelet:sink"

    You can use the Kamelet shared on the Catalog and or created on a OpenShift cluster.

Example:

Apply on a cluster together with a simple binding.

  1. You must enable the Openshift cluster and connect to a namespace for the camel K operator to act.

  2. Create the Kamelet. 

    kubectl apply -f twitter-search-source.kamelet.yaml

  3. Create a binding as shown in the following example:

    twitter-search-source-binding.yaml`

    apiVersion: camel.apache.org/v1alpha1
kind: KameletBinding
metadata:
  name: twitter-search-source-binding
spec:
  source:
    ref:
      kind: Kamelet
      apiVersion: camel.apache.org/v1alpha1
      name: twitter-search-source
    properties:
      keywords: "Apache Camel"
      apiKey: "your own"
      apiKeySecret: "your own"
      accessToken: "your own"
      accessTokenSecret: "your own"
  sink:
    uri: "log:info"

  4. This can be created using: 

    kubectl apply -f twitter-search-source-binding.yaml

  5. Once created, you can see the logs of the binding using: 

    kamel logs twitter-search-source-binding
  6. After executing the above steps, you must get a few tweets in the logs after the integration is created.
  7. For more information on how to use it in different contexts (like Knative, Kafka, etc) see Kamelets User Guide.

5.2. Customizing an existing Kamelet catalog

This is an example to customize an existing kamelet catalog.

  1. Goal: Adding "groupId" option to the Kafka source kamelet.

    • Current version kafka source kamelet contains an option "groupId". Following example does not contain the "groupId".
    • Through this section, you must add "groupId" option to the existing kamelet catalog.

  2. Customize Kamelet:

    • Get the original file.

      https://access.redhat.com/documentation/en-us/red_hat_build_of_apache_camel_k/1.10/html/kamelets_reference/kafka-source#kamelet_source_file_44

    • Define the new Kamelet option

      • Add the information about the new option "consumerGroup" under 

        spec:
  definition:
    properties:

      • The contents of the definition would be similar to the following: 

        consumerGroup:
    title: Consumer Group
    description: A string that uniquely identifies the group of consumers to which this source belongs
    type: string
    example: "my-group-id"

    • Map the new kamelet option with camel-kafka component’s groupId option

      • We must define which camel-kafka component option is set by "consumerGroup" under: 

        template:
  from:
    parameters:

      • The contents of the definition are as follows: 

        groupId: "\{{?consumerGroup}}"

  3. Code: 

    spec:
  definition:
    description: Receive data from Kafka topics.
    properties:
~skip~
      consumerGroup:
        title: Consumer Group
        description: A string that uniquely identifies the group of consumers to which this source belongs
        type: string
        example: "my-group-id"
~skip~
  template:
    from:
      parameters:
        allowManualCommit: '{{allowManualCommit}}'
        autoCommitEnable: '{{autoCommitEnable}}'
        autoOffsetReset: '{{autoOffsetReset}}'
        brokers: '{{?bootstrapServers}}'
        pollOnError: '{{pollOnError}}'
        saslJaasConfig: org.apache.kafka.common.security.plain.PlainLoginModule required username='{{user}}' password='{{password}}';
        saslMechanism: '{{saslMechanism}}'
        securityProtocol: '{{securityProtocol}}'
        groupId: "{{?consumerGroup}}"
        consumersCount: "{{consumersCount}}"
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.