From ba6b95c8bca5ea78628f7af62473c17213a67dea Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Tue, 8 Mar 2022 15:11:00 +0100 Subject: [PATCH 1/5] documented service discovery --- docs/modules/ROOT/nav.adoc | 3 +- docs/modules/ROOT/pages/discovery.adoc | 42 ++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 docs/modules/ROOT/pages/discovery.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 0006f3b7..f6349474 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,4 +2,5 @@ * xref:installation.adoc[] * xref:configuration.adoc[] * xref:usage.adoc[] - +* Concepts +** xref:discovery.adoc[] diff --git a/docs/modules/ROOT/pages/discovery.adoc b/docs/modules/ROOT/pages/discovery.adoc new file mode 100644 index 00000000..89ef9931 --- /dev/null +++ b/docs/modules/ROOT/pages/discovery.adoc @@ -0,0 +1,42 @@ +:clusterName: simple-kafka +:namespace: stackable +:brokerPort: 9092 + += Discovery Profiles + +The Stackable Operator for Apache Kafka creates a single discovery profile that allows access to the Kafka cluster https://kubernetes.io/docs/concepts/services-networking/service/[`Service`] which is published into the Kubernetes cluster as a +https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#configmap-v1-core[`ConfigMap`] object. + +== Profiles + +Given the following Kafka cluster: + +[subs="attributes"] +---- +apiVersion: kafka.stackable.tech/v1alpha1 +kind: KafkaCluster +metadata: + name: {clusterName} # <1> + namespace: {namespace} # <2> +spec: + [...] +---- +<1> Name of the Kafka cluster which is the name of the `ConfigMap` created for this discovery profile. +<2> Namespace of the `ConfigMap` created for this discovery profile. + +The published `ConfigMap` name and namespace are equal to the cluster name and namespace. In this case `{namespace}/{clusterName}`. + +=== Default + +This profile allows access to the Kafka cluster from inside the Kubernetes cluster, and connects directly to the metastore NodePort `Service`. + +== Contents + +The discovery profile contains the following fields where `{clusterName}` represents the name and `{namespace}` the namespace of the cluster: + +`KAFKA`:: +==== +Contains the thrift protocol connection string for the Kafka cluster to connect to the metastore: +[subs="attributes"] + {clusterName}.{namespace}.svc.cluster.local:{brokerPort} +==== From d209b41c6928f28fc6d87575f0604fbb07c772bb Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Mon, 14 Mar 2022 11:25:21 +0100 Subject: [PATCH 2/5] adapted to pr review --- docs/modules/ROOT/pages/discovery.adoc | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/modules/ROOT/pages/discovery.adoc b/docs/modules/ROOT/pages/discovery.adoc index 89ef9931..515e44c5 100644 --- a/docs/modules/ROOT/pages/discovery.adoc +++ b/docs/modules/ROOT/pages/discovery.adoc @@ -2,12 +2,13 @@ :namespace: stackable :brokerPort: 9092 -= Discovery Profiles += Discovery -The Stackable Operator for Apache Kafka creates a single discovery profile that allows access to the Kafka cluster https://kubernetes.io/docs/concepts/services-networking/service/[`Service`] which is published into the Kubernetes cluster as a -https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#configmap-v1-core[`ConfigMap`] object. +The Stackable Operator for Apache Kafka publishes a discovery https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#configmap-v1-core[`ConfigMap`], which exposes a client configuration bundle that allows access to the Apache Kafka cluster. -== Profiles +The bundle includes a thrift connection string to access the Kafka broker service. This string may be used by other operators or tools to configure their products with access to Kafka. This is limited to internal cluster access. + +== Example Given the following Kafka cluster: @@ -21,22 +22,18 @@ metadata: spec: [...] ---- -<1> Name of the Kafka cluster which is the name of the `ConfigMap` created for this discovery profile. -<2> Namespace of the `ConfigMap` created for this discovery profile. - -The published `ConfigMap` name and namespace are equal to the cluster name and namespace. In this case `{namespace}/{clusterName}`. - -=== Default +<1> The name of the Kafka cluster, which is also the name of the created discovery `ConfigMap`. +<2> The namespace of the discovery `ConfigMap`. -This profile allows access to the Kafka cluster from inside the Kubernetes cluster, and connects directly to the metastore NodePort `Service`. +The resulting discovery `ConfigMap` is `{namespace}/{clusterName}`. == Contents -The discovery profile contains the following fields where `{clusterName}` represents the name and `{namespace}` the namespace of the cluster: +The `{namespace}/{clusterName}` discovery `ConfigMap` contains the following fields where `{clusterName}` represents the name and `{namespace}` the namespace of the cluster: `KAFKA`:: ==== -Contains the thrift protocol connection string for the Kafka cluster to connect to the metastore: +Contains the thrift protocol connection string for the Kafka cluster: [subs="attributes"] {clusterName}.{namespace}.svc.cluster.local:{brokerPort} ==== From 0fe680b2b0b4f5390ce0a8420a7710794af9767a Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Mon, 14 Mar 2022 11:25:51 +0100 Subject: [PATCH 3/5] adapted to pr review --- docs/modules/ROOT/pages/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/discovery.adoc b/docs/modules/ROOT/pages/discovery.adoc index 515e44c5..cac42825 100644 --- a/docs/modules/ROOT/pages/discovery.adoc +++ b/docs/modules/ROOT/pages/discovery.adoc @@ -12,7 +12,7 @@ The bundle includes a thrift connection string to access the Kafka broker servic Given the following Kafka cluster: -[subs="attributes"] +[source,yaml,subs="attributes,callouts"] ---- apiVersion: kafka.stackable.tech/v1alpha1 kind: KafkaCluster From 21d6d80b3c9ca768fe762684c08ad7fdf42268db Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Mon, 14 Mar 2022 11:56:03 +0100 Subject: [PATCH 4/5] fixed callout highlighting --- docs/modules/ROOT/pages/discovery.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/discovery.adoc b/docs/modules/ROOT/pages/discovery.adoc index cac42825..da46e836 100644 --- a/docs/modules/ROOT/pages/discovery.adoc +++ b/docs/modules/ROOT/pages/discovery.adoc @@ -3,6 +3,7 @@ :brokerPort: 9092 = Discovery +:icons: font The Stackable Operator for Apache Kafka publishes a discovery https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#configmap-v1-core[`ConfigMap`], which exposes a client configuration bundle that allows access to the Apache Kafka cluster. @@ -12,12 +13,12 @@ The bundle includes a thrift connection string to access the Kafka broker servic Given the following Kafka cluster: -[source,yaml,subs="attributes,callouts"] +[source,yaml,subs="normal,callouts"] ---- apiVersion: kafka.stackable.tech/v1alpha1 kind: KafkaCluster metadata: - name: {clusterName} # <1> + name: {clusterName} # <1> namespace: {namespace} # <2> spec: [...] @@ -34,6 +35,6 @@ The `{namespace}/{clusterName}` discovery `ConfigMap` contains the following fie `KAFKA`:: ==== Contains the thrift protocol connection string for the Kafka cluster: -[subs="attributes"] +[subs="normal"] {clusterName}.{namespace}.svc.cluster.local:{brokerPort} ==== From 350f004110bd97624d08c5e6c43dbce4a4eccedf Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Mon, 14 Mar 2022 11:59:22 +0100 Subject: [PATCH 5/5] removed icon font --- docs/modules/ROOT/pages/discovery.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/modules/ROOT/pages/discovery.adoc b/docs/modules/ROOT/pages/discovery.adoc index da46e836..cbf22694 100644 --- a/docs/modules/ROOT/pages/discovery.adoc +++ b/docs/modules/ROOT/pages/discovery.adoc @@ -3,7 +3,6 @@ :brokerPort: 9092 = Discovery -:icons: font The Stackable Operator for Apache Kafka publishes a discovery https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#configmap-v1-core[`ConfigMap`], which exposes a client configuration bundle that allows access to the Apache Kafka cluster.