[DPE-2460] Tutorial for Kafka K8s (#64)

canonical · Oct 9, 2023 · bfa0e86 · bfa0e86
1 parent d919362
commit bfa0e86
Show file tree

Hide file tree

Showing 9 changed files with 719 additions and 23 deletions.
diff --git a/docs/how-to/h-manage-app.md b/docs/how-to/h-manage-app.md
@@ -57,7 +57,51 @@ unit-data-integrator-0:
     started: 2023-01-27 14:22:51 +0000 UTC
 ```
 
-## Internal Password rotation
+
+## Password rotation
+
+### External clients
+
+#### With client application downtime
+
+The easiest way to rotate user credentials of client applications is by removing and then re-relating 
+the application (either a charm supporting the `kafka-client` interface or a `data-integrator`) with the `kafka-k8s` charm
+
+```shell
+juju remove-relation kafka-k8s <charm-or-data-integrator>
+# wait for the relation to be torn down 
+juju relate kafka-k8s <charm-or-data-integrator>
+```
+
+The successful credential rotation can be confirmed by retrieving the new password with the action `get-credentials`.
+
+#### Without client application downtime
+
+In some use-cases credentials should be rotated with no or limited application downtime.
+If credentials should be rotated with no or limited downtine, you can deploy a new charm with the same permissions and resource definition, e.g. 
+
+```shell
+juju deploy data-integrator rotated-user --channel stable \
+  --config topic-name=test-topic --config extra-user-roles=admin
+```
+
+The `data-integrator` charm can then be related to the `kafka-k8s` charm to create a new user
+```shell
+juju relate kafka-k8s rotated-user
+```
+
+At this point, we effectively have two overlapping users, therefore allowing applications to swap the password
+from one to another. 
+If the applications consist of fleets of independent producers and consumers, user credentials can be rotated
+progressively across fleets, such that no effective downtime is achieved. 
+
+Once all applications have rotated their credentials, it is then safe to remove data first `data-integrator` charm
+
+```shell
+juju remove-application data-integrator
+```
+
+### Internal Password rotation
 
 The operator user is used internally by the Charmed Kafka Operator, the `set-password` action can be used to rotate its password.
 ```shell

diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,4 @@
-## Charmed Kafka K8s Documentation
+# Charmed Kafka K8s Documentation
 
 The Charmed Kafka K8s Operator delivers automated operations management from day 0 to day 2 on the [Apache Kafka](https://kafka.apache.org) event streaming platform deployed on top of a [Kubernetes cluster](https://kubernetes.io/). It is an open source, end-to-end, production ready data platform on top of cloud native technologies.
 
@@ -40,24 +40,3 @@ Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhan
 ## License
 
 The Charmed Kafka K8s Operator is free software, distributed under the Apache Software License, version 2.0. See [LICENSE](https://github.com/canonical/kafka-operator/blob/main/LICENSE) for more information.
-
-# Navigation
-
-| Level | Path                 | Navlink                                                                  |
-|-------|----------------------|--------------------------------------------------------------------------|
-| 1     | how-to               | [How To]()                                                               |
-| 2     | h-manage-units       | [Manage units](/t/charmed-kafka-k8s-how-to-manage-units/10295)           |
-| 2     | h-enable-encryption  | [Enable encryption](/t/charmed-kafka-k8s-how-to-enable-encryption/10289) |
-| 2     | h-manage-app         | [Manage applications](/t/charmed-kafka-k8s-how-to-manage-app/10293)      |
-| 2     | h-enable-monitoring  | [Enable Monitoring](/t/charmed-kafka-k8s-how-to-enable-monitoring/10291) |
-| 1     | reference            | [Reference]()                                                            |
-| 2     | r-actions            | [Actions](https://charmhub.io/kafka-k8s/actions)                         |
-| 2     | r-configurations     | [Configurations](https://charmhub.io/kafka-k8s/configure)                |
-| 2     | r-libraries          | [Libraries](https://charmhub.io/kafka-k8s/libraries/helpers)             |
-
-# Redirects
-
-[details=Mapping table]
-| Path | Location |
-| ---- | -------- |
-[/details]
diff --git a/docs/tutorial/t-cleanup-environment.md b/docs/tutorial/t-cleanup-environment.md
@@ -0,0 +1,21 @@
+# Cleanup and extra info
+
+This is part of the [Charmed Kafka K8s Tutorial](/t/charmed-kafka-k8s-documentation-tutorial-overview/11945). Please refer to this page for more information and the overview of the content.
+
+## Remove and cleanup environment
+If you're done with testing and would like to free up resources on your machine, just remove Multipass VM.
+*Warning: when you remove VM as shown below you will lose all the data in Kafka and any other applications inside Multipass VM!*
+```shell
+multipass delete --purge my-vm
+```
+
+## Next Steps
+
+In this tutorial we've successfully deployed Kafka, added/removed users, connected client applications and even enabled and disabled TLS. 
+If you're looking for what to do next you can:
+- Run [Charmed Kafka on VMs](https://github.com/canonical/kafka-operator).
+- Check out our Charmed offerings of [MySQL](https://charmhub.io/mysql-k8s), [PostgreSQL](https://charmhub.io/postgresql-k8s), [MongoDB](https://charmhub.io/mongodb-k8s).
+- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability)
+- [Report](https://github.com/canonical/kafka-k8s-operator/issues) any problems you encountered.
+- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform).
+- [Contribute to the code base](https://github.com/canonical/kafka-k8s-operator)
diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md
@@ -0,0 +1,122 @@
+# Get a Charmed Kafka and Zookeeper up and running
+
+This is part of the [Charmed Kafka K8s Tutorial](/t/charmed-kafka-k8s-documentation-tutorial-overview/11945). Please refer to this page for more information and the overview of the content. 
+
+## Deploy
+
+To deploy Charmed Kafka K8s, all you need to do is run the following commands, which will automatically fetch [Kafka](https://charmhub.io/kafka-k8s?channel=3/stable) and [Zookeeper](https://charmhub.io/zookeeper-k8s?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
+
+```shell
+$ juju deploy zookeeper-k8s -n 3 --channel=3/edge
+$ juju deploy kafka-k8s -n 3 --channel=3/edge
+```
+
+After this, it is necessary to connect them:
+
+```shell
+$ juju relate kafka-k8s zookeeper-k8s
+```
+
+Juju will now fetch Charmed Kafka K8s and Charmed Zookeeper K8s and begin deploying it to the local MicroK8s. 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
+```
+
+This command is useful for checking the status of Charmed Zookeeper K8s and Charmed Kafka K8s. Some of the helpful information it displays include IP pods addresses, ports, state, etc. 
+The command updates the status of the cluster every second and as the application starts you can watch the status and messages of Charmed Kafka K8s and Charmed Zookeeper K8s change. 
+
+Wait until the application is ready - when it is ready, `juju status --watch 1s` will show:
+```shell
+...
+Model     Controller  Cloud/Region        Version  SLA          Timestamp
+tutorial  microk8s    microk8s/localhost  3.1.5    unsupported  17:22:21+02:00
+
+App            Version  Status  Scale  Charm          Channel  Rev  Address         Exposed  Message
+kafka-k8s               active      3  kafka-k8s      3/edge    39  10.152.183.237  no
+zookeeper-k8s           active      3  zookeeper-k8s  3/edge    33  10.152.183.134  no
+
+Unit              Workload  Agent  Address     Ports  Message
+kafka-k8s/0       active    idle   10.1.36.78
+kafka-k8s/1       active    idle   10.1.36.80
+kafka-k8s/2*      active    idle   10.1.36.79
+zookeeper-k8s/0   active    idle   10.1.36.84
+zookeeper-k8s/1*  active    idle   10.1.36.86
+zookeeper-k8s/2   active    idle   10.1.36.85
+```
+To exit the screen with `juju status --watch 1s`, enter `Ctrl+c`.
+
+## Retrieving Kafka cluster admin credentials
+
+To watch the process, `juju status` can be used. Once all the units show as `active|idle` the credentials to access a broker can be queried with:
+```shell
+juju run kafka-k8s/leader get-admin-credentials
+```
+
+The output of the previous command is something like this:
+```shell
+Running operation 1 with 1 task
+  - task 2 on unit-kafka-k8s-2
+
+Waiting for task 2...
+client-properties: |-
+  security.protocol=SASL_PLAINTEXT
+  sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required username="admin" password="0FIQ5QxSaNfl1bXHtV5dyttb21Nbzmpp";
+  sasl.mechanism=SCRAM-SHA-512
+  bootstrap.servers=kafka-k8s-1.kafka-k8s-endpoints:9092,kafka-k8s-2.kafka-k8s-endpoints:9092,kafka-k8s-0.kafka-k8s-endpoints:9092
+password: 0FIQ5QxSaNfl1bXHtV5dyttb21Nbzmpp
+username: admin
+```
+
+Providing you the `username` and `password` of the Kafka cluster admin user. 
+
+**IMPORTANT** Note that when no other application is related to Kafka, the cluster is secured-by-default and external listeners (binded to port 9092) are disabled, thus preventing any external incoming connection. 
+
+Nevertheless, it is still possible to run a command from within the Kafka cluster. To do so, log in into one of the Kafka container in one of the units
+
+```shell
+juju ssh --container kafka kafka-k8s/leader sudo -i 
+```
+
+The Charmed Kafka K8s image ships with the Apache Kafka `bin/*.sh` commands, that can be found under `/opt/kafka/bin/`.
+These allow admin to do various administrative tasks, e.g `bin/kafka-config.sh` to update cluster configuration, `bin/kafka-topics.sh` for topic management, and many more! 
+Within the image you can also find a `client.properties` file that already provides the relevant settings to connect to the cluster using the CLI:
+
+```shell
+export CLIENT_PROPERTIES=/etc/kafka/client.properties
+```
+
+Since we don't have any client applications related yet and therefore external listeners are initially closed, if you wish to run a command from the cluster you ought to use the internal listeners exposed at ports 19092.  
+```shell
+export INTERNAL_LISTENERS=kafka-k8s-1.kafka-k8s-endpoints:19092,kafka-k8s-2.kafka-k8s-endpoints:19092,kafka-k8s-0.kafka-k8s-endpoints:19092
+```
+
+We are now ready to perform some administrative tasks. For example, in order to create a topic, you can run:
+```shell
+/opt/kafka/bin//kafka-topics.sh \
+    --create --topic test_topic \
+    --bootstrap-server  $INTERNAL_LISTENERS \
+    --command-config $CLIENT_PROPERTIES
+```
+
+You can similarly then list the topic, using
+```shell
+/opt/kafka/bin//kafka-topics.sh \
+    --list \
+    --bootstrap-server  $INTERNAL_LISTENERS \
+    --command-config $CLIENT_PROPERTIES
+```
+
+making sure the topic was successfully created.
+
+You can finally delete the topic, using 
+
+```shell
+/opt/kafka/bin//kafka-topics.sh \
+    --delete --topic test_topic \
+    --bootstrap-server  $INTERNAL_LISTENERS \
+    --command-config $CLIENT_PROPERTIES
+```
+
+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.
diff --git a/docs/tutorial/t-enable-encryption.md b/docs/tutorial/t-enable-encryption.md
@@ -0,0 +1,100 @@
+# Enable Security in your Kafka K8s deployment 
+
+This is part of the [Charmed Kafka K8s Tutorial](/t/charmed-kafka-k8s-documentation-tutorial-overview/11945). 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 K8s. This means (re-)configuring TLS on Charmed Kafka K8s 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 K8s to the [TLS Certificates Charm](https://charmhub.io/tls-certificates-operator). The TLS Certificates Charm centralises TLS certificate management in a consistent manner and handles providing, requesting, and renewing TLS certificates. 
+
+> *Note: In this tutorial, we will distribute [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) to all charms (Kafka, Zookeeper and client applications) that are signed using a root self-signed CA
+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.*
+
+### Configure TLS
+Before enabling TLS on Charmed Kafka K8s we must first deploy the `tls-certificates-operator` charm:
+```shell
+juju deploy tls-certificates-operator \
+  --channel stable \
+  --config generate-self-signed-certificates="true" --config ca-common-name="Tutorial CA"
+```
+
+Wait for the charm settles into an `active/idle` state, as shown by the `juju status`
+
+```shell
+Model     Controller  Cloud/Region        Version  SLA          Timestamp
+tutorial  microk8s    microk8s/localhost  3.1.5    unsupported  21:32:35+02:00
+
+App                        Version  Status  Scale  Charm                      Channel    Rev  Exposed  Message
+...
+tls-certificates-operator           active      1  tls-certificates-operator  stable     22   no       
+...
+
+Unit                          Workload  Agent  Address    Ports  Message
+...
+tls-certificates-operator/0*  active    idle   10.1.36.91        
+...
+```
+
+To enable TLS on Charmed Kafka K8s, relate the both the `kafka-k8s` and `zookeeper-k8s` charms with the
+`tls-certificates-operator` charm:
+```shell
+juju relate zookeeper-k8s tls-certificates-operator
+juju relate kafka-k8s tls-certificates-operator
+```
+
+After the charms settle into `active/idle` states, the Kafka listeners should now have been swapped to the 
+default encrypted port 9093. This can be tested by testing whether the ports are open/closed with `telnet`
+
+```shell
+telnet <IP> 9092 
+telnet <IP> 9093
+```
+
+### Enable TLS encrypted connection
+
+Once the Kafka cluster is enabled to use encrypted connection, client applications should be configured as well to connect to
+the correct port as well as trust the self-signed CA provided by the `tls-certificates-operator` charm. 
+
+Make sure that the `kafka-test-app` is not connected to the Kafka charm, by removing the relation if it exists
+
+```shell
+juju remove-relation kafka-test-app kafka-k8s
+```
+
+Then enable encryption on the `kafka-test-app` by relating with the `tls-certificates-operator` charm
+
+```shell
+juju relate kafka-test-app tls-certificates-operator
+```
+
+We can then set up the `kafka-test-app` to produce messages with the usual configuration (note that there is no difference 
+here with the unencrypted workflow)
+
+```shell
+juju config kafka-test-app topic_name=test_encryption_topic role=producer num_messages=25
+```
+
+and then relate with the `kafka-k8s` cluster
+
+```shell
+juju relate kafka-k8s kafka-test-app
+```
+
+As before, you can check that the messages are pushed into the Kafka cluster by inspecting the logs
+
+```shell
+juju exec --application kafka-test-app "tail /tmp/*.log"
+```
+
+Note that if the `kafka-test-app` was running before, there may be multiple logs related to the different
+runs. Refer to the latest logs produced and also check that in the logs the connection is indeed established 
+with the encrypted port 9093. 
+
+### Remove external TLS certificate
+To remove the external TLS and return to the locally generate one, un-relate applications:
+```shell
+juju remove-relation kafka-k8s tls-certificates-operator
+juju remove-relation zookeeper-k8s tls-certificates-operator
+```
+
+The Charmed Kafka K8s application is not using TLS anymore.