Add descriptions

Author: Felix Hennig

docs/modules/zookeeper/pages/index.adoc

@@ -1,5 +1,5 @@
 = Stackable Operator for Apache ZooKeeper
-:description: The Stackable operator for Apache ZooKeeper is a Kubernetes operator that can manage Apache ZooKeeper ensembles. Learn about its features, resources, dependencies and demos, and see the list of supported ZooKeeper versions.
+:description: Manage Apache ZooKeeper ensembles with the Stackable Kubernetes operator. Supports ZooKeeper versions, custom images, and integrates with Hadoop, Kafka, and more.
 :keywords: Stackable operator, Hadoop, Apache ZooKeeper, Kubernetes, k8s, operator, metadata, storage, cluster
 :zookeeper: https://zookeeper.apache.org/
 :github: https://github.com/stackabletech/zookeeper-operator/

docs/modules/zookeeper/pages/usage_guide/authentication.adoc

@@ -1,4 +1,5 @@
 = Authentication
+:description: Enable TLS authentication for ZooKeeper with Stackable's Kubernetes operator.
 
 The communication between nodes (server to server) is encrypted via TLS by default.
 In order to enforce TLS authentication for client-to-server communication, you can set an xref:concepts:authentication.adoc[AuthenticationClass] reference in the `spec.clusterConfig.authentication` property.

docs/modules/zookeeper/pages/usage_guide/encryption.adoc

@@ -1,8 +1,9 @@
 = Encryption
+:description: Quorum and client communication in ZooKeeper are encrypted via TLS by default. Customize certificates with the Secret Operator for added security
 
-The quorum and client communication are encrypted by default via TLS. This requires the
-xref:secret-operator:index.adoc[Secret Operator] to be present in order to provide certificates. The utilized
-certificates can be changed in a top-level config.
+The quorum and client communication are encrypted by default via TLS.
+This requires the xref:secret-operator:index.adoc[Secret Operator] to be present in order to provide certificates.
+The utilized certificates can be changed in a top-level config.
 
 [source,yaml]
 ----

docs/modules/zookeeper/pages/usage_guide/isolating_clients_with_znodes.adoc

@@ -1,8 +1,11 @@
 = Isolating clients with ZNodes
+:description: Isolate clients in ZooKeeper with unique ZNodes for each product. Set up ZNodes for each product and connect them using discovery ConfigMaps.
 
-ZooKeeper is a dependency of many products supported by the Stackable Data Platform. To ensure that all products can use the same ZooKeeper cluster safely, it is important to isolate them which is done using xref:znodes.adoc[].
+ZooKeeper is a dependency of many products supported by the Stackable Data Platform.
+To ensure that all products can use the same ZooKeeper cluster safely, it is important to isolate them which is done using xref:znodes.adoc[].
 
-This guide shows you how to set up multiple ZNodes to use with different products from the Stackable Data Platform, using Kafka and Druid as an example. For an explanation of the ZNode concept, read the xref:znodes.adoc[] concept page.
+This guide shows you how to set up multiple ZNodes to use with different products from the Stackable Data Platform, using Kafka and Druid as an example.
+For an explanation of the ZNode concept, read the xref:znodes.adoc[] concept page.
 
 == Prerequisites
 
@@ -21,7 +24,8 @@ This guide assumes the ZookeeperCluster is called `my-zookeeper` and is running
 
 === Setting up the ZNodes
 
-To set up a Kafka and Druid instance to use the ZookeeperCluster, two ZNodes are required, one for each product. This guide assumes the Kafka instance is running in the same namespace as the ZooKeeper, while the Druid instance is running in its own namespace called `druid-ns`.
+To set up a Kafka and Druid instance to use the ZookeeperCluster, two ZNodes are required, one for each product.
+This guide assumes the Kafka instance is running in the same namespace as the ZooKeeper, while the Druid instance is running in its own namespace called `druid-ns`.
 
 First, the Druid ZNode:
 
@@ -43,7 +47,8 @@ include::example$usage_guide/znode/example-znode-kafka.yaml[]
 <2> The namespace where the ZNode should be created. Since Kafka is running in the same namespace as ZooKeeper, this is the namespace of `my-zookeeper`.
 <3> The ZooKeeper cluster reference. The namespace is omitted here because the ZooKeeper is in the same namespace as the ZNode object.
 
-The Stackable Operator for ZooKeeper watches for ZookeeperZnode objects. If one is found it creates the ZNode _inside_ the ZooKeeper cluster and also creates a xref:concepts:service_discovery.adoc[discovery ConfigMap] in the same namespace as the ZookeeperZnode with the same name as the ZookeeperZnode.
+The Stackable Operator for ZooKeeper watches for ZookeeperZnode objects.
+If one is found it creates the ZNode _inside_ the ZooKeeper cluster and also creates a xref:concepts:service_discovery.adoc[discovery ConfigMap] in the same namespace as the ZookeeperZnode with the same name as the ZookeeperZnode.
 
 In this example, two ConfigMaps are created:
 
@@ -63,7 +68,8 @@ include::example$usage_guide/znode/example-znode-discovery.yaml[]
 
 This ConfigMap can then be mounted into other Pods and the `ZOOKEEPER` key can be used to connect to the ZooKeeper instance and the correct ZNode.
 
-All products that need a ZNode can be configured with a `zookeeperConfigMapName` property. As the name implies, this property  references the discovery ConfigMap for the requested ZNode.
+All products that need a ZNode can be configured with a `zookeeperConfigMapName` property.
+As the name implies, this property  references the discovery ConfigMap for the requested ZNode.
 
 For Kafka:
 
@@ -105,9 +111,9 @@ You can find out more about the discovery ConfigMap xref:discovery.adoc[] and th
 
 For security reasons, a unique ZNode path is generated every time the same ZookeeperZnode object is recreated, even if it has the same name.
 
-If a ZookeeperZnode needs to be associated with an existing ZNode path, the field `status.znodePath` can be set to
-the desired path. Note that since this is a subfield of `status`, it must explicitly be updated on the `status` subresource,
-and requires RBAC permissions to replace the `zookeeperznodes/status` resource. For example:
+If a ZookeeperZnode needs to be associated with an existing ZNode path, the field `status.znodePath` can be set to the desired path.
+Note that since this is a subfield of `status`, it must explicitly be updated on the `status` subresource, and requires RBAC permissions to replace the `zookeeperznodes/status` resource.
+For example:
 
 [source,bash]
 ----

docs/modules/zookeeper/pages/usage_guide/listenerclass.adoc

@@ -2,7 +2,8 @@
 
 Apache ZooKeeper offers an API. The Operator deploys a service called `<name>` (where `<name>` is the name of the ZookeeperCluster) through which ZooKeeper can be reached.
 
-This service can have either the `cluster-internal` or `external-unstable` type. `external-stable` is not supported for ZooKeeper at the moment. Read more about the types in the xref:concepts:service-exposition.adoc[service exposition] documentation at platform level.
+This service can have either the `cluster-internal` or `external-unstable` type. `external-stable` is not supported for ZooKeeper at the moment.
+Read more about the types in the xref:concepts:service-exposition.adoc[service exposition] documentation at platform level.
 
 This is how the listener class is configured:
 

docs/modules/zookeeper/pages/usage_guide/log_aggregation.adoc

@@ -1,7 +1,7 @@
 = Log aggregation
+:description: The logs can be forwarded to a Vector log aggregator by providing a discovery ConfigMap for the aggregator and by enabling the log agent.
 
-The logs can be forwarded to a Vector log aggregator by providing a discovery
-ConfigMap for the aggregator and by enabling the log agent:
+The logs can be forwarded to a Vector log aggregator by providing a discovery ConfigMap for the aggregator and by enabling the log agent:
 
 [source,yaml]
 ----
@@ -26,5 +26,4 @@ spec:
         replicas: 1
 ----
 
-Further information on how to configure logging, can be found in
-xref:concepts:logging.adoc[].
+Further information on how to configure logging, can be found in xref:concepts:logging.adoc[].

docs/modules/zookeeper/pages/usage_guide/monitoring.adoc

@@ -1,4 +1,5 @@
 = Monitoring
+:description: The managed ZooKeeper instances are automatically configured to export Prometheus metrics.
 
-The managed ZooKeeper instances are automatically configured to export Prometheus metrics. See
-xref:operators:monitoring.adoc[] for more details.
+The managed ZooKeeper instances are automatically configured to export Prometheus metrics.
+See xref:operators:monitoring.adoc[] for more details.

docs/modules/zookeeper/pages/usage_guide/resource_configuration.adoc

@@ -1,8 +1,10 @@
 = Storage and resource configuration
+:description: Configure ZooKeeper storage with PersistentVolumeClaims and set resource requests for CPU, memory, and storage.
+:pvcs: https://kubernetes.io/docs/concepts/storage/persistent-volumes
 
 == Storage for data volumes
 
-You can mount volumes where data is stored by specifying https://kubernetes.io/docs/concepts/storage/persistent-volumes[PersistentVolumeClaims] for each individual role group:
+You can mount volumes where data is stored by specifying {pvcs}[PersistentVolumeClaims] for each individual role group:
 
 [source,yaml]
 ----

docs/modules/zookeeper/pages/usage_guide/using_multiple_role_groups.adoc

@@ -1,17 +1,23 @@
 = Using multiple role groups
+:description: ZooKeeper uses myid for server identification. Avoid conflicts in multiple role groups by setting myidOffset for unique IDs in each StatefulSet.
+:ordinal-index: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#ordinal-index
 
-// abstract/summary
-ZooKeeper uses a unique ID called _myid_ to identify each server in the cluster. The Stackable Operator for Apache ZooKeeper assigns the _myid_ to each Pod from the https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#ordinal-index[ordinal index] given to the Pod by Kubernetes. This index is unique over the Pods in the StatefulSet of the xref:concepts:roles-and-role-groups.adoc[role group].
+ZooKeeper uses a unique ID called _myid_ to identify each server in the cluster.
+The Stackable Operator for Apache ZooKeeper assigns the _myid_ to each Pod from the {ordinal-index}[ordinal index] given to the Pod by Kubernetes.
+This index is unique over the Pods in the StatefulSet of the xref:concepts:roles-and-role-groups.adoc[role group].
 
-When using multiple role groups in a cluster, this will lead to different ZooKeeper Pods using the same _myid_. Each role group is represented by its own StatefulSet, and therefore always identified starting with `0`.
+When using multiple role groups in a cluster, this will lead to different ZooKeeper Pods using the same _myid_.
+Each role group is represented by its own StatefulSet, and therefore always identified starting with `0`.
 
-In order to avoid this _myid_ conflict, a property `myidOffset` needs to be specified in each rolegroup. The `myidOffset` defaults to zero, but if specified will be added to the ordinal index of the Pod.
+In order to avoid this _myid_ conflict, a property `myidOffset` needs to be specified in each rolegroup.
+The `myidOffset` defaults to zero, but if specified will be added to the ordinal index of the Pod.
 
 == Example configuration
 
 Here the property is used on the second role group in a ZooKeeperCluster:
 
-```yaml
+[source,yaml]
+----
 apiVersion: zookeeper.stackable.tech/v1alpha1
 kind: ZookeeperCluster
 metadata:
@@ -25,8 +31,9 @@ spec:
         replicas: 1
         config:
           myidOffset: 10  # <1>
-```
-
+----
 <1> The `myidOffset` property set to 10 for the secondary role group
 
-The `secondary` role group _myid_ starts from id `10`. The `primary` role group will start from `0`. This means, the replicas of the role group `primary` should not be scaled higher than `10` which results in `10` `primary` Pods using a _myid_ from `0` to `9`, followed by the `secondary` Pods starting at _myid_ `10`.
+The `secondary` role group _myid_ starts from id `10`.
+The `primary` role group will start from `0`.
+This means, the replicas of the role group `primary` should not be scaled higher than `10` which results in `10` `primary` Pods using a _myid_ from `0` to `9`, followed by the `secondary` Pods starting at _myid_ `10`.

docs/modules/zookeeper/pages/znodes.adoc

@@ -1,4 +1,5 @@
 = ZNodes
+:description: Manage ZooKeeper ZNodes with the ZookeeperZnode resource. Each client should use a unique root ZNode to prevent conflicts. Network access to ZooKeeper is required.
 
 Apache ZooKeeper organizes all data into a hierarchical system of https://zookeeper.apache.org/doc/r3.9.2/zookeeperProgrammers.html#ch_zkDataModel[ZNodes],
 which act as both files (they can have data associated with them) and folders (they can contain other ZNodes) when compared to a traditional (POSIX-like) file system.