Release v0.2.0
51 files changed
tree: 66dc71e8ee846d04686254405d9e3956dbdeb064
  1. .asf.yaml
  2. .github/
  3. .gitignore
  4. Jenkinsfile
  5. KEYS
  6. LICENSE
  7. NOTICE
  8. README.md
  9. aws-ddb-streams-source.kamelet.yaml
  10. aws-kinesis-firehose-sink.kamelet.yaml
  11. aws-kinesis-source.kamelet.yaml
  12. aws-lambda-sink.kamelet.yaml
  13. aws-s3-sink.kamelet.yaml
  14. aws-s3-source.kamelet.yaml
  15. aws-sns-fifo-sink.kamelet.yaml
  16. aws-sns-sink.kamelet.yaml
  17. aws-sqs-fifo-sink.kamelet.yaml
  18. aws-sqs-sink.kamelet.yaml
  19. aws-sqs-source.kamelet.yaml
  20. azure-eventhubs-sink.kamelet.yaml
  21. azure-eventhubs-source.kamelet.yaml
  22. azure-storage-blob-sink.kamelet.yaml
  23. azure-storage-blob-source.kamelet.yaml
  24. azure-storage-queue-sink.kamelet.yaml
  25. bitcoin-source.kamelet.yaml
  26. cron-source.kamelet.yaml
  27. docs/
  28. dropbox-sink.kamelet.yaml
  29. dropbox-source.kamelet.yaml
  30. earthquake-source.kamelet.yaml
  31. fhir-source.kamelet.yaml
  32. file-watch-source.kamelet.yaml
  33. ftp-source.kamelet.yaml
  34. ftps-source.kamelet.yaml
  35. github-source.kamelet.yaml
  36. google-calendar-source.kamelet.yaml
  37. google-mail-source.kamelet.yaml
  38. google-sheets-source.kamelet.yaml
  39. http-sink.kamelet.yaml
  40. http-source.kamelet.yaml
  41. jira-source.kamelet.yaml
  42. kafka-source.kamelet.yaml
  43. mail-imap-source.kamelet.yaml
  44. minio-sink.kamelet.yaml
  45. minio-source.kamelet.yaml
  46. mqtt-source.kamelet.yaml
  47. nats-source.kamelet.yaml
  48. pdf-action.kamelet.yaml
  49. rabbitmq-source.kamelet.yaml
  50. salesforce-source.kamelet.yaml
  51. script/
  52. sftp-source.kamelet.yaml
  53. slack-source.kamelet.yaml
  54. ssh-source.kamelet.yaml
  55. telegram-sink.kamelet.yaml
  56. telegram-source.kamelet.yaml
  57. test/
  58. timer-source.kamelet.yaml
  59. twitter-directmessage.kamelet.yaml
  60. twitter-search.kamelet.yaml
  61. twitter-timeline.kamelet.yaml
  62. webhook-source.kamelet.yaml
README.md

Apache Camel - Kamelet Catalog

This repository contains the default Kamelet catalog used by Apache Camel and its sub-projects.

Kamelets in this repository can be used natively in Apache Camel K integrations, without additional configuration steps: users just need to reference the Kamelets by name in the URI (e.g. kamelet:timer-source?message=Hello), or use them in a KameletBinding.

NOTE: Camel K (and other sub-projects) will only use a specific version of this Kamelet catalog. Refer to the release notes of the sub-project for more information.

Documents and guides about Kamelets can be found in the Kamelets User and Developer Guides.

Guidelines for contributions

Kamelets in this repository are intended to be generic connectors that any external platform can embed in order to leverage the Apache Camel integration capabilities.

All Kamelets posted here will be subject to the scrutiny of the Apache Camel PMC to assess their compliance with the ecosystem and, in any case, they MUST be in line with the general Apache Code of Conduct.

General Format

Kamelets MUST be provided in the Kubernetes YAML format, i.e. they MUST be resources that can be applied on a cluster using the Kubernetes kubectl CLI.

The file name of each Kamelet MUST follow this specific pattern: <kamelet-name>.kamelet.yaml. The <kamelet-name> MUST match field metadata -> name inside the Kamelet YAML.

For the time being, we'll accept only two kind of Kamelets:

  • Sources: Kamelets producing data that can be forwarded to any chosen destination. In the Camel jargon, a source can be used consumer-side. Kamelets belonging to this category MUST be marked with label: camel.apache.org/kamelet.type=source.
  • Sinks: Kamelets that accept data with a specific datashape and forward it to an external system. In the Camel jargon, a sink can be used producer-side. Kamelets belonging to this category MUST be marked with label: camel.apache.org/kamelet.type=sink.

