You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by nf...@apache.org on 2020/08/10 14:23:31 UTC
[camel-k] branch master updated: chore(doc): document sinkbinding
in the context of sources and Kamelets
This is an automated email from the ASF dual-hosted git repository.
nferraro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git
The following commit(s) were added to refs/heads/master by this push:
new 6a03754 chore(doc): document sinkbinding in the context of sources and Kamelets
6a03754 is described below
commit 6a03754341c32b23e34cd6906f982fb420b717df
Author: nicolaferraro <ni...@gmail.com>
AuthorDate: Mon Aug 10 16:14:43 2020 +0200
chore(doc): document sinkbinding in the context of sources and Kamelets
---
.../architecture/camel-k-sources-diagram.png | Bin 0 -> 27721 bytes
docs/modules/ROOT/nav.adoc | 1 +
.../ROOT/pages/architecture/architecture.adoc | 6 +-
.../ROOT/pages/architecture/cr/camel-catalog.adoc | 2 +-
docs/modules/ROOT/pages/architecture/sources.adoc | 88 +++++++++++++++++++++
5 files changed, 95 insertions(+), 2 deletions(-)
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-sources-diagram.png b/docs/modules/ROOT/assets/images/architecture/camel-k-sources-diagram.png
new file mode 100644
index 0000000..edaedb8
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-sources-diagram.png differ
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 47563a4..c5afcc6 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -27,6 +27,7 @@
*** xref:architecture/cr/camel-catalog.adoc[CamelCatalog]
** xref:architecture/runtime.adoc[Runtime]
** xref:architecture/traits.adoc[Traits]
+** xref:architecture/sources.adoc[Sources]
* Observability
** xref:observability/monitoring.adoc[Monitoring]
* xref:traits:traits.adoc[Traits]
diff --git a/docs/modules/ROOT/pages/architecture/architecture.adoc b/docs/modules/ROOT/pages/architecture/architecture.adoc
index b98c107..8d5dd11 100644
--- a/docs/modules/ROOT/pages/architecture/architecture.adoc
+++ b/docs/modules/ROOT/pages/architecture/architecture.adoc
@@ -4,8 +4,12 @@
image::architecture/camel-k.jpg[Overview]
-The *Camel K* platform is based on three concepts:
+The *Camel K* core platform is based on three concepts:
1. The xref:architecture/operator.adoc[Operator] which is the intelligence that coordinates all the moving parts.
2. The xref:architecture/runtime.adoc[Runtime] which provides the functionnality to run the integration.
3. The xref:architecture/traits.adoc[Traits] through wich the behavior of the operator and the runtime can be customized.
+
+For information on how *Camel K* is able to provide *Sources* e.g. for the Knative platform:
+
+- The xref:architecture/sources.adoc[Sources] page describes how sources are internally materialized.
diff --git a/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc b/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
index 37a373f..e05cc5a 100644
--- a/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
+++ b/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
@@ -1,7 +1,7 @@
[[camel-catalog]]
= CamelCatalog
-The*CamelCatalog* is a static side resources that provides metadata related to the what it is included in the xref:architecture/runtime.adoc[Runtime] in term of Camel components, languages, dataformats and what capabilities are prvided.
+The *CamelCatalog* is a static side resources that provides metadata related to the what it is included in the xref:architecture/runtime.adoc[Runtime] in term of Camel components, languages, dataformats and what capabilities are prvided.
[NOTE]
====
diff --git a/docs/modules/ROOT/pages/architecture/sources.adoc b/docs/modules/ROOT/pages/architecture/sources.adoc
new file mode 100644
index 0000000..90f92a1
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/sources.adoc
@@ -0,0 +1,88 @@
+[[sources]]
+= Sources
+
+WARNING: This document describes features that will be
+*available in Camel K 1.2.x* (not released at the time of writing: August 08, 2020)
+
+One of the goals of Camel K is to provide connectors that can be easily installed on any Kubernetes cluster and
+used when needed to provide data to internal services or publish data outside, without requiring any in-depth knowledge about Apache Camel from the end-users.
+
+Knative Sources fall into this category, but in general, sources described here can be used with any underlying technology.
+
+NOTE: https://knative.dev/docs/eventing/samples/apache-camel-source/[Knative CamelSources] are a community effort to provide specific sources for Knative.
+What we describe in this document is a more general approach that is alternative to Knative CamelSources and aims to supersede them.
+
+== Sources Design
+
+The following diagram shows how sources are materialized from their elementary building blocks.
+
+image::architecture/camel-k-sources-diagram.png[Next-gen Sources diagram]
+
+=== Kamelets as Abtract Sources
+
+In the context of sources, *Kamelets* play the role of abstract sources that can be materialized once the user provides values for all
+mandatory parameters contained in the Kamelet specification.
+
+What follows is a simple Kamelet that can produce periodic events with a specified payload:
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: Kamelet
+metadata:
+ name: timer
+spec:
+ definition:
+ title: "Timer"
+ description: "Produces periodic events with a custom payload"
+ required:
+ - message
+ properties:
+ payload: # <1>
+ title: Payload
+ description: The message to generate as payload of each Cloudevent
+ type: string
+ # continues with the flow declaration
+ # ...
+----
+<1> The definition of the `payload` property
+
+The Kamelet contains the definition of all properties in JSON Schema format. In this example, there's only a single property named `payload`.
+
+A Kamelet does nothing when created on a cluster, but it can be used later to create sources, as explained in the remainder of this document.
+
+=== Integration: binding a Kamelet to a destination
+
+An integration can be used to bind a Kamelet to a destination, providing values for all the Kamelet parameters.
+
+For example, the following integration binds the `timer` Kamelet to the Knative *InMemoryChannel* named `mychannel`:
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Integration
+metadata:
+ name: timer-source
+spec:
+ flows:
+ - from:
+ uri: kamelet:timer # <1>
+ parameters:
+ payload: "Hello World" # <2>
+ steps:
+ - to: knative:channel/mychannel?apiVersion=messaging.knative.dev/v1beta1&kind=InMemoryChannel # <3>
+----
+<1> Reference to the Kamelet named `timer`
+<2> Value for the `payload` required property (and others, if present)
+<3> Destination of the generated events
+
+When binding a Kamelet to a single (fully specified) Knative destination, Camel K does not attempt to do any binding,
+instead it delegates the actual mapping to a Knative *SinkBinding* resource.
+
+The **SinkBinding** intercepts the creation of the Deployment containing the integration specification, to inject the
+exact coordinates of the destination (in the example, of the InMemoryChannel named `mychannel`).
+This mechanism works also if the integration is materialized into a Knative Serving Service or into a CronJob, not only if a
+standard Deployment is used.
+
+The SinkBinding resource is also interpreted at Knative level as a standard source, so the `kn` CLI is able to properly recognize
+it. UI tools based on Knative, e.g. the OpenShift console, should also be able to display it as a standard source.