From 703c00345bcf3638859a074f689088640a38e66e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 1 Oct 2024 09:50:51 +0100 Subject: [PATCH] [discourse-gatekeeper] Update deployment instructions with stable track and trust (#134) Co-authored-by: upload-charms-docs-bot --- docs/how-to/h-deploy.md | 6 ++++-- docs/how-to/h-manage-units.md | 39 +++++++++++++++++++++++------------ docs/tutorial/t-deploy.md | 2 +- 3 files changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/how-to/h-deploy.md b/docs/how-to/h-deploy.md index bb456dee..b705d4fb 100644 --- a/docs/how-to/h-deploy.md +++ b/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 -juju deploy zookeeper-k8s --channel 3/edge -n +juju deploy kafka-k8s --channel 3/stable -n --trust +juju deploy zookeeper-k8s --channel 3/stable -n ``` where `` and `` -- 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 diff --git a/docs/how-to/h-manage-units.md b/docs/how-to/h-manage-units.md index d0815002..a67a7409 100644 --- a/docs/how-to/h-manage-units.md +++ b/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 @@ -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,7 +54,7 @@ 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) @@ -61,12 +62,14 @@ BOOTSTRAP_SERVERS=$(juju run kafka-k8s/leader get-admin-credentials | grep "boot 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: diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md index b92c7c46..1bbbe5c8 100644 --- a/docs/tutorial/t-deploy.md +++ b/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: