diff --git a/docs/how-to/h-deploy.md b/docs/how-to/h-deploy.md index 24a7cd2e..ee98d9ac 100644 --- a/docs/how-to/h-deploy.md +++ b/docs/how-to/h-deploy.md @@ -1,104 +1,111 @@ # How to deploy Charmed Kafka K8s -To deploy a Charmed Kafka K8s cluster on a bare environment, it is necessary to: +> **IMPORTANT** For non-K8s Charmed Kafka, see the [Charmed Kafka documentation](/t/charmed-kafka-documentation/13261) instead. + +To deploy a Charmed Kafka K8s cluster: 1. Set up a Juju Controller 2. Set up a Juju Model -3. Deploy Charmed Kafka K8s and Charmed ZooKeeper K8s +3. Deploy and relate Kafka K8s and ZooKeeper K8s charms. 4. (Optionally) Create an external admin user -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 -Before deploying Kafka, make sure you have a Juju controller accessible from +Make sure you have a Juju controller accessible from your local environment using the [Juju client snap](https://snapcraft.io/juju). -The properties of your current controller can be listed using `juju show-controller`. -Make sure that the controller's backend cloud **is** K8s. -The cloud information can be retrieved with the following command +List available controllers: + +```commandline +juju list-controllers +``` + +Switch to another controller if needed: + +```commandline +juju switch +``` + +If there are no suitable controllers, create a new one: ```commandline -juju show-controller | yq '.[].details.cloud' +juju bootstrap ``` -> **IMPORTANT** If the cloud is **not** `k8s`, please refer to the [Charmed Kafka documentation](/t/charmed-kafka-documentation/10288) instead. +where `` -- the cloud to deploy controller to, e.g., `localhost`. For more information on how to setup a new cloud, see the [How to manage clouds](https:///t/1100) guide in Juju documentation. -You can find more information on how to bootstrap and configure a controller for different -clouds [here](https://juju.is/docs/juju/manage-controllers#heading--bootstrap-a-controller). -Make sure you bootstrap a `k8s` Juju controller. +> **Note** See the [How to manage controllers](/t/1111) guide in Juju documentation for more options. ## Juju Model setup You can create a new Juju model using -``` +```commandline juju add-model ``` -Alternatively, you can use a pre-existing Juju model and switch to it by running the following command: +Alternatively, you can switch to any existing Juju model: -``` -juju switch +```commandline +juju switch ``` -Make sure that the model is **not** a `k8s` type. The type of the model -can be obtained by +Make sure that the model is of a correct type (`k8s`): -``` +```commandline juju show-model | yq '.[].type' ``` -> **IMPORTANT** If the model is **not** `k8s`, please refer to the [Charmed Kafka documentation](/t/charmed-kafka-documentation/10288) instead. - - -## Deploy Charmed Kafka K8s and Charmed ZooKeeper +## Deploy and relate Kafka K8s and ZooKeeper charms The Kafka and ZooKeeper charms can both be deployed as follows: -```shell -$ juju deploy zookeeper-k8s --channel 3/edge -n -$ juju deploy kafka-k8s --channel 3/edge -n +```commandline +juju deploy kafka-k8s --channel 3/edge -n +juju deploy zookeeper-k8s --channel 3/edge -n ``` -After this, it is necessary to connect them: -```shell -$ juju relate kafka-k8s zookeeper-k8s +where `` and `` -- the number of units to deploy for Kafka and ZooKeeper. We recommend values of at least `3` and `5` respectively. + +Connect ZooKeeper and Kafka by relating/integrating the charms: + +```commandline +juju relate kafka-k8s zookeeper-k8s ``` -> We recommend values for `` of at least 3 and for `` of 5, to -ensure reasonable high-availability margins. +Check the status of the deployment: + +```commandline +juju status +``` -Once all the units show as `active|idle` in the `juju status` output, the deployment -should be ready to be used. +Once all the units show `active` or `idle` status, the deployment should be complete. ## (Optional) Create an external admin users Charmed Kafka aims to follow the _secure by default_ paradigm. As a consequence, after being deployed the Kafka cluster won't expose any external listener. In fact, ports are only opened when client applications are related, also -depending on the protocols to be used. Please refer to [this table](TODO) for -more information about the available listeners and protocols. +depending on the protocols to be used. +> **NOTE** For more information about the available listeners and protocols please refer to [this table](/t/13270). -It is however generally useful for most of the use-cases to create a first admin user +It is however generally useful for most situations to create a first admin user to be used to manage the Kafka cluster (either internally or externally). To create an admin user, deploy the [Data Integrator Charm](https://charmhub.io/data-integrator) with -`extra-user-roles` set to `admin` +`extra-user-roles` set to `admin`: -```shell +```commandline juju deploy data-integrator --channel stable --config topic-name=test-topic --config extra-user-roles=admin ``` -and relate to the Kafka charm +... and relate it to the Kafka charm: -```shell +```commandline juju relate data-integrator kafka-k8s ``` -To retrieve authentication information such as the username, password, etc. use +To retrieve authentication information, such as the username and password, use: -```shell +```commandline juju run data-integrator/leader get-credentials ``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d009b8bb..19a38e4c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Charmed Kafka K8s Documentation +# Charmed Kafka K8s documentation Charmed Kafka K8s is an open-source operator that makes it easier to manage Apache Kafka on Kubernetes, with built-in support for enterprise features. @@ -6,7 +6,7 @@ Charmed Kafka K8s is built on top of [Juju](https://juju.is/) and reliably simpl Charmed Kafka K8s operates Apache Kafka on different Kubernetes distributions, featuring support for both on-premise installation (e.g. using MicroK8s) or cloud services (e.g. AWS EKS). Charmed Kafka K8s is a solution designed and developed for helping ops teams and -administrators to automate Apache Kafka operations from day 0 to day 2, across multiple cloud environments and platforms. +administrators to automate Apache Kafka operations from Day 0 to Day 2, across multiple cloud environments and platforms. [note] Canonical has also developed the [Charmed Kafka operator](/t/charmed-kafka-documentation/10288) to support Kafka in VM/IAAS environments. @@ -14,14 +14,14 @@ Canonical has also developed the [Charmed Kafka operator](/t/charmed-kafka-docum Charmed Kafka K8s is developed and supported by [Canonical](https://canonical.com/), as part of its commitment to provide open-source, self-driving solutions, seamlessly integrated using the Operator Framework Juju. Please -refer to [charmhub.io](https://charmhub.io/), for more charmed operators integrated in the Juju ecosystem. +refer to [Charmhub.io](https://charmhub.io/), for more Charmed operators that can be integrated by Juju. ## In this documentation | | | |--|--| | [Tutorials](/t/charmed-kafka-k8s-tutorial-overview/11945)
Get started - a hands-on introduction to using Charmed Kafka K8s operator for new users
| [How-to guides](/t/charmed-kafka-k8s-how-to-manage-units/10295)
Step-by-step guides covering key operations and common tasks | -| [Reference](https://charmhub.io/kafka-k8s/actions?channel=3/stable)
Technical information - specifications, APIs, architecture | [Explanation]()
Concepts - discussion and clarification of key topics | +| [Reference](/t/13269)
Technical information - specifications, APIs, architecture | | ## Project and community @@ -34,4 +34,4 @@ Charmed Kafka K8s is a distribution of Apache Kafka. It’s an open-source proje ## 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. +The Charmed Kafka K8s Operator is free software, distributed under the Apache Software License, version 2.0. See [LICENSE](https://github.com/canonical/kafka-k8s-operator/blob/main/LICENSE) for more information. diff --git a/docs/tutorial/t-setup-environment.md b/docs/tutorial/t-setup-environment.md index 5eeecae9..19702bcb 100644 --- a/docs/tutorial/t-setup-environment.md +++ b/docs/tutorial/t-setup-environment.md @@ -7,7 +7,7 @@ This is part of the [Charmed Kafka Tutorial](/t/charmed-kafka-k8s-documentation- Let's install Multipass from [Snap](https://snapcraft.io/multipass) and launch a new VM using "[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)" cloud-init config: ```shell sudo snap install multipass && \ -multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs +multipass launch --cpus 4 --memory 8G --disk 50G --name my-vm charm-dev ``` *Note: all 'multipass launch' params are [described here](https://multipass.run/docs/launch-command)*.