[discourse-gatekeeper] Update deployment instructions with stable track and trust (#134)

Co-authored-by: upload-charms-docs-bot <[email protected]>

Author: github-actions[bot]

docs/how-to/h-deploy.md

@@ -64,12 +64,14 @@ juju show-model | yq '.[].type'
 The Kafka and ZooKeeper charms can both be deployed as follows:
 
 ```commandline
-juju deploy kafka-k8s --channel 3/edge -n <kafka-units>
-juju deploy zookeeper-k8s --channel 3/edge -n <zookeeper-units>
+juju deploy kafka-k8s --channel 3/stable -n <kafka-units> --trust
+juju deploy zookeeper-k8s --channel 3/stable -n <zookeeper-units>
 ```
 
 where `<kafka-units>` and `<zookeeper-units>` -- the number of units to deploy for Kafka and ZooKeeper. We recommend values of at least `3` and `5` respectively.
 
+> **NOTE** The `--trust` option is needed for the Kafka application to work properly, e.g., use NodePort or `juju refresh`. For more information about the trust options usage, see the [Juju documentation](/t/5476#heading--trust-an-application-with-a-credential). 
+
 Connect ZooKeeper and Kafka by relating/integrating the charms:
 
 ```commandline

docs/how-to/h-manage-units.md

@@ -5,7 +5,7 @@ Unit management guide for scaling and running admin utility scripts.
 ## Replication and scaling
 
 Increasing the number of Kafka brokers can be achieved by adding more units
-to the Charmed Kafka K8s application, e.g. 
+to the Charmed Kafka K8s application:
 
 ```shell
 juju add-unit kafka-k8s -n <num_brokers_to_add>
@@ -18,8 +18,8 @@ It is important to note that when adding more units, the Kafka cluster will not
 will be used only when new topics and new partitions are created. 
 
 Partition reassignment can still be done manually by the admin user by using the 
-`/opt/kafka/bin/kafka-reassign-partitions.sh` Kafka bin utility script. Please refer to 
-its documentation for more information. 
+`/opt/kafka/bin/kafka-reassign-partitions.sh` Kafka bin utility script. Please refer to the
+[Apache Kafka documentation](https://kafka.apache.org/documentation/#basic_ops_partitionassignment) for more information on the script usage. 
 
 > **IMPORTANT** Scaling down is currently not supported in the charm automation.  
 > If partition reassignment is not manually performed before scaling down in order 
@@ -29,16 +29,17 @@ its documentation for more information.
 ## Running Kafka Admin utility scripts
 
 Apache Kafka ships with `bin/*.sh` commands to do various administrative tasks such as:
+
 * `bin/kafka-config.sh` to update cluster configuration
 * `bin/kafka-topics.sh` for topic management
 * `bin/kafka-acls.sh` for management of ACLs of Kafka users
 
-Please refer to the upstream [Kafka project](https://github.com/apache/kafka/tree/trunk/bin), 
+Please refer to the upstream [Kafka project](https://github.com/apache/kafka/tree/trunk/bin) or its [documentation](https://kafka.apache.org/documentation/#basic_ops), 
 for a full list of the bash commands available in Kafka distributions. Also, you can 
 use `--help` argument for printing a short summary of the argument for a given 
 bash command. 
 
-These scripts can be found in the `/opt/kafka/bin` folder.
+These scripts can be found in the `/opt/kafka/bin` folder of the workload container.
 
 > **IMPORTANT** Before running bash scripts, make sure that some listeners have been correctly 
 > opened by creating appropriate integrations. Please refer to [this table](/t/charmed-kafka-k8s-documentation-reference-listeners/13270) for more 
@@ -53,20 +54,22 @@ To run most of the scripts, you need to provide:
 ### Juju admins of the Kafka deployment
 
 For Juju admins of the Kafka deployment, the bootstrap servers information can 
-be obtained using
+be obtained using the `get-admin-credentials` action output:
 
 ```
 BOOTSTRAP_SERVERS=$(juju run kafka-k8s/leader get-admin-credentials | grep "bootstrap.servers" | cut -d "=" -f 2)
 ```
 
 Admin client authentication information is stored in the 
 `/etc/kafka/client.properties` file present on every Kafka
-broker. The content of the file can be accessed using 
+container. The content of the file can be accessed using `juju ssh` command:
 
 ```
-juju ssh kafka-k8s/leader `cat /etc/kafka/client.properties`
+juju ssh --container kafka kafka-k8s/leader 'cat /etc/kafka/client.properties'
 ```
 
+where `--container kafka` is to select the Kafka workload container of the unit. By default, the charm operator container is opened.
+
 This file can be provided to the Kafka bin commands via the `--command-config`
 argument. Note that `client.properties` may also refer to other files (
 e.g. truststore and keystore for TLS-enabled connections). Those
@@ -76,25 +79,35 @@ Commands can be run within a Kafka broker, since both the authentication
 file (along with the truststore if needed) and the Charmed Kafka binaries are 
 already present. 
 
-#### Example (listing topics)
+#### Listing topics example
+
+For instance, to list the current topics on the Kafka cluster, you can run:
+
+```shell
+juju ssh --container kafka kafka-k8s/leader '/opt/kafka/bin/kafka-topics.sh --bootstrap-server $BOOTSTRAP_SERVERS --list --command-config /etc/kafka/client.properties'
+```
 
-For instance, in order to list the current topics on the Kafka cluster, you can run:
+As long as `BOOTSTRAP_SERVERS` variable contains the information we retrieved earlier in the **Juju admins of the Kafka deployment** section.
+
+For example, a full command without the usage of the variable might look like the following:
 
 ```shell
-juju ssh kafka-k8s/leader '/opt/kafka/bin/kafka-topics.sh --bootstrap-server $BOOTSTRAP_SERVERS --list --command-config /etc/kafka/client.properties'
+juju ssh --container kafka kafka-k8s/leader '/opt/kafka/bin/kafka-topics.sh --bootstrap-server kafka-k8s-0.kafka-k8s-endpoints:9092,kafka-k8s-1.kafka-k8s-endpoints:9092,kafka-k8s-2.kafka-k8s-endpoints:9092,kafka-k8s-3.kafka-k8s-endpoints:9092 --list --command-config /etc/kafka/client.properties'
 ```
 
+where `kafka-k8s-0.kafka-k8s-endpoints:9092,kafka-k8s-1.kafka-k8s-endpoints:9092,kafka-k8s-2.kafka-k8s-endpoints:9092,kafka-k8s-3.kafka-k8s-endpoints:9092` - is the contents of the `$BOOTSTRAP_SERVERS` variable.
+
 ### Juju external users
 
 For external users managed by the  [Data Integrator Charm](https://charmhub.io/data-integrator), 
-the endpoints and credentials can be fetched using the dedicated action
+the endpoints and credentials can be fetched using the dedicated action:
 
 ```shell
 juju run data-integrator/leader get-credentials --format yaml
 ```
 
 The `client.properties` file can be generated by substituting the relevant information in the 
-file available on the brokers at `/etc/kafka/client.properties`
+file available on the brokers at `/etc/kafka/client.properties`.
 
 To do so, fetch the information using `juju` commands:
 

docs/tutorial/t-deploy.md

@@ -6,7 +6,7 @@ To deploy Charmed Kafka K8s, all you need to do is run the following commands, w
 
 ```shell
 $ juju deploy zookeeper-k8s -n 3 
-$ juju deploy kafka-k8s -n 3 
+$ juju deploy kafka-k8s -n 3 --trust
 ```
 
 After this, it is necessary to connect them: