Split off usage guide into individual files and document MyID for multiple role groups (#606)

# Description

fixes #557 

## Review Checklist

- [ ] Code contains useful comments
- [ ] CRD change approved (or not applicable)
- [ ] (Integration-)Test cases added (or not applicable)
- [ ] Documentation added (or not applicable)
- [ ] Changelog updated (or not applicable)
- [ ] Cargo.toml only contains references to git tags (not specific commits or branches)
- [ ] Helm chart can be installed and deployed operator works (or not applicable)

Once the review is done, comment `bors r+` (or `bors merge`) to merge. [Further information](https://bors.tech/documentation/getting-started/#reviewing-pull-requests)


Co-authored-by: Felix Hennig <[email protected]>

Author: Felix Hennig

docs/antora.yml

@@ -4,4 +4,5 @@ title: Stackable Operator for Apache ZooKeeper
 nav:
   - modules/getting_started/nav.adoc
   - modules/ROOT/nav.adoc
+  - modules/usage_guide/nav.adoc
 prerelease: true

docs/modules/ROOT/nav.adoc

@@ -1,5 +1,4 @@
 * xref:configuration.adoc[]
-* xref:usage.adoc[]
 * Concepts
 ** xref:znodes.adoc[]
 ** xref:discovery.adoc[]

docs/modules/ROOT/pages/usage.adoc

@@ -94,4 +94,4 @@ Great! This step concludes the Getting started guide. You have installed the Zoo
 
 == What's next
 
-Have a look at the xref:ROOT:usage.adoc[] page to learn more about configuration options for your ZooKeeper cluster like setting up encryption or authentication. You can also have a look at the xref:ROOT:znodes.adoc[] page to learn more about ZNodes.
+Have a look at the xref:usage_guide:index.adoc[] to learn more about configuration options for your ZooKeeper cluster like setting up encryption or authentication. You can also have a look at the xref:ROOT:znodes.adoc[] page to learn more about ZNodes.

docs/modules/getting_started/pages/first_steps.adoc

@@ -0,0 +1,7 @@
+* xref:index.adoc[]
+** xref:encryption.adoc[]
+** xref:authentication.adoc[]
+** xref:resource_configuration.adoc[]
+** xref:monitoring.adoc[]
+** xref:using_multiple_role_groups.adoc[]
+** xref:configuration_environment_overrides.adoc[]

docs/modules/ROOT/examples/example-cluster-tls-authentication-class.yaml renamed to docs/modules/usage_guide/examples/example-cluster-tls-authentication-class.yaml

@@ -0,0 +1,18 @@
+= Authentication
+
+The quorum or server-to-server communication is authenticated via TLS per default. In order to enforce TLS authentication for client-to-server communication, you can set an `AuthenticationClass` reference in the custom resource provided by the xref:commons-operator::index.adoc[Commons Operator].
+
+[source,yaml]
+----
+include::example$example-cluster-tls-authentication.yaml[]
+include::example$example-cluster-tls-authentication-class.yaml[]
+include::example$example-cluster-tls-authentication-secret.yaml[]
+----
+<1> The `config.clientAuthentication.authenticationClass` can be set to use TLS for authentication. This is optional.
+<2> The referenced `AuthenticationClass` that references a `SecretClass` to provide certificates.
+<3> The reference to a `SecretClass`.
+<4> The `SecretClass` that is referenced by the `AuthenticationClass` in order to provide certificates.
+
+If both `spec.config.tls.secretClass` and `spec.config.clientAuthentication.authenticationClass` are set, the authentication class will take precedence over the secret class. The cluster will be encrypted and authenticate only against the authentication class.
+
+WARNING: Due to a https://issues.apache.org/jira/browse/ZOOKEEPER-4276[bug] in ZooKeeper, the `clientPort` property in combination with `client.portUnification=true` is used instead of the `secureClientPort`. This means that unencrypted and unauthenticated access to the ZooKeeper cluster is still possible.

docs/modules/ROOT/examples/example-cluster-tls-authentication-secret.yaml renamed to docs/modules/usage_guide/examples/example-cluster-tls-authentication-secret.yaml

@@ -0,0 +1,64 @@
+
+= Configuration and environment overrides
+
+The cluster definition also supports overriding configuration properties and environment variables, either per role or per role group, where the more specific override (role group) has precedence over the less specific one (role).
+
+IMPORTANT: Overriding certain properties which are set by operator (such as the ports) can interfere with the operator and can lead to problems.
+
+== Configuration properties
+
+For a role or role group, at the same level of `config`, you can specify: `configOverrides` for the `zoo.cfg`. For example, if you want to set the `4lw.commands.whitelist` to allow the `ruok` administrative command, it can be configured in the `ZookeeperCluster` resource like so:
+
+[source,yaml]
+----
+servers:
+  roleGroups:
+    default:
+      configOverrides:
+        zoo.cfg:
+          4lw.commands.whitelist: "srvr, ruok"
+      replicas: 1
+----
+
+Just as for the `config`, it is possible to specify this at role level as well:
+
+[source,yaml]
+----
+routers:
+  configOverrides:
+    zoo.cfg:
+      4lw.commands.whitelist: "srvr, ruok"
+  roleGroups:
+    default:
+      replicas: 1
+----
+
+All override property values must be strings.
+
+For a full list of configuration options we refer to the Apache ZooKeeper https://zookeeper.apache.org/doc/r3.7.0/zookeeperAdmin.html#sc_configuration[Configuration Reference].
+
+== Environment variables
+
+In a similar fashion, environment variables can be (over)written. For example per role group:
+
+[source,yaml]
+----
+servers:
+  roleGroups:
+    default:
+      envOverrides:
+        MY_ENV_VAR: "MY_VALUE"
+      replicas: 1
+----
+
+or per role:
+
+[source,yaml]
+----
+servers:
+  envOverrides:
+    MY_ENV_VAR: "MY_VALUE"
+  roleGroups:
+    default:
+      replicas: 1
+----

docs/modules/ROOT/examples/example-cluster-tls-authentication.yaml renamed to docs/modules/usage_guide/examples/example-cluster-tls-authentication.yaml

@@ -0,0 +1,19 @@
+= Encryption
+
+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]
+----
+include::example$example-cluster-tls-encryption.yaml[]
+----
+<1> The `tls.secretClass` refers to the client-to-server encryption. Defaults to the `tls` secret.
+<2> The `quorumTlsSecretClass` refers to the server-to-server quorum encryption. Defaults to the `tls` secret.
+
+The `tls` secret is deployed from the xref:secret-operator::index.adoc[Secret Operator] and looks like this:
+
+[source,yaml]
+----
+include::example$example-secret-operator-tls-secret.yaml[]
+----
+
+You can create your own secrets and reference them e.g. in the `tls.secretClass` to use different certificates.

docs/modules/ROOT/examples/example-cluster-tls-encryption.yaml renamed to docs/modules/usage_guide/examples/example-cluster-tls-encryption.yaml

@@ -0,0 +1,3 @@
+= Usage guide
+
+This section provides more in depth information about specific aspects of using the Stackable Operator for Apache ZooKeeper.

docs/modules/ROOT/examples/example-secret-operator-tls-secret.yaml renamed to docs/modules/usage_guide/examples/example-secret-operator-tls-secret.yaml

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

docs/modules/usage_guide/nav.adoc

@@ -0,0 +1,47 @@
+= Storage and resource configuration
+
+== 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:
+
+[source,yaml]
+----
+servers:
+  roleGroups:
+    default:
+      config:
+        resources:
+          storage:
+            data:
+              capacity: 2Gi
+----
+
+In the above example, all ZooKeeper nodes in the default group will store data (the location of the property `dataDir`) on a `2Gi` volume.
+
+By default, in case nothing is configured in the custom resource for a certain role group, each Pod will have a `1Gi` large local volume mount for the data location.
+
+== Resource requests
+
+// The "nightly" version is needed because the "include" directive searches for
+// files in the "stable" version by default.
+// TODO: remove the "nightly" version after the next platform release (current: 22.09)
+include::nightly@home:concepts:stackable_resource_requests.adoc[]
+
+If no resource requests are configured explicitly, the ZooKeeper operator uses the following defaults:
+
+[source,yaml]
+----
+servers:
+  roleGroups:
+    default:
+      config:
+        resources:
+          memory:
+            limit: '512Mi'
+          cpu:
+            max: '4'
+            min: '500m'
+          storage:
+            data:
+              capacity: '1Gi'
+----