davsclaus commented on a change in pull request #1: URL: https://github.com/apache/camel-kamelets/pull/1#discussion_r571942138
########## File path: README.md ########## @@ -1,6 +1,126 @@ -# Apache Camel - Kamelet Repository +# Apache Camel - Kamelet Catalog -This repository contains the default catalog of Kamelet definitions that can be used with Apache Camel and its sub-projects. +This repository contains the default Kamelet catalog used by Apache Camel and its sub-projects. -More information about Kamelets can be found in the [Apache Camel K documentation](https://camel.apache.org/camel-k/latest/kamelets/kamelets.html). +Kamelets in this repository can be used natively in [Apache Camel K](https://github.com/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 [Apache Camel K documentation](https://camel.apache.org/camel-k/latest/kamelets/kamelets.html). + +## 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](https://www.apache.org/foundation/policies/conduct.html). + +### 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. + +We provide an example of Kamelet to give more context to the following sections: + +```yaml +apiVersion: camel.apache.org/v1alpha1 +kind: Kamelet +metadata: + name: timer-source + annotations: + camel.apache.org/kamelet.icon: data:image/svg+xml;base64,PD94... + 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 + 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 **CAN** declare dependencies on Camel components using the syntax `camel:<component-name>` (e.g. `camel:telegram`). Review comment: For these CAN it would be good to have an example showing that, eg can we add another out of the box kamelet that does that. Also the timer kamelet does not declare that it uses camel:timer ########## File path: README.md ########## @@ -1,6 +1,126 @@ -# Apache Camel - Kamelet Repository +# Apache Camel - Kamelet Catalog -This repository contains the default catalog of Kamelet definitions that can be used with Apache Camel and its sub-projects. +This repository contains the default Kamelet catalog used by Apache Camel and its sub-projects. -More information about Kamelets can be found in the [Apache Camel K documentation](https://camel.apache.org/camel-k/latest/kamelets/kamelets.html). +Kamelets in this repository can be used natively in [Apache Camel K](https://github.com/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 [Apache Camel K documentation](https://camel.apache.org/camel-k/latest/kamelets/kamelets.html). + +## 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](https://www.apache.org/foundation/policies/conduct.html). + +### 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. Review comment: Yes SVG icons are the best. I wonder if we have any way of previewing those icons from a PR. Or some hint. Maybe you can just copy that base64 into some online service that can render it. And do we have a generic base64 icon for camel itself? But I would of course like to see specific icons per kamelet so they use twitter, telegram, salesforce logos/icons etc. But finding svg icons can sometime be tricky. You may have a bitmap icon, and if you convert that to SVG then it gets very bloated and big. So to find a natural clean svg icon is not always easy ########## File path: README.md ########## @@ -1,6 +1,126 @@ -# Apache Camel - Kamelet Repository +# Apache Camel - Kamelet Catalog -This repository contains the default catalog of Kamelet definitions that can be used with Apache Camel and its sub-projects. +This repository contains the default Kamelet catalog used by Apache Camel and its sub-projects. -More information about Kamelets can be found in the [Apache Camel K documentation](https://camel.apache.org/camel-k/latest/kamelets/kamelets.html). +Kamelets in this repository can be used natively in [Apache Camel K](https://github.com/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 [Apache Camel K documentation](https://camel.apache.org/camel-k/latest/kamelets/kamelets.html). + +## 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](https://www.apache.org/foundation/policies/conduct.html). + +### 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. + +We provide an example of Kamelet to give more context to the following sections: + +```yaml +apiVersion: camel.apache.org/v1alpha1 +kind: Kamelet +metadata: + name: timer-source + annotations: + camel.apache.org/kamelet.icon: data:image/svg+xml;base64,PD94... + 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 Review comment: (in milli seconds) ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