All Kamelets MUST provide a value for label camel.apache.org/kamelet.type.

All Kamelets MUST declare an icon in the camel.apache.org/kamelet.icon annotation using the embedded URL data:image format. An icon annotation CANNOT contain a link to an external location. A Kamelet SHOULD use the specific data:image/svg+xml;base64 format whenever it's possible.

Kamelets that are logically related (e.g. all Kamelets that allow doing things with Twitter) SHOULD be linked together using the label camel.apache.org/kamelet.group=<name of the group> (e.g. camel.apache.org/kamelet.group=Twitter) to ease visualization in tooling.

All Kamelets present in this repository MUST have the annotation camel.apache.org/provider set to "Apache Software Foundation".

We provide an example of Kamelet to give more context to the following sections:

apiVersion: camel.apache.org/v1alpha1
kind: Kamelet
metadata:
  name: timer-source
  annotations:
    camel.apache.org/kamelet.icon: data:image/svg+xml;base64,PD94...
    camel.apache.org/provider: "Apache Software Foundation"
  labels:
    camel.apache.org/kamelet.type: source
spec:
  definition:
    title: Timer Source
    description: Produces periodic events with a custom payload
    required:
      - message
    properties:
      period:
        title: Period
        description: The interval between two events in milliseconds
        type: integer
        default: 1000
      message:
        title: Message
        description: The message to generate
        type: string
        example: hello world
  types:
    out:
      mediaType: text/plain
  flow:
    from:
      uri: timer:tick
      parameters:
        period: "{{period}}"
      steps:
        - set-body:
            constant: "{{message}}"
        - to: kamelet:sink

Flow Code

The Camel route that defines the behavior of the Kamelet MUST be provided in YAML flow syntax. The Kamelet MAY declare additional supporting routes that MUST be written in YAML syntax (to provide better support in all Camel subprojects).

The code of a “source” Kamelet must send data to the kamelet:sink special endpoint. The code of a “sink” Kamelet must consume data from the special endpoint kamelet:source.

The Kamelet MAY declare dependencies on Camel components using the syntax camel:<component-name> (e.g. camel:telegram). Some Camel dependencies are implicitly added by the runtime when a certain Camel URI is used (e.g. there's no need to declare explicit dependency on camel:timer if the flow section uses the timer URI).

The Kamelet CAN declare dependencies on artifacts of one of the Camel subprojects. In case it does, the Kamelet must contain label camel.apache.org/requires.runtime=<name-of-the-project> (e.g. camel.apache.org/requires.runtime=camel-quarkus).

The Kamelet CAN declare dependencies on other artifacts in Maven Central, provided that they are released with a license compatible with Apache License 2.0 (syntax is mvn:group:artifact:version).

All source code dependencies (e.g. github:organization:project) MUST link to Apache Camel repositories only. Contributors are welcome to use this same repository to share libraries in the form of source code.

All these should be added to the spec -> dependencies section, like in the following example:

# ...
spec:
  # ...
  dependencies:
  - camel:telegram
  - mvn:org.apache.commons:commons-vfs2:2.7.0
  - github:apache/camel-kamelets
  flow:
    # ...

Configuration properties

Kamelets SHOULD declare their configuration properties in the spec -> definition section as a JSON-schema specification.

The top-level part of the JSON-schema document refer to the Kamelet itself, so the following properties are MANDATORY:

  • title: the visual name of the Kamelet
  • description: a detailed description of what the Kamelet is useful for

The properties part can then contain a set of configuration properties available for the Kamelet.

Property name id is reserved and implicit for all Kamelets.

Data Types

Kamelets SHOULD declare the mediaType of data that they produce or consume when it's known in advance. If technically possible, they SHOULD also indicate the schema of the corresponding data.

Kamelets MAY choose not to declare a mediaType when it varies depending on the configuration of the parameters. Contributors MAY consider to split a Kamelet into multiple instances if that can help determining unique types and schemas.

Testing

Kamelets SHOULD be accompained with testing code that verifies their correct behavior.

Yaks is the testing framework of choice for Kamelets and the one implemented in the CI.

Test code must be submitted in the test/<kamelet-name>/ directory in the root of this repository.

Kamelets submitted with tests that verify their correctness MUST be labeled with camel.apache.org/kamelet.verified=true.

NOTE: there‘s no way at the moment to inject credentials for external systems into the CI in order to write more advanced tests, but we can expect we’ll find an usable strategy in the long run