[DPE-3488] Adding kafka-test-app usage in tutorial (#169)

docs/index.md

@@ -4,7 +4,7 @@ The Charmed Kafka Operator delivers automated operations management from day 0 t
 
 This operator charm comes with features such as:
 - Fault-tolerance, replication, scalability and high-availability out-of-the-box.
-- SASL/SCRAM auth for Broker-Broker and Client-Broker authenticaion enabled by default.
+- SASL/SCRAM auth for Broker-Broker and Client-Broker authentication enabled by default.
 - Access control management supported with user-provided ACL lists.
 
 The Kafka Operator uses the latest upstream Kafka binaries released by the The Apache Software Foundation that comes with Kafka, made available using the [`charmed-kafka` snap ](https://snapcraft.io/charmed-kafka) distributed by Canonical.
@@ -24,7 +24,7 @@ Charmed Kafka is an official distribution of Apache Kafka. It’s an open-source
 - [Join the Discourse forum](/tag/kafka)
 - [Contribute](https://github.com/canonical/kafka-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/kafka-operator/issues/new)
 - Explore [Canonical Data Fabric solutions](https://canonical.com/data)
-- [Contacts us]([/t/13107) for all further questions
+- [Contact us]([/t/13107) for all further questions
 
 ## In this documentation
 

docs/tutorial/t-cleanup-environment.md

@@ -1,8 +1,7 @@
-# Cleanup and extra info
-
 This is part of the [Charmed Kafka Tutorial](/t/charmed-kafka-tutorial-overview/10571). Please refer to this page for more information and the overview of the content. 
 
-## Remove Charmed Kafka and Juju
+## Cleanup your environment 
+
 If you're done using Charmed Kafka and Juju and would like to free up resources on your machine, you can remove Charmed Kafka, Charmed Zookeeper and Juju. 
 *Warning: when you remove Charmed Kafka as shown below you will lose all the data in Kafka. Further, when you remove Juju as shown below you will lose access to any other applications you have hosted on Juju.*
 
@@ -21,7 +20,7 @@ Finally to remove Juju altogether, enter:
 sudo snap remove juju --purge
 ```
 
-## Next Steps
+## What's next?
 
 In this tutorial we've successfully deployed Kafka, added/removed replicas, added/removed users to/from the cluster, and even enabled and disabled TLS. 
 You may now keep your Charmed Kafka deployment running or remove it entirely using the steps in [Remove Charmed Kafka and Juju](#remove-charmed-kafka-and-juju). 
@@ -30,5 +29,5 @@ If you're looking for what to do next you can:
 - Check out our Charmed offerings of [PostgreSQL](https://charmhub.io/postgresql?channel=edge) and [MongoDB](https://charmhub.io/mongodb?channel=5/edge).
 - Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability)
 - [Report](https://github.com/canonical/kafka-operator/issues) any problems you encountered.
-- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform).
+- [Give us your feedback](https://matrix.to/#/#charmhub-data-platform:ubuntu.com).
 - [Contribute to the code base](https://github.com/canonical/kafka-operator)

docs/tutorial/t-deploy.md

@@ -1,8 +1,6 @@
-# Get a Charmed Kafka and Zookeeper up and running
-
 This is part of the [Charmed Kafka Tutorial](/t/charmed-kafka-tutorial-overview/10571). Please refer to this page for more information and the overview of the content. 
 
-## Deploy
+## Deploy Charmed Kafka (and Charmed Zookeeper)
 
 To deploy Charmed Kafka, all you need to do is run the following commands, which will automatically fetch [Kafka](https://charmhub.io/kafka?channel=3/stable) and [Zookeeper](https://charmhub.io/zookeeper?channel=3/stable) charms from [Charmhub](https://charmhub.io/) and deploy them to your model. For example, to deploy a 5 Zookeeper unit and 3 Kafka unit cluster, you can simply run
 
@@ -17,7 +15,7 @@ After this, it is necessary to connect them:
 $ juju relate kafka zookeeper
 ```
 
-Juju will now fetch Charmed Kafka and Zookeeper and begin deploying it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU,etc) your machine is. You can track the progress by running:
+Juju will now fetch Charmed Kafka and Zookeeper and begin deploying it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is. You can track the progress by running:
 ```shell
 juju status --watch 1s
 ```
@@ -95,7 +93,7 @@ When the unit is started, the Charmed Kafka Operator installs the [`charmed-kafk
 Within the machine, the Charmed Kafka Operator also creates a `client.properties` file that already provides the relevant settings to connect to the cluster using the CLI
 
 ```shell
-CLIENT_PROPERTIES= /var/snap/charmed-kafka/current/etc/kafka/client.properties
+CLIENT_PROPERTIES=/var/snap/charmed-kafka/current/etc/kafka/client.properties
 ```
 
 For example, in order to create a topic, you can run:
@@ -130,6 +128,8 @@ Other available Kafka bin commands can also be found with:
 snap info charmed-kafka
 ```
 
+## What's next?
+
 However, although the commands above can run within the cluster, it is generally recommended during operations
 to enable external listeners and use these for running the admin commands from outside the cluster. 
 To do so, as we will see in the next section, we will deploy a [data-integrator](https://charmhub.io/data-integrator) charm and relate it to Kafka.

docs/tutorial/t-enable-encryption.md

@@ -1,8 +1,7 @@
-# Enable Security in your Kafka deployment 
-
 This is part of the [Charmed Kafka Tutorial](/t/charmed-kafka-tutorial-overview/10571). Please refer to this page for more information and the overview of the content. 
 
 ## Transport Layer Security (TLS)
+
 [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) is used to encrypt data exchanged between two applications; it secures data transmitted over the network. Typically, enabling TLS within a highly available database, and between a highly available database and client/server applications, requires domain-specific knowledge and a high level of expertise. Fortunately, the domain-specific knowledge has been encoded into Charmed Kafka. This means (re-)configuring TLS on Charmed Kafka is readily available and requires minimal effort on your end.
 
 Again, relations come in handy here as TLS is enabled via relations; i.e. by relating Charmed Kafka to the [Self-signed Certificates Charm](https://charmhub.io/self-signed-certificates) via the [`tls-certificates`](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/tls_certificates/v1/README.md) charm relations. The `tls-certificates` relation centralises TLS certificate management in a consistent manner and handles providing, requesting, and renewing TLS certificates, making it possible to use different providers, like the self-signed certificates but also other services, e.g. Let's Encrypt. 
@@ -11,7 +10,7 @@ Again, relations come in handy here as TLS is enabled via relations; i.e. by rel
 that is also trusted by all applications. This setup is only for show-casing purposes and self-signed certificates should **never** be used in a production cluster. For more information about which charm may better suit your use-case, please refer to [this post](https://charmhub.io/topics/security-with-x-509-certificates).* 
 
 ### Configure TLS
-Before enabling TLS on Charmed Kafka we must first deploy the `tls-certificates-operator` charm:
+Before enabling TLS on Charmed Kafka we must first deploy the `self-signed-certificates` charm:
 ```shell
 juju deploy self-signed-certificates --config ca-common-name="Tutorial CA"
 ```
@@ -59,7 +58,7 @@ Make sure that the `kafka-test-app` is not connected to the Kafka charm, by remo
 juju remove-relation kafka-test-app kafka
 ```
 
-Then enable encryption on the `kafka-test-app` by relating with the `tls-certificates-operator` charm
+Then enable encryption on the `kafka-test-app` by relating with the ` self-signed-certificates` charm
 
 ```shell
 juju relate kafka-test-app self-signed-certificates

docs/tutorial/t-manage-passwords.md

@@ -1,13 +1,15 @@
-# Manage Passwords
-
 This is part of the [Charmed Kafka Tutorial](/t/charmed-kafka-tutorial-overview/10571). Please refer to this page for more information and the overview of the content.
 
-## Passwords
+## Manage Passwords
+
+Passwords help to secure our cluster and are essential for security. Over time it is a good practice to change the password frequently. Here we will go through setting and changing the password both for the admin user and external Kafka users managed by the data-integrator.
+
+### Admin user
+
+The admin user password management is handled directing by the charm, by using Juju actions. 
 
-When we accessed Kafka earlier in this tutorial, we needed to include a password in the connection parameters. 
-Passwords help to secure our cluster and are essential for security. Over time it is a good practice to change the password frequently. Here we will go through setting and changing the password for the admin user.
+#### Retrieve the admin password
 
-### Retrieve the admin password
 As previously mentioned, the admin password can be retrieved by running the `get-admin-credentials` action on the Charmed Kafka application:
 ```shell
 juju run kafka/leader get-admin-credentials
@@ -33,8 +35,8 @@ unit-kafka-1:
 ```
 The admin password is under the result: `password`.
 
+#### Rotate the admin password
 
-### Rotate the admin password
 You can change the admin password to a new random password by entering:
 ```shell
 juju run kafka/leader set-password username=admin
@@ -56,7 +58,7 @@ The admin password is under the result: `admin-password`. It should be different
 
 > **Note** When changing the admin password you will also need to update the admin password the in Kafka connection parameters; as the old password will no longer be valid.*
 
-### Set the admin password
+#### Set the admin password
 You can change the admin password to a specific password by entering:
 ```shell
 juju run kafka/leader set-password username=admin password=<password>
@@ -78,28 +80,11 @@ The admin password under the result: `admin-password` should match whatever you
 
 > **Note** When changing the admin password you will also need to update the admin password in the Kafka connection parameters, as the old password will no longer be valid.*
 
-### Kafka Users
-
-As mentioned in the previous section of the Tutorial, the recommended way to create and manage users is by means of the data-integrator charm. 
-This will allow us to encode users directly in the Juju model, and - as shown in the following - to rotate user credentials rotations with and without application downtime.   
-
-### Deploy the data-integrator 
-
-To deploy a `data-integrator` simply issue the following command:
+### External Kafka users
 
-```
-juju deploy data-integrator --config extra-user-roles=producer --config topic-name=test-topic
-```
-
-*(here we assumed to create an producer user (possible roles for Kafka are producer, consumer and admin)*
-
-Then related the `data-integrator` with `kafka`:
-
-```
-juju relate data-integrator kafka
-```
+Unlike Admin management, the password management for external Kafka users is instead managed using relations. Let's see this into play with the Data Integrator charm, that we have deployed in the previous part of the tutorial.
 
-### Retrieve the password
+#### Retrieve the password
 
 Similarly to the Kafka application, also the `data-integrator` exposes an action to retrieve the credentials, e.g. 
 ```shell
@@ -119,7 +104,7 @@ ok: "True"
 
 As before, the admin password is under the result: `password`.
 
-### Rotate the password
+#### Rotate the password
 
 The easiest way to rotate user credentials using the `data-integrator` is by removing and then re-relating the `data-integrator` with the `kafka` charm
 
@@ -147,4 +132,52 @@ kafka:
 ok: "True"
 ```
 
-In order to rotate external password with no or limited downtime, please refer to the how-to guide on [app management](/t/charmed-kafka-how-to-manage-app/10285).
+In order to rotate external password with no or limited downtime, please refer to the how-to guide on [app management](/t/charmed-kafka-how-to-manage-app/10285).
+
+#### Remove the user
+
+To remove the user, remove the relation. Removing the relation automatically removes the user that was created when the relation was created. Enter the following to remove the relation:
+```shell
+juju remove-relation kafka data-integrator
+```
+
+The output of the juju model should be something like this:
+
+```shell
+Model     Controller  Cloud/Region         Version  SLA          Timestamp
+tutorial  overlord    localhost/localhost  3.1.6    unsupported  10:20:59Z
+
+App              Version  Status   Scale  Charm            Channel      Rev  Exposed  Message
+data-integrator           blocked      1  data-integrator  stable        11  no       Please relate the data-integrator with the desired product
+kafka                     active       3  kafka            3/stable     147  no       
+zookeeper                 active       5  zookeeper        3/stable     114  no       
+
+Unit                Workload  Agent  Machine  Public address  Ports  Message
+data-integrator/0*  blocked   idle   8        10.244.26.4            Please relate the data-integrator with the desired product
+kafka/0             active    idle   5        10.244.26.43           
+kafka/1*            active    idle   6        10.244.26.6            
+kafka/2             active    idle   7        10.244.26.19           
+zookeeper/0         active    idle   0        10.244.26.251          
+zookeeper/1         active    idle   1        10.244.26.129          
+zookeeper/2         active    idle   2        10.244.26.121          
+zookeeper/3*        active    idle   3        10.244.26.28           
+zookeeper/4         active    idle   4        10.244.26.174          
+
+Machine  State    Address        Inst id        Series  AZ  Message
+0        started  10.244.26.251  juju-f1a2cd-0  jammy       Running
+1        started  10.244.26.129  juju-f1a2cd-1  jammy       Running
+2        started  10.244.26.121  juju-f1a2cd-2  jammy       Running
+3        started  10.244.26.28   juju-f1a2cd-3  jammy       Running
+4        started  10.244.26.174  juju-f1a2cd-4  jammy       Running
+5        started  10.244.26.43   juju-f1a2cd-5  jammy       Running
+6        started  10.244.26.6    juju-f1a2cd-6  jammy       Running
+7        started  10.244.26.19   juju-f1a2cd-7  jammy       Running
+8        started  10.244.26.4    juju-f1a2cd-8  jammy       Running
+```
+
+
+> **Note** The operations above would also apply to charmed applications that implement  the `kafka_client` relation, for which password rotation and user deletion can be achieved in the same consistent way.
+
+## What's next?
+
+In the next part, we will now see how easy it is to enable encryption across the board, to make sure no one is eavesdropping, sniffing or snooping your traffic by enabling TLS.

docs/tutorial/t-overview.md

@@ -17,12 +17,22 @@ While this tutorial intends to guide and teach you as you deploy Charmed Kafka,
 - Basic terminal commands.
 - Kafka concepts such as replication and users.
 
+## Minimum requirements
+
+Before we start, make sure your machine meets the following requirements:
+
+* Ubuntu 20.04 (Focal) or later.
+* 8GB of RAM.
+* 2 CPU threads.
+* At least 20GB of available storage.
+* Access to the internet for downloading the required snaps and charms.
+
 ## Step-by-step guide
 
 Here’s an overview of the steps required with links to our separate tutorials that deal with each individual step:
 * [Set up the environment](/t/charmed-kafka-tutorial-setup-environment/10575)
 * [Deploy Kafka](/t/charmed-kafka-tutorial-deploy-kafka/10567)
+* [Integrate with client applications](/t/charmed-kafka-tutorial-relate-kafka/10573)
 * [Manage passwords](/t/charmed-kafka-tutorial-manage-passwords/10569)
-* [Relate your Kafka to other applications](/t/charmed-kafka-tutorial-relate-kafka/10573)
 * [Enable encryption](/t/charmed-kafka-documentation-tutorial-enable-security/12043)
 * [Cleanup your environment](/t/charmed-kafka-tutorial-cleanup-environment/10565)