[discourse-gatekeeper] Migrate charm docs (#120)

Initial Vale tests fixes
Co-authored-by: upload-charms-docs-bot <[email protected]>

Author: github-actions[bot]

docs/how-to/h-cluster-migration.md

@@ -1,31 +1,29 @@
-# Cluster Migration using MirrorMaker2.0
+# Cluster migration using MirrorMaker2.0
 
 ## Overview
 
 This How-To guide covers executing a cluster migration to a Charmed Kafka K8s deployment using MirrorMaker2.0, running as a process on each of the Juju units in an active/passive setup, where MirrorMaker will act as a consumer from an existing cluster, and a producer to the Charmed Kafka K8s cluster. In parallel (one process on each unit), data and consumer offsets for all existing topics will be synced one-way until both clusters are in-sync, with all data replicated across both in real-time.
 
-## MirrorMaker2 Overview
+## MirrorMaker2 overview
 
 Under the hood, MirrorMaker uses Kafka Connect source connectors to replicate data, those being the following:
 - **MirrorSourceConnector** - replicates topics from an original cluster to a new cluster. It also replicates ACLs and is necessary for the MirrorCheckpointConnector to run
 - **MirrorCheckpointConnector** - periodically tracks offsets. If enabled, it also synchronizes consumer group offsets between the original and new clusters
 - **MirrorHeartbeatConnector** - periodically checks connectivity between the original and new clusters
 
-Together, these allow for cluster->cluster replication of topics, consumer groups, topic configuration and ACLs, preserving partitioning and consumer offsets. For more detail on MirrorMaker internals, consult the [MirrorMaker README.md](https://github.com/apache/kafka/blob/trunk/connect/mirror/README.md) and the [MirrorMaker 2.0 KIP](https://cwiki.apache.org/confluence/display/KAFKA/KIP-382%3A+MirrorMaker+2.0). In practice, it allows one to sync data one-way between two live Kafka clusters with minimal impact on the ongoing production service.
+Together, they are used for cluster->cluster replication of topics, consumer groups, topic configuration and ACLs, preserving partitioning and consumer offsets. For more detail on MirrorMaker internals, consult the [MirrorMaker README.md](https://github.com/apache/kafka/blob/trunk/connect/mirror/README.md) and the [MirrorMaker 2.0 KIP](https://cwiki.apache.org/confluence/display/KAFKA/KIP-382%3A+MirrorMaker+2.0). In practice, it allows one to sync data one-way between two live Kafka clusters with minimal impact on the ongoing production service.
 
 In short, MirrorMaker runs as a distributed service on the new cluster, and consumes all topics, groups and offsets from the still-active original cluster in production, before producing them one-way to the new cluster that may not yet be serving traffic to external clients. The original, in-production cluster is referred to as an ‘active’ cluster, and the new cluster still waiting to serve external clients is ‘passive’. The MirrorMaker service can be configured using much the same configuration as available for Kafka Connect.
 
-## Deploy and run MirrorMaker
-
-### Pre-requisites
+## Pre-requisites
 
 - An existing Kafka cluster to migrate from. The clusters need to be reachable from/to Charmed Kafka K8s. 
 - A bootstrapped Juju K8s cloud running Charmed Kafka K8s to migrate to
     - A tutorial on how to set-up a Charmed Kafka deployment can be found as part of the [Charmed Kafka K8s Tutorial](/t/charmed-kafka-k8s-documentation-tutorial-overview/11945)
     - The CLI tool `yq` - https://github.com/mikefarah/yq
     - `snap install yq --channel=v3/stable`
 
-### Get cluster details and admin credentials
+## Get cluster details and admin credentials
 
 By design, the `kafka` charm will not expose any available connections until related to by a client. In this case, we deploy `data-integrator` charms and relating them to each `kafka` application, requesting `admin` level privileges:
 
@@ -49,9 +47,9 @@ export NEW_SERVERS=$(juju show-unit data-integrator/0 | yq -r '.. | .endpoints?
 export NEW_SASL_JAAS_CONFIG="org.apache.kafka.common.security.scram.ScramLoginModule required username=\""${NEW_USERNAME}"\" password=\""${NEW_PASSWORD}\"\;
 ```
 
-### Required source cluster credentials
+## Required source cluster credentials
 
-In order to authenticate MirrorMaker to both clusters, it will need full `super.user` permissions on **BOTH** clusters. MirrorMaker supports every possible `security.protocol` supported by Apache Kafka. In this guide, we will make the assumption that the original cluster is using `SASL_PLAINTEXT` authentication, as such, the required information is as follows:
+To authenticate MirrorMaker to both clusters, it will need full `super.user` permissions on **BOTH** clusters. MirrorMaker supports every possible `security.protocol` supported by Apache Kafka. In this guide, we will make the assumption that the original cluster is using `SASL_PLAINTEXT` authentication, as such, the required information is as follows:
 
 ```bash
 # comma-separated list of kafka server IPs and ports to connect to
@@ -63,9 +61,9 @@ OLD_SASL_JAAS_CONFIG
 
 > **NOTE** - If using `SSL` or `SASL_SSL` authentication, review the configuration options supported by Kafka Connect in the [Apache Kafka documentation](https://kafka.apache.org/documentation/#connectconfigs)
 
-### Generating `mm2.properties` file on the Charmed Kafka cluster
+## Generating `mm2.properties` file on the Charmed Kafka cluster
 
-MirrorMaker takes a `.properties` file for its configuration to fine-tune behavior. See below an example `mm2.properties` file that can be placed on each of the Charmed Kafka units using the above credentials:
+MirrorMaker takes a `.properties` file for its configuration to fine-tune behaviour. See below an example `mm2.properties` file that can be placed on each of the Charmed Kafka units using the above credentials:
 
 ```bash
 # Aliases for each cluster, can be set to any unique alias
@@ -131,7 +129,8 @@ cat /tmp/mm2.properties | juju ssh kafka-k8s/<id> sudo -i 'sudo tee -a /etc/kafk
 
 where `<id>` is the id of the Charmed Kafka unit.
 
-### Starting a dedicated MirrorMaker cluster
+## Starting a dedicated MirrorMaker cluster
+
 It is strongly advised to run MirrorMaker services on the downstream cluster to avoid service impact due to resource use. Now that the properties are set on each unit of the new cluster, the MirrorMaker services can be started using with JMX metrics exporters using the following:
 
 ```bash
@@ -142,7 +141,7 @@ export KAFKA_OPTS = "-Djava.security.auth.login.config=/etc/kafka/zookeeper-jaas
 juju ssh kafka-k8s/<id> sudo -i 'cd /opt/kafka/bin && KAFKA_OPTS=$KAFKA_OPTS ./connect-mirror-maker.sh /etc/kafka/mm2.properties'
 ```
 
-### Monitoring and validating data replication
+## Monitoring and validating data replication
 
 The migration process can be monitored using built-in Kafka bin-commands on the original cluster. In the Charmed Kafka cluster, these bin-commands are also mapped to snap commands on the units (e.g `charmed-kafka.get-offsets` or `charmed-kafka.topics`).
 
@@ -164,8 +163,11 @@ There is also a [range of different metrics](https://github.com/apache/kafka/blo
 ```
 curl 10.248.204.198:9099/metrics | grep records_count
 ```
-### Switching client traffic from original cluster to Charmed Kafka cluster
+## Switching client traffic from original cluster to Charmed Kafka cluster
+
 Once happy that all the necessary data has successfully migrated, stop all active consumer applications on the original cluster, and redirect them to the Charmed Kafka cluster, making sure to use the Charmed Kafka cluster server addresses and authentication. After doing so, they will re-join their original consumer groups at the last committed offset it had originally, and continue consuming as normal.
 Finally, the producer client applications can be stopped, updated with the Charmed Kafka cluster server addresses and authentication, and restarted, with any newly produced messages being received by the migrated consumer client applications, completing the migration of both the data, and the client applications.
-### Stopping MirrorMaker replication
+
+## Stopping MirrorMaker replication
+
 Once confident in the successful completion of the data an client migration, the running processes on each of the charm units can be killed, stopping the MirrorMaker processes active on the Charmed Kafka cluster.

docs/how-to/h-deploy.md

@@ -8,7 +8,11 @@ To deploy a Charmed Kafka K8s cluster:
 3. Deploy and relate Kafka K8s and ZooKeeper K8s charms.
 4. (Optionally) Create an external admin user
 
-## Juju Controller setup
+In the next subsections, we will cover these steps separately by referring to 
+relevant Juju documentation and providing details on the Charmed Kafka K8s specifics.
+If you already have a Juju controller and/or a Juju model, you can skip the associated steps.
+
+## Juju controller setup
 
 Make sure you have a Juju controller accessible from 
 your local environment using the [Juju client snap](https://snapcraft.io/juju). 
@@ -35,7 +39,7 @@ where `<cloud>` -- the cloud to deploy controller to, e.g., `localhost`. For mor
 
 > **Note** See the [How to manage controllers](/t/1111) guide in Juju documentation for more options.
 
-## Juju Model setup
+## Juju model setup
 
 You can create a new Juju model using 
 

docs/how-to/h-enable-encryption.md

@@ -1,8 +1,10 @@
 # How to enable encryption
 
+To enable encryption, you should first deploy a TLS certificates Provider charm.
+
 ## Deploy a TLS Provider charm
 
-To enable encryption, you should first deploy a TLS certificates Provider charm. The Kafka K8s and ZooKeeper K8s charms implements the Requirer side of the [`tls-certificates/v1`](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/tls_certificates/v1/README.md) charm relation. 
+The Kafka K8s and ZooKeeper K8s charms implement the Requirer side of the [`tls-certificates/v1`](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/tls_certificates/v1/README.md) charm relation. 
 Therefore, any charm implementing the Provider side could be used. 
 
 One possible option, suitable for testing, could be to use the `self-signed-certificates`, although this setup is however not recommended for production clusters. 

docs/how-to/h-enable-monitoring.md

@@ -6,35 +6,44 @@ The metrics can be queried by accessing the `http://<kafka-unit-ip>:9101/metrics
 Additionally, the charm provides integration with the [Canonical Observability Stack](https://charmhub.io/topics/canonical-observability-stack).
 
 ## Prerequisites
+
 * A deployed [Charmed Kafka K8s and Charmed ZooKeeper K8s bundle](HERE)
 * A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
 
 ## Offer interfaces via the COS controller
+
 First, we will switch to the COS K8s environment and offer COS interfaces to be cross-model integrated with the Charmed Kafka K8s model.
 
 To switch to the Kubernetes controller for the COS model, run
+
 ```shell
 juju switch <k8s_cos_controller>:<cos_model_name>
 ```
 To offer the COS interfaces, run 
+
 ```shell
 juju offer grafana:grafana-dashboard grafana-dashboards
 juju offer loki:logging loki-logging
 juju offer prometheus:receive-remote-write prometheus-receive-remote-write
 ```
+
 ## Consume offers via the Kafka model
+
 Next, we will switch to the Charmed Kafka K8s model, find offers, and consume them.
 
 We are currently on the Kubernetes controller for the COS model. To switch to the Kafka model, run
+
 ```shell
 juju switch <k8s_db_controller>:<kafka_model_name>
 ```
 To find offers, run the following command (make sure not to miss the ":" at the end!):
+
 ```shell
 juju find-offers <k8s_cos_controller>: 
 ```
 
-The output should be similar to the sample below, where `k8s` is the k8s controller name and `cos` is the model where `cos-lite` has been deployed:
+The output should be similar to the sample below, where `k8s` is the K8s controller name and `cos` is the model where `cos-lite` has been deployed:
+
 ```shell
 Store     URL                                        Access  Interfaces
 k8s  admin/cos.grafana-dashboards               admin   grafana_dashboard:grafana-dashboard
@@ -44,6 +53,7 @@ k8s  admin/cos.prometheus-receive-remote-write  admin   prometheus_remote_write:
 ```
 
 To consume offers to be reachable in the current model, run
+
 ```shell
 juju consume <k8s_cos_controller>:admin/<cos_model_name>.grafana-dashboards
 juju consume <k8s_cos_controller>:admin/<cos_model_name>.loki-logging
@@ -52,6 +62,7 @@ juju consume <k8s_cos_controller>:admin/<cos_model_name>.prometheus-receive-remo
 ## Deploy and integrate Grafana
 
 First, deploy [grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s): 
+
 ```shell
 juju deploy grafana-agent-k8s --trust
 ```
@@ -84,14 +95,15 @@ models, e.g. `<kafka_model_name>` and `<cos_model_name>`.
 After this is complete, the monitoring COS stack should be up and running and ready to be used. 
 
 ### Connect Grafana web interface
+
 To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s?_ga=2.201254254.1948444620.1704703837-757109492.1701777558#heading--browse-dashboards) section of the MicroK8s "Getting started" guide.
 ```shell
 juju run grafana/leader get-admin-password --model <k8s_cos_controller>:<cos_model_name>
 ```
 
 ## Tune server logging level
 
-In order to tune the level of the server logs for Kafka and ZooKeeper, configure the `log-level` and `log_level` properties accordingly
+To tune the level of the server logs for Kafka and ZooKeeper, configure the `log-level` and `log_level` properties accordingly.
 
 ### Kafka 
 

docs/how-to/h-integrate-alerts-dashboards.md

@@ -1,30 +1,28 @@
 # Integrate custom alerting rules and dashboards
 
-This guide shows you how to integrate an existing set of rules and/or dashboards to your Charmed Kafka and Charmed Zookeeper deployment to be consumed with the [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack).
-To do so, we will sync resources stored in a git repo to COS Lite.
+This guide shows you how to integrate an existing set of rules and/or dashboards to your Charmed Kafka and Charmed ZooKeeper deployment to be consumed with the [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack).
+To do so, we will sync resources stored in a git repository to COS Lite.
 
 ## Prerequisites
 
-Deploy the cos-lite bundle in a Kubernetes environment and integrate Charmed Kafka and Charmed ZooKeeper to the COS offers, as shown in the [How to Enable Monitoring](/t/charmed-kafka-k8s-how-to-enable-monitoring/10291) guide.
+Deploy the `cos-lite` bundle in a Kubernetes environment and integrate Charmed Kafka and Charmed ZooKeeper to the COS offers, as shown in the [How to Enable Monitoring](/t/charmed-kafka-k8s-how-to-enable-monitoring/10291) guide.
 This guide will refer to the models that charms are deployed into as:
 
-* `<cos-model>` for the model containing observabilities charms (and deployed on k8s)
+* `<cos-model>` for the model containing observability charms (and deployed on K8s)
 
 * `<apps-model>` for the model containing Charmed Kafka and Charmed ZooKeeper
 
-* `<apps-model>` for other optional charms (e.g. tls-certificates operators, `grafana-agent`, `data-integrator`, etc.).
+* `<apps-model>` for other optional charms (e.g. TLS-certificates operators, `grafana-agent`, `data-integrator`, etc.).
 
 ## Create a repository with a custom monitoring setup
 
-
 Create an empty git repository, or in an existing one, save your alert rules and dashboard models under the `<path_to_prom_rules>`, `<path_to_loki_rules>` and `<path_to_models>` folders.
 
 If you want a primer to rule writing, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/).  
 You may also find an example in the [kafka-test-app repository](https://github.com/canonical/kafka-test-app).
 
 Then, push your changes to the remote repository.
 
-
 ## Deploy the COS configuration charm
 
 Deploy the [COS configuration](https://charmhub.io/cos-configuration-k8s) charm in the `<cos-model>` model:
@@ -43,7 +41,6 @@ Adding, updating or deleting an alert rule or a dashboard in the repository will
 You need to manually refresh `cos-config`'s local repository with the *sync-now* action if you do not want to wait for the next [update-status event](/t/event-update-status/6484) to pull the latest changes.
 [/Note]
 
-
 ## Forward the rules and dashboards
 
 The path to the resource folders can be set after deployment: