From fc8f9923c2b45d51cab2665a5f1e91f6a05a20ed Mon Sep 17 00:00:00 2001 From: prmellor Date: Tue, 20 Feb 2024 17:10:27 +0000 Subject: [PATCH] docs(refactor): moves annotations content Signed-off-by: prmellor --- .../configuring/assembly-config.adoc | 6 +++++ .../assembly-deploy-client-access.adoc | 3 ++- .../assembly-deploy-kafka-cluster.adoc | 2 ++ .../assembly-uninstalling.adoc | 0 .../managing/assembly-management-tasks.adoc | 18 --------------- documentation/deploying/deploying.adoc | 2 ++ .../con-service-discovery.adoc | 23 ++++++++----------- .../con-configuring-cluster-operator.adoc | 2 +- .../proc-pausing-reconciliation.adoc | 8 +++---- 9 files changed, 27 insertions(+), 37 deletions(-) rename documentation/assemblies/{managing => deploying}/assembly-uninstalling.adoc (100%) rename documentation/modules/{managing => deploying}/con-service-discovery.adoc (69%) rename documentation/modules/{managing => operators}/proc-pausing-reconciliation.adoc (91%) diff --git a/documentation/assemblies/configuring/assembly-config.adoc b/documentation/assemblies/configuring/assembly-config.adoc index 6e9f6dd8229..347ea036f03 100644 --- a/documentation/assemblies/configuring/assembly-config.adoc +++ b/documentation/assemblies/configuring/assembly-config.adoc @@ -58,6 +58,10 @@ include::../../modules/configuring/con-config-kafka.adoc[leveloffset=+1] include::../../modules/managing/proc-setting-broker-limits.adoc[leveloffset=+2] //Zookeeper's default configuration include::../../modules/configuring/con-zookeeper-default-config.adoc[leveloffset=+2] +//steps to delete kafka nodes using annotations +include::../../modules/configuring/proc-manual-delete-pod-pvc-kafka.adoc[leveloffset=+2] +//steps to delete zookeeper nodes using annotations +include::../../modules/configuring/proc-manual-delete-pod-pvc-zookeeper.adoc[leveloffset=+2] //configuring node pools include::../../modules/configuring/con-config-node-pools.adoc[leveloffset=+1] @@ -81,6 +85,8 @@ include::../../modules/configuring/con-configuring-user-operator.adoc[leveloffse //cluster operator config env vars include::../../modules/operators/con-configuring-cluster-operator.adoc[leveloffset=+1] +//pausing reconciliation of custom resources +include::../../modules/operators/proc-pausing-reconciliation.adoc[leveloffset=+2] //enabling leader election include::../../assemblies/operators/assembly-using-multiple-cluster-operators.adoc[leveloffset=+2] //cluster operator proxy config diff --git a/documentation/assemblies/deploying/assembly-deploy-client-access.adoc b/documentation/assemblies/deploying/assembly-deploy-client-access.adoc index d81d1b2b26e..fe1c82e3c10 100644 --- a/documentation/assemblies/deploying/assembly-deploy-client-access.adoc +++ b/documentation/assemblies/deploying/assembly-deploy-client-access.adoc @@ -26,4 +26,5 @@ ifdef::Section[] include::../../modules/security/proc-accessing-kafka-using-ingress.adoc[leveloffset=+1] endif::Section[] include::../../modules/security/proc-accessing-kafka-using-routes.adoc[leveloffset=+1] - +//discover internal bootstrap service and Bridge +include::../../modules/deploying/con-service-discovery.adoc[leveloffset=+1] \ No newline at end of file diff --git a/documentation/assemblies/deploying/assembly-deploy-kafka-cluster.adoc b/documentation/assemblies/deploying/assembly-deploy-kafka-cluster.adoc index 7adf6f65552..ab76b48257b 100644 --- a/documentation/assemblies/deploying/assembly-deploy-kafka-cluster.adoc +++ b/documentation/assemblies/deploying/assembly-deploy-kafka-cluster.adoc @@ -34,5 +34,7 @@ include::../../modules/deploying/proc-deploy-kafka-cluster.adoc[leveloffset=+1] include::../../modules/deploying/proc-deploy-topic-operator-with-cluster-operator.adoc[leveloffset=+1] //Include User Operator in deployment include::../../modules/deploying/proc-deploy-user-operator-with-cluster-operator.adoc[leveloffset=+1] +//Connecting to ZooKeeper from terminal +include::../../modules/configuring/proc-connecting-to-zookeeper.adoc[leveloffset=+1] //Kafka cluster resources created include::../../modules/configuring/ref-list-of-kafka-cluster-resources.adoc[leveloffset=+1] \ No newline at end of file diff --git a/documentation/assemblies/managing/assembly-uninstalling.adoc b/documentation/assemblies/deploying/assembly-uninstalling.adoc similarity index 100% rename from documentation/assemblies/managing/assembly-uninstalling.adoc rename to documentation/assemblies/deploying/assembly-uninstalling.adoc diff --git a/documentation/assemblies/managing/assembly-management-tasks.adoc b/documentation/assemblies/managing/assembly-management-tasks.adoc index 7bec4ef77c1..f525359e2ff 100644 --- a/documentation/assemblies/managing/assembly-management-tasks.adoc +++ b/documentation/assemblies/managing/assembly-management-tasks.adoc @@ -9,32 +9,14 @@ Managing Strimzi requires performing various tasks to keep the Kafka clusters and associated resources running smoothly. Use `kubectl` commands to check the status of resources, configure maintenance windows for rolling updates, and leverage tools such as the Strimzi Drain Cleaner and Kafka Static Quota plugin to manage your deployment effectively. -//discover internal bootstrap service and HTTP Bridge -include::../../modules/managing/con-service-discovery.adoc[leveloffset=+1] - -//connecting to ZooKeeper from terminal -include::../../modules/configuring/proc-connecting-to-zookeeper.adoc[leveloffset=+1] - -//pausing reconciliation of custom resources -include::../../modules/managing/proc-pausing-reconciliation.adoc[leveloffset=+1] - //windows (time) for maintenance include::assembly-maintenance-time-windows.adoc[leveloffset=+1] -//steps to delete kafka nodes using annotations -include::../../modules/configuring/proc-manual-delete-pod-pvc-kafka.adoc[leveloffset=+1] - -//steps to delete zookeeper nodes using annotations -include::../../modules/configuring/proc-manual-delete-pod-pvc-zookeeper.adoc[leveloffset=+1] - //performing manual rolling updates include::assembly-rolling-updates.adoc[leveloffset=+1] //recover a cluster from a PV include::assembly-cluster-recovery-volume.adoc[leveloffset=+1] -//uninstalling the product -include::assembly-uninstalling.adoc[leveloffset=+1] - //faqs for cluster operator include::../../modules/managing/con-cluster-operator-faqs.adoc[leveloffset=+1] diff --git a/documentation/deploying/deploying.adoc b/documentation/deploying/deploying.adoc index a7b5390e3d6..6db8472813c 100644 --- a/documentation/deploying/deploying.adoc +++ b/documentation/deploying/deploying.adoc @@ -54,6 +54,8 @@ include::assemblies/deploying/assembly-drain-cleaner.adoc[leveloffset=+1] include::assemblies/upgrading/assembly-upgrade.adoc[leveloffset=+1] //Downgrading the deployment include::assemblies/upgrading/assembly-downgrade.adoc[leveloffset=+1] +//uninstalling the product +include::assemblies/deploying/assembly-uninstalling.adoc[leveloffset=+1] //How to monitor restart events include::assemblies/deploying/assembly-deploy-restart-events.adoc[leveloffset=+1] //tuning configuration diff --git a/documentation/modules/managing/con-service-discovery.adoc b/documentation/modules/deploying/con-service-discovery.adoc similarity index 69% rename from documentation/modules/managing/con-service-discovery.adoc rename to documentation/modules/deploying/con-service-discovery.adoc index e6f1f746298..7f0910ac5bf 100644 --- a/documentation/modules/managing/con-service-discovery.adoc +++ b/documentation/modules/deploying/con-service-discovery.adoc @@ -3,23 +3,22 @@ // managing/assembly-management-tasks.adoc [id='proc-add-service-discovery-{context}'] -= Discovering services using labels and annotations += Returning connection details for services +[role="_abstract"] Service discovery makes it easier for client applications running in the same Kubernetes cluster as Strimzi to interact with a Kafka cluster. -A _service discovery_ label and annotation is generated for services used to access the Kafka cluster: +A _service discovery_ label and annotation are generated for services used to access the Kafka cluster: * Internal Kafka bootstrap service -* HTTP Bridge service +* Kafka Bridge service -The label helps to make the service discoverable, and the annotation provides connection details that a client application can use to make the connection. +The label helps to make the service discoverable, while the annotation provides connection details for client applications to establish connections. The service discovery label, `strimzi.io/discovery`, is set as `true` for the `Service` resources. The service discovery annotation has the same key, providing connection details in JSON format for each service. -[discrete] -== Example internal Kafka bootstrap service - +.Example internal Kafka bootstrap service [source,yaml,subs="attributes+"] ---- apiVersion: v1 @@ -48,8 +47,7 @@ spec: #... ---- -[discrete] -== Example HTTP Bridge service +.Example Kafka Bridge service [source,yaml,subs="attributes+"] ---- @@ -71,13 +69,12 @@ metadata: strimzi.io/name: my-bridge-bridge-service ---- -== Returning connection details on services - -You can find the services by specifying the discovery label when fetching services from the command line or a corresponding API call. +Find services by specifying the discovery label when fetching services from the command line or a corresponding API call. +.Returning services using the discovery label [source,yaml] ---- kubectl get service -l strimzi.io/discovery=true ---- -The connection details are returned when retrieving the service discovery label. +Connection details are returned when retrieving the service discovery label. diff --git a/documentation/modules/operators/con-configuring-cluster-operator.adoc b/documentation/modules/operators/con-configuring-cluster-operator.adoc index eaa7dd5480d..3b31be8e991 100644 --- a/documentation/modules/operators/con-configuring-cluster-operator.adoc +++ b/documentation/modules/operators/con-configuring-cluster-operator.adoc @@ -265,7 +265,7 @@ env: ---- [id='ref-operator-cluster-periodic-reconciliation-{context}'] -== Configuring periodic reconciliation by the Cluster Operator +== Setting periodic reconciliation of custom resources Use the `STRIMZI_FULL_RECONCILIATION_INTERVAL_MS` variable to set the time interval for periodic reconciliations by the Cluster Operator. Replace its value with the required interval in milliseconds. diff --git a/documentation/modules/managing/proc-pausing-reconciliation.adoc b/documentation/modules/operators/proc-pausing-reconciliation.adoc similarity index 91% rename from documentation/modules/managing/proc-pausing-reconciliation.adoc rename to documentation/modules/operators/proc-pausing-reconciliation.adoc index 7bdebbe05cc..9aa8bb3be9a 100644 --- a/documentation/modules/managing/proc-pausing-reconciliation.adoc +++ b/documentation/modules/operators/proc-pausing-reconciliation.adoc @@ -4,14 +4,14 @@ [id='proc-pausing-reconciliation-{context}'] -= Pausing reconciliation of custom resources += Pausing reconciliation of custom resources using annotations -Sometimes it is useful to pause the reconciliation of custom resources managed by Strimzi Operators, +Sometimes it is useful to pause the reconciliation of custom resources managed by Strimzi operators, so that you can perform fixes or make updates. -If reconciliations are paused, any changes made to custom resources are ignored by the Operators until the pause ends. +If reconciliations are paused, any changes made to custom resources are ignored by the operators until the pause ends. If you want to pause reconciliation of a custom resource, set the `strimzi.io/pause-reconciliation` annotation to `true` in its configuration. -This instructs the appropriate Operator to pause reconciliation of the custom resource. +This instructs the appropriate operator to pause reconciliation of the custom resource. For example, you can apply the annotation to the `KafkaConnect` resource so that reconciliation by the Cluster Operator is paused. You can also create a custom resource with the pause annotation enabled.