[camel-k] 02/09: chore(doc): Document RBAC requirements for Knative Sinks

[as...@apache.org]

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 44010336fdd419d28766046920517cb7db8f7fbf
Author: Antonin Stefanutti <an...@stefanutti.fr>
AuthorDate: Thu Jan 27 15:43:13 2022 +0100

    chore(doc): Document RBAC requirements for Knative Sinks
---
 docs/modules/ROOT/nav.adoc                         |  1 +
 .../ROOT/pages/installation/advanced/knative.adoc  | 85 ++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 068bf24..4e13dfe 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -16,6 +16,7 @@
 *** xref:installation/registry/icr.adoc[IBM Container Registry]
 *** xref:installation/registry/k3s.adoc[K3s]
 ** Advanced
+*** xref:installation/advanced/knative.adoc[Knative Sinks]
 *** xref:installation/advanced/resources.adoc[Resource management]
 *** xref:installation/advanced/multi.adoc[Multiple Operators]
 * Command Line Interface
diff --git a/docs/modules/ROOT/pages/installation/advanced/knative.adoc b/docs/modules/ROOT/pages/installation/advanced/knative.adoc
new file mode 100644
index 0000000..7bb61d7
--- /dev/null
+++ b/docs/modules/ROOT/pages/installation/advanced/knative.adoc
@@ -0,0 +1,85 @@
+[[knative-sinks]]
+= Knative Sinks
+
+A https://knative.dev/docs/eventing/sinks[Knative Sink] can be referenced in a producer path of the Camel Knative component, e.g.:
+
+[source,java]
+----
+from('timer:tick')
+  .setBody().constant('event')
+  .to('knative:event/broker')
+----
+
+Or as the value of the `sink` field in a `KameletBinding` resource, e.g.:
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+  name: timer-source-binding
+spec:
+  source:
+    ref:
+      kind: Kamelet
+      apiVersion: camel.apache.org/v1alpha1
+      name: timer-source
+    properties:
+      message: Event
+  sink:
+    ref:
+      kind: Broker
+      apiVersion: eventing.knative.dev/v1
+      name: broker
+    properties:
+      type: type
+----
+
+In the above examples, the Knative Sink is a https://knative.dev/docs/eventing/broker/[Knative Broker].
+However, a Knative Sink can be any Kubernetes resource that's _addressable_, i.e., whose URL can be retrieved by reading its `status.address.url`.
+
+This is what the Camel K operator does to resolve the Sink URLs, so that events can be sent to.
+That requires the ServiceAccount that runs the operator to be granted permission to GET these resources, while it configures the integration runtime.
+
+As the set of resources is arbitrary, and cannot be known _a-priori_, these permissions must be added to a Camel K operator Role, or ClusterRole, that's bound to the `camel-k-operator` ServiceAccount.
+
+For the above examples, that sink into an `eventing.knative.dev/broker` resource, this can be achieved by creating the following resources:
+
+.operator-role-knative-sinks.yaml
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app: camel-k
+  name: camel-k-operator-knative-sinks
+rules:
+- apiGroups:
+  - eventing.knative.dev
+  resources:
+  - brokers
+  verbs:
+  - get
+----
+
+.operator-rolebinding-knative-sinks.yaml
+[source,yaml]
+----
+kind: ClusterRoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: camel-k-operator-knative-sinks
+  labels:
+    app: "camel-k"
+subjects:
+- kind: ServiceAccount
+  name: camel-k-operator
+  namespace: camel-k
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: camel-k-operator-knative-sinks
+----
+
+These resources apply when the Camel K operator is deployed in _global_ mode, into the `camel-k` namespace, and should be adapted depending on how the operator is actually deployed.