This is an automated email from the ASF dual-hosted git repository. astefanutti pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 93245fd35c7a118d35ee9fc9369956c2838bddf6 Author: Christoph Deppisch <[email protected]> AuthorDate: Tue Jun 14 12:15:30 2022 +0200 Fix #2177: Update docs --- docs/modules/ROOT/pages/architecture/operator.adoc | 21 +++++++++++++-- .../ROOT/pages/installation/advanced/multi.adoc | 31 +++++++++++++++------- 2 files changed, 41 insertions(+), 11 deletions(-) diff --git a/docs/modules/ROOT/pages/architecture/operator.adoc b/docs/modules/ROOT/pages/architecture/operator.adoc index 6a980a789..252487f21 100644 --- a/docs/modules/ROOT/pages/architecture/operator.adoc +++ b/docs/modules/ROOT/pages/architecture/operator.adoc @@ -21,7 +21,7 @@ The Camel K Operator defines a number of new Kubernetes API through the https:// All the api conform to the Kubernetes https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md[api conventions]. -To manage the interaction with them, a simple control loop was not enough and we ended up with a sort of “Hierarchical Operator Pattern” where the reconcile phase may trigger other controllers and supervises them. +To manage the interaction with them, a simple control loop was not enough. So we ended up with a sort of “Hierarchical Operator Pattern” where the reconcile phase may trigger other controllers and supervises them. image::architecture/camel-k-operator-control-loop.png[control-loop] @@ -31,7 +31,7 @@ With the exception of the `CamelCatalog`, each CR has a dedicated state machine image::architecture/camel-k-state-machine-basic.png[State Machine] -Each state of the CR is handled by a dedicated handler, named `Action`, defined as follow: +Each state of the CR is handled by a dedicated handler, named `Action`, defined as follows: [source,go] ---- @@ -47,3 +47,20 @@ type Action interface { ==== Since the go language does not yet support generics, there is an `Action` definition per CR, The full list of definitions can be found in the https://github.com/apache/camel-k/tree/main/pkg/controller[controller package] ==== + +== Operator resource mapping + +By default the Camel K operator (global mode) will manage all Camel K resources on the cluster doing the reconciliation loops for the resources in order to apply the mentioned state machine. + +For clusters with multiple Camel K tenants this approach is not going to work as user groups may want to separate the workloads with respective +authentication and authorization schemes. For multi tenancy the Camel K operator uses an operator id that can be applied to resources in the form of +an annotation. The annotation selects the operator that should handle the resource. + +This approach allows multiple Camel K installations and operators on the same cluster with each operator handling an explicit set of Camel K resources identified +by the operator id. + +By default the Camel K operator has the id `camel-k` and users with only one single installation on the cluster will not even notice the existence of this identifier. When an administrator wants to add more Camel K operator installations to the cluster the +operator id needs to be unique and resources should be annotated with the respective annotation `camel.apache.org/operator.id={operator-id}`. With this approach we make sure that only one single operator installation manages +a resource at a time. + +Read more about this topic in xref:installation/advanced/multi.adoc[Multiple Operators and Selective Upgrades] diff --git a/docs/modules/ROOT/pages/installation/advanced/multi.adoc b/docs/modules/ROOT/pages/installation/advanced/multi.adoc index c95da15ba..fdad7bdba 100644 --- a/docs/modules/ROOT/pages/installation/advanced/multi.adoc +++ b/docs/modules/ROOT/pages/installation/advanced/multi.adoc @@ -1,19 +1,22 @@ [[advanced-installation-multiple-operators]] = Multiple Operators and Selective Upgrades -It's possible to setup multiple Camel K operators in a cluster to watch the same namespaces. It's not +It is possible to set up multiple Camel K operators on a cluster to watch resources on namespaces. It's not possible to configure Camel K this way using OLM (Operator Hub), since OLM prevents two operators from watching the same namespaces, but it's technically possible to achieve this setup manually. -A typical example is when you install two global operators in different namespaces (e.g. `kamel install --global --olm=false -n camel-ns-1` and `kamel install --global --olm=false -n camel-ns-2`). -In this situation, both operators will watch the same resources in the cluster, so that if a user creates an integration in any namespace, -both operators will contend the integration and the reconciliation will most probably result in an error (actual behavior is undefined). +A typical example is when you need to install multiple global operators in different namespaces in order to have multiple tenants on the cluster working with Camel K. +In this multi operator situation Camel K needs to avoid that the same resources on the cluster are managed by more than one operator at the same time. +Operators must not contend the integration and the reconciliation because this will most probably result in an error (actual behavior is undefined). -To avoid contention, it's possible to specify for each operator an ID and then assign any custom resource (CR) to a specific operator using an annotation. -The assigned operator will be responsible for the reconciliation of the annotated CR. +To avoid contention, Camel K uses an operator id for each operator. The operator id must be unique on the cluster and any custom resource (CR) is assigned to a specific operator using an annotation. +The assigned operator will be responsible for the reconciliation of the annotated CR and explicitly manages the resource no matter where it lives. In detail, the Camel K operator supports the environment variable `KAMEL_OPERATOR_ID`. The value is an identifier that can be equal to any string (e.g. `KAMEL_OPERATOR_ID=operator-1`). -Once the operator is assigned an ID, it will *only reconcile* Camel custom resources that are assigned to that ID (unannotated resources will be ignored as well). +Once the operator is assigned with an identifier, it will *only reconcile* Camel K custom resources that are assigned to that ID (unannotated resources will be ignored as well). + +By default, the Camel K operator is using the id `camel-k`. When installing many operators the instances must use a different operator id. +(e.g. `kamel install --global --olm=false -n camel-ns-1 --operator-id=operator-2`). To assign a resource to a specific operator, the user can annotate it with `camel.apache.org/operator.id`. For example: @@ -23,10 +26,14 @@ kind: Integration apiVersion: camel.apache.org/v1 metadata: annotations: - camel.apache.org/operator.id: operator-1 + camel.apache.org/operator.id: operator-2 # ... ---- +By default, Camel K custom resources use the default operator id `camel-k` as a value in this annotation. +And more precisely the default operator with id `camel-k` and only this specific operator is allowed to also reconcile resources that are missing the +operator id annotation. + The annotation can be put on any resource belonging to the "camel.apache.org" group. NOTE: When a resource creates additional resources in order to proceed with the reconciliation (for example @@ -34,7 +41,13 @@ an Integration may create an IntegrationKit, which in turn creates a Build resou all resources created in the process, so they'll be all reconciled by the same operator. By using the `camel.apache.org/operator.id` annotation, it's possible to move integrations between two or more operators running different -versions of the Camel K platform, i.e. *selectively upgrading or downgrading* them. +versions of the Camel K platform, i.e. *selectively upgrading or downgrading* them. Just change the annotation on that particula resource to point to a new +operator id: + +[source,shell script] +---- +kubectl annotate integration timer-to-log camel.apache.org/operator.id=operator-2 --overwrite +---- [[advanced-installation-multiple-platforms]] == Configuring Multiple Integration Platforms
