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
commit 4b4b56efdee01205fbce6bb94aaae36ad31846c2 Author: Pasquale Congiusti <[email protected]> AuthorDate: Fri Sep 15 11:48:02 2023 +0200 chore(doc): kamelet distribution model Closes #1576 --- docs/modules/ROOT/nav-end.adoc | 2 ++ .../ROOT/pages/kamelets/kamelets-distribution.adoc | 21 ++++++++++++ .../modules/ROOT/pages/kamelets/kamelets-user.adoc | 39 +--------------------- docs/modules/ROOT/pages/kamelets/kamelets.adoc | 32 +++++++++++++++--- 4 files changed, 52 insertions(+), 42 deletions(-) diff --git a/docs/modules/ROOT/nav-end.adoc b/docs/modules/ROOT/nav-end.adoc index 3ce7e1317..1f1b100ad 100644 --- a/docs/modules/ROOT/nav-end.adoc +++ b/docs/modules/ROOT/nav-end.adoc @@ -3,8 +3,10 @@ ** xref:troubleshooting/operating.adoc[Operating] ** xref:troubleshooting/known-issues.adoc[Known Issues] * xref:kamelets/kamelets.adoc[Kamelets] +** xref:kamelets/kamelets-distribution.adoc[Distribution] ** xref:kamelets/kamelets-user.adoc[User Guide] ** xref:kamelets/kamelets-dev.adoc[Developer Guide] +** xref:kamelets/kameletbindings-error-handler.adoc[Error Handling] * xref:architecture/architecture.adoc[Architecture] ** xref:architecture/operator.adoc[Operator] *** xref:architecture/cr/integration-platform.adoc[IntegrationPlatform] diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-distribution.adoc b/docs/modules/ROOT/pages/kamelets/kamelets-distribution.adoc new file mode 100644 index 000000000..617039bc3 --- /dev/null +++ b/docs/modules/ROOT/pages/kamelets/kamelets-distribution.adoc @@ -0,0 +1,21 @@ +[[kamelets-distribution]] += Kamelets Distribution + +When you install Camel K, you typically got bundled a series of Kamelets which are coming from the xref:camel-kamelets::index.adoc[Apache Kamelet Catalog]. This is a facility that will let you immediately use a wide set of connector-style resources to interact with any event source and sink. + +NOTE: the version we bundle depends directly on the default Camel version used. For instance, in Camel K version 2, the default runtime we use is Camel K Runtime 2.16.0 which depends on Camel version 3.20.1. The Kamelet version we use is the one distributed as link:https://github.com/apache/camel-kamelets/releases/tag/v3.20.1.1[v3.20.1]. + +As development of Kamelet is very fast, make sure to use some version which is compatible with the Camel runtime you're going to use. + +[[kamelets-own-catalog]] +== Provide your own catalog + +An alternative to the catalog we bundle is to include a repository containing your own catalog. You need to specify it in the IntegrationPlatform `.spec.kamelet.repository`. + +However, we have a simple command in our CLI which takes care of it: +``` +kamel kamelet add-repo <git-platform>:<owner>/<repo>[/path_to_kamelets_folder][@version] +``` +Mind that `<git-platform>` is the repository of your choice, for instance `github` and `[@version]` is the tag to use (by default it will use `main` branch). + +With this approach you can dynamically include any repository where your Kamelets are hosted. They will be lazily initialized as soon as they are required by any of the Integration or Pipes which will make use of them. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc index 18cb23a10..cdb00a68f 100644 --- a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc +++ b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc @@ -1,41 +1,4 @@ -[[kamelets]] -= Kamelets - -[[kamelets-introduction]] -== Introduction - -Kamelets (**Kamel** route snipp**ets**) are a new concept introduced in Camel K that allow users to connect to external systems via a simplified interface, -hiding all the low level details about how those connections are implemented. - -A Kamelet can act as *"source"* of data or alternatively as *"sink"*: a source allows to consume data from an external system, -while a sink can let you send data to an external system or execute a particular action and get a result. - -For example, a "twitter-stream" Kamelet may allow a user to consume all tweets containing a specified keyword. -Another Kamelet "twitter-post" may allow the user to publish some data as a tweet. -Those are simple examples: experienced Camel developers know how to map those Kamelets into Camel endpoint URIs directly. -But, in general, a Kamelet is not expected to map 1:1 a Camel component. Kamelets are **route templates**, so they can be much more complex. - -Being made of **pure Camel DSL**, Kamelets can embody all the logic that allows to consume or produce data from public SaaS or -enterprise systems and only expose to the final users a clean interface that describes **the expected parameters, input and output**: just like an OpenAPI spec. - -For example, a "store-orders" Kamelet may be used to consume all events related to orders created in a customer enterprise system. -The **Kamelet's interface** will define what parameters should be provided (e.g. filters on the type of order) and what's the expected datashape of the produced events. -**Internally**, the Kamelet defines how such events will be generated: it may involve connections to multiple systems using different protocols, transformations and so on. -But everything will be **hidden to the end user**. - -Kamelets are the fundamental **unit of abstraction** in the next-gen architecture of Apache Camel K. -A system as a whole can be technically described as the set of operations that you can do with it: -if you use the language of Kamelets to describe a specific system, then other users can have access to all those operations with ease, -no matter how complicated is the internal logic underlying all those operations. -Comparing it to the classical way of using Apache Camel, where developers used to write complex routes (containing both high-level and low-level details) -to integrate systems, the Kamelet model tends to reduce the complexity by encapsulating low-level details into reusable components. - -Kamelets are also expected to be **rendered on visual tools** that will provide additional value to the end users. -They are generic connectors that can be used in multiples ways, depending on the context, so each UIs can use them -for its own purpose. - -[[kamelets-example]] -== Kamelet Example += Kamelets user guide Speaking technically, a Kamelet is a resource that can be installed on any Kubernetes cluster. The following is an example of Kamelet that we'll use to discuss the various parts: diff --git a/docs/modules/ROOT/pages/kamelets/kamelets.adoc b/docs/modules/ROOT/pages/kamelets/kamelets.adoc index d908064f6..a9f97ce3a 100644 --- a/docs/modules/ROOT/pages/kamelets/kamelets.adoc +++ b/docs/modules/ROOT/pages/kamelets/kamelets.adoc @@ -1,8 +1,32 @@ [[kamelets]] = Kamelets -This section of the documentation contains information about Kamelets from both a user and a developer point of view: +Kamelets (**Kamel** route snipp**ets**) are a concept originally introduced in Camel K and later moved into Camel core. It allows users to connect to external systems via a simplified interface, hiding all the low level details about how those connections are implemented. -- The xref:kamelets/kamelets-user.adoc[Kamelets User Guide] is for users that want to use Kamelets for connecting systems with their applications -- The xref:kamelets/kameletbindings-error-handler.adoc[Pipes Error Handler User Guide] explains how to configure an error handler on a `Pipe` -- The xref:kamelets/kamelets-dev.adoc[Kamelets Developer Guide] is a reference for developers that want to create new Kamelets and share them with users +A Kamelet can act as *"source"* of data or alternatively as *"sink"*: a source allows to consume data from an external system, while a sink can let you send data to an external system or execute a particular action and get a result. + +For example, a "twitter-stream" Kamelet may allow a user to consume all tweets containing a specified keyword. +Another Kamelet "twitter-post" may allow the user to publish some data as a tweet. +Those are simple examples: experienced Camel developers know how to map those Kamelets into Camel endpoint URIs directly. +But, in general, a Kamelet is not expected to map 1:1 a Camel component. Kamelets are **route templates**, so they can be much more complex. + +Being made of **pure Camel DSL**, Kamelets can embody all the logic that allows to consume or produce data from public SaaS or +enterprise systems and only expose to the final users a clean interface that describes **the expected parameters, input and output**: just like an OpenAPI spec. + +For example, a "store-orders" Kamelet may be used to consume all events related to orders created in a customer enterprise system. +The **Kamelet's interface** will define what parameters should be provided (e.g. filters on the type of order) and what's the expected datashape of the produced events. +**Internally**, the Kamelet defines how such events will be generated: it may involve connections to multiple systems using different protocols, transformations and so on. +But everything will be **hidden to the end user**. + +Kamelets are the fundamental **unit of abstraction** in the next-gen architecture of Apache Camel K. +A system as a whole can be technically described as the set of operations that you can do with it: +if you use the language of Kamelets to describe a specific system, then other users can have access to all those operations with ease, +no matter how complicated is the internal logic underlying all those operations. +Comparing it to the classical way of using Apache Camel, where developers used to write complex routes (containing both high-level and low-level details) +to integrate systems, the Kamelet model tends to reduce the complexity by encapsulating low-level details into reusable components. + +Kamelets are also expected to be **rendered on visual tools** that will provide additional value to the end users. +They are generic connectors that can be used in multiples ways, depending on the context, so each UIs can use them +for its own purpose. + +Have a look at the xref:kamelets/kamelets-user.adoc[Kamelets User Guide] to learn how to immediately use Kamelets in Camel K or check xref:kamelets/kamelets-distribution.adoc[Distribution][how to use your own Kamelet catalog].
