From 1ac2a2eeefcdcafe2319d922168af05f90213ea4 Mon Sep 17 00:00:00 2001 From: Mateo Florido Date: Fri, 10 Jan 2025 13:51:37 -0500 Subject: [PATCH 1/5] Add Basic Operations with the Charm --- docs/src/charm/tutorial/basic-operations.md | 167 ++++++++++++++++++++ docs/src/charm/tutorial/getting-started.md | 127 ++------------- docs/src/charm/tutorial/index.md | 1 + 3 files changed, 179 insertions(+), 116 deletions(-) create mode 100644 docs/src/charm/tutorial/basic-operations.md diff --git a/docs/src/charm/tutorial/basic-operations.md b/docs/src/charm/tutorial/basic-operations.md new file mode 100644 index 000000000..29dc4b54d --- /dev/null +++ b/docs/src/charm/tutorial/basic-operations.md @@ -0,0 +1,167 @@ +# Basic operations with the charm + +This tutorial walks you through common management tasks for your {{ product }} +cluster using the `k8s` charm. You'll learn how to scale your cluster, manage +workers, and interact with it using `kubectl`. + +## What you will need + +- A running {{ product }} cluster deployed with the `k8s` charm +- The Juju [client][Juju client] +- [Kubectl] (installation instructions included below) + +## Scaling Your Cluster + +The `k8s` charm provides flexibility to scale your cluster as needed by adding +or removing control plane nodes or worker nodes. + +To increase the control plane's capacity or ensure high availability, you can +add more units to the `k8s` application: + +``` +juju add-unit k8s -n 2 +``` + +```{tip} +For high availability, we recommend deploying at least three `k8s` charm units. +``` + +Similarly, you can add more worker nodes when your workload demands increase: + +``` +juju add-unit k8s-worker -n 1 +``` + +This command deploys an additional instance of the `k8s-worker` charm. Juju +manages all instances within the same application, so no extra configuration +is needed. After running this command, new units will appear in your cluster, +such as `k8s-worker/0` and `k8s-worker/1`. + +To scale up multiple units at once, adjust the unit count: + +``` +juju add-unit k8s-worker -n 3 +``` + +If you need to scale down the cluster, you can remove units as follows: + +``` +juju remove-unit k8s-worker/1 +``` + +Replace the unit name with the appropriate application name (e.g., `k8s` or +`k8s-worker`) and unit number. + + +## Set up `kubectl` + +[kubectl][] is the standard upstream tool for interacting with a Kubernetes +cluster. This is the command that can be used to inspect and manage your +cluster. + +If you don't already have `kubectl`, it can be installed from a snap: + +``` +sudo snap install kubectl --classic +``` + +If you have just installed it, you should also create a file to contain the configuration: + +``` +mkdir ~/.kube +``` + +To fetch the configuration information from the cluster we can run: + +``` +juju run k8s/0 get-kubeconfig +``` + +The Juju action is a piece of code which runs on a unit to perform a specific +task. In this case it collects the cluster information - the YAML formatted +details of the cluster and the keys required to connect to it. + +```{warning} +If you already have `kubectl` and are using it to manage other clusters, you +should edit the relevant parts of the cluster yaml output and append them to +your current kubeconfig file. +``` + +We can use pipe to append your cluster's kubeconfig information directly to a +config file which will just require a bit of editing: + +``` +juju run k8s/0 get-kubeconfig >> ~/.kube/config +``` + +The output includes the root of the YAML, `kubeconfig: |`, so we can just use an +editor to remove that line: + +``` +vim ~/.kube/config +``` + +Please use the editor of your choice to delete the first line and save the file. + +Alternatively, if you are a `yq` user, the same can be achieved with: + +``` +juju run k8s/0 get-kubeconfig | yq '.kubeconfig' -r >> ~/.kube/config +``` + +You can now confirm Kubectl can read the kubeconfig file: + +``` +kubectl config show +``` + +...which should output something like this: + +``` +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: DATA+OMITTED + server: https://10.158.52.236:6443 + name: k8s +contexts: +- context: + cluster: k8s + user: k8s-user + name: k8s +current-context: k8s +kind: Config +preferences: {} +users: +- name: k8s-user + user: + token: REDACTED +``` + +You can then further confirm that it is possible to inspect the cluster by +running a simple command such as : + +``` +kubectl get pods -A +``` + +This should return some pods, confirming the command can reach the cluster. + +## Next steps + +Now that you're familiar with basic cluster operations, you might want to: + +- Deploy applications to your cluster +- Configure storage solutions like [Ceph] +- Set up monitoring and observability with [Canonical Observability Stack][COS] + +For more advanced operations and updates, keep an eye on the charm's +documentation and release [notes][release notes]. + + + +[Ceph]: ../howto/ceph-csi +[COS]: ../howto/cos-lite +[Juju client]: https://juju.is/docs/juju/install-and-manage-the-client +[Kubectl]: https://kubernetes.io/docs/reference/kubectl/ +[release notes]: ../reference/releases diff --git a/docs/src/charm/tutorial/getting-started.md b/docs/src/charm/tutorial/getting-started.md index 40255b9ea..ee4961c74 100644 --- a/docs/src/charm/tutorial/getting-started.md +++ b/docs/src/charm/tutorial/getting-started.md @@ -12,11 +12,10 @@ Kubernetes and some common first steps. - How to install {{product}} - Making a cluster - Deploying extra workers -- Using Kubectl +- Using `kubectl` ## What you will need -- Ubuntu 22.04 LTS or 20.04 LTS - The [Juju client][] - Access to a Juju-supported cloud for creating the required instances - [Kubectl] for interacting with the cluster (installation instructions are @@ -84,8 +83,8 @@ juju status --watch 2s When the status reports that K8s is "idle/ready" you have successfully deployed a {{product}} control-plane using Juju. -```{note} For High Availability you will need at least three units of the k8s - charm. Scaling the deployment is covered below. +```{note} +For High Availability you will need at least three units of the `k8s` charm. ``` ## 3. Deploy a worker @@ -110,128 +109,23 @@ fetched earlier also includes a list of the relations possible, and from this we can see that the k8s-worker requires "cluster: k8s-cluster". To connect these charms and effectively add the worker to our cluster, we use -the 'integrate' command, adding the interface we wish to connect. +the `integrate` command, adding the interface we wish to connect. ``` juju integrate k8s k8s-worker:cluster +juju integrate k8s k8s-worker:containerd +juju integrate k8s k8s-worker:cos-tokens ``` After a short time, the worker node will share information with the control plane and be joined to the cluster. -## 4. Scale the cluster (Optional) - -If one worker doesn't seem like enough, we can easily add more: - -``` -juju add-unit k8s-worker -n 1 -``` - -This will create an additional instance running the k8s-worker charm. Juju -manages all instances of the same application together, so there is no need to -add the integration again. If you check the Juju status, you should see that a -new unit is created, and now you have `k8s-worker/0` and `k8s-worker/1` - - -## 5. Use Kubectl - -[Kubectl][] is the standard upstream tool for interacting with a Kubernetes -cluster. This is the command that can be used to inspect and manage your -cluster. - -If you don't already have `kubectl`, it can be installed from a snap: - -``` -sudo snap install kubectl --classic -``` - -If you have just installed it, you should also create a file to contain the configuration: - -``` -mkdir ~/.kube -``` - -To fetch the configuration information from the cluster we can run: - -``` -juju run k8s/0 get-kubeconfig -``` - -The Juju action is a piece of code which runs on a unit to perform a specific -task. In this case it collects the cluster information - the YAML formatted -details of the cluster and the keys required to connect to it. - -```{warning} If you already have Kubectl and are using it to manage other clusters, - you should edit the relevant parts of the cluster yaml output and append them to - your current kubeconfig file. -``` - -We can use pipe to append your cluster's kubeconfig information directly to a -config file which will just require a bit of editing: - -``` -juju run k8s/0 get-kubeconfig >> ~/.kube/config -``` - -The output includes the root of the YAML, `kubeconfig: |`, so we can just use an -editor to remove that line: - -``` -nano ~/.kube/config -``` - -Please use the editor of your choice to delete the first line and save the file. - -Alternatively, if you are a `yq` user, the same can be achieved with: - -``` -juju run k8s/0 get-kubeconfig | yq '.kubeconfig' -r >> ~/.kube/config -``` - -You can now confirm Kubectl can read the kubeconfig file: - -``` -kubectl config show -``` - -...which should output something like this: - -``` -apiVersion: v1 -clusters: -- cluster: - certificate-authority-data: DATA+OMITTED - server: https://10.158.52.236:6443 - name: k8s -contexts: -- context: - cluster: k8s - user: k8s-user - name: k8s -current-context: k8s -kind: Config -preferences: {} -users: -- name: k8s-user - user: - token: REDACTED -``` - -You can then further confirm that it is possible to inspect the cluster by -running a simple command such as : - -``` -kubectl get pods -A -``` - -This should return some pods, confirming the command can reach the cluster. - ## Next steps -Congratulations - you now have a functional Kubernetes cluster! In the near -future more charms are on the way to simplify usage and extend the base -functionality of {{product}}. Bookmark the [releases page] to keep -informed of updates. +Congratulations — you now have a functional {{ product }} cluster! You can +start exploring the [basic operations] with the charm. In the near future more +charms are on the way to simplify usage and extend the base functionality of +{{product}}. Bookmark the [releases page] to keep informed of updates. @@ -240,3 +134,4 @@ informed of updates. [Kubectl]: https://kubernetes.io/docs/reference/kubectl/ [the channel explanation page]: ../../snap/explanation/channels [releases page]: ../reference/releases +[basic operations]: ./basic-operations.md diff --git a/docs/src/charm/tutorial/index.md b/docs/src/charm/tutorial/index.md index 17ef956b7..82f468165 100644 --- a/docs/src/charm/tutorial/index.md +++ b/docs/src/charm/tutorial/index.md @@ -12,6 +12,7 @@ Overview :glob: :titlesonly: getting-started +basic-operations ``` --- From fde7d522368ce2c0cfb74077c282361c5f0fa0d5 Mon Sep 17 00:00:00 2001 From: Mateo Florido Date: Fri, 10 Jan 2025 14:50:30 -0500 Subject: [PATCH 2/5] Address docs review --- docs/src/charm/tutorial/basic-operations.md | 6 ++++-- docs/src/charm/tutorial/getting-started.md | 8 -------- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/src/charm/tutorial/basic-operations.md b/docs/src/charm/tutorial/basic-operations.md index 29dc4b54d..23d607629 100644 --- a/docs/src/charm/tutorial/basic-operations.md +++ b/docs/src/charm/tutorial/basic-operations.md @@ -19,11 +19,13 @@ To increase the control plane's capacity or ensure high availability, you can add more units to the `k8s` application: ``` -juju add-unit k8s -n 2 +juju add-unit k8s -n 1 ``` ```{tip} For high availability, we recommend deploying at least three `k8s` charm units. +Use `juju status` to view all the units in your cluster and monitor their +status. ``` Similarly, you can add more worker nodes when your workload demands increase: @@ -109,7 +111,7 @@ Alternatively, if you are a `yq` user, the same can be achieved with: juju run k8s/0 get-kubeconfig | yq '.kubeconfig' -r >> ~/.kube/config ``` -You can now confirm Kubectl can read the kubeconfig file: +You can now confirm `kubectl` can read the kubeconfig file: ``` kubectl config show diff --git a/docs/src/charm/tutorial/getting-started.md b/docs/src/charm/tutorial/getting-started.md index ee4961c74..266318eb0 100644 --- a/docs/src/charm/tutorial/getting-started.md +++ b/docs/src/charm/tutorial/getting-started.md @@ -12,14 +12,11 @@ Kubernetes and some common first steps. - How to install {{product}} - Making a cluster - Deploying extra workers -- Using `kubectl` ## What you will need - The [Juju client][] - Access to a Juju-supported cloud for creating the required instances -- [Kubectl] for interacting with the cluster (installation instructions are - included in this tutorial) ## 1. Get prepared @@ -83,10 +80,6 @@ juju status --watch 2s When the status reports that K8s is "idle/ready" you have successfully deployed a {{product}} control-plane using Juju. -```{note} -For High Availability you will need at least three units of the `k8s` charm. -``` - ## 3. Deploy a worker Before we start doing things in Kubernetes, we should consider adding a worker. @@ -131,7 +124,6 @@ charms are on the way to simplify usage and extend the base functionality of [Juju client]: https://juju.is/docs/juju/install-and-manage-the-client [Juju tutorial]: https://juju.is/docs/juju/tutorial -[Kubectl]: https://kubernetes.io/docs/reference/kubectl/ [the channel explanation page]: ../../snap/explanation/channels [releases page]: ../reference/releases [basic operations]: ./basic-operations.md From f5bfed2e94221a8e5fe5ad29e9e7274bb0cc3db0 Mon Sep 17 00:00:00 2001 From: Mateo Florido Date: Fri, 10 Jan 2025 17:24:25 -0500 Subject: [PATCH 3/5] Address code review --- docs/src/charm/tutorial/basic-operations.md | 8 +++++--- docs/src/charm/tutorial/getting-started.md | 6 ++++-- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/src/charm/tutorial/basic-operations.md b/docs/src/charm/tutorial/basic-operations.md index 23d607629..f43011c20 100644 --- a/docs/src/charm/tutorial/basic-operations.md +++ b/docs/src/charm/tutorial/basic-operations.md @@ -22,10 +22,11 @@ add more units to the `k8s` application: juju add-unit k8s -n 1 ``` -```{tip} -For high availability, we recommend deploying at least three `k8s` charm units. Use `juju status` to view all the units in your cluster and monitor their status. + +```{tip} +For high availability, we recommend deploying at least three `k8s` charm units. ``` Similarly, you can add more worker nodes when your workload demands increase: @@ -67,7 +68,8 @@ If you don't already have `kubectl`, it can be installed from a snap: sudo snap install kubectl --classic ``` -If you have just installed it, you should also create a file to contain the configuration: +If you have just installed it, you should also create a file to contain +the configuration: ``` mkdir ~/.kube diff --git a/docs/src/charm/tutorial/getting-started.md b/docs/src/charm/tutorial/getting-started.md index 266318eb0..1e3dd5eff 100644 --- a/docs/src/charm/tutorial/getting-started.md +++ b/docs/src/charm/tutorial/getting-started.md @@ -110,8 +110,10 @@ juju integrate k8s k8s-worker:containerd juju integrate k8s k8s-worker:cos-tokens ``` -After a short time, the worker node will share information with the control plane -and be joined to the cluster. +After a short time, the worker node will share information with the +control plane and be joined to the cluster. Use +`juju status --relations` to monitor the status of your units and their +established relations. ## Next steps From b8910a5af5973616698d2ac740e590e161fce06f Mon Sep 17 00:00:00 2001 From: Mateo Florido Date: Mon, 13 Jan 2025 09:20:53 -0500 Subject: [PATCH 4/5] Address docs review --- docs/src/charm/tutorial/basic-operations.md | 69 ++++++++------------- 1 file changed, 25 insertions(+), 44 deletions(-) diff --git a/docs/src/charm/tutorial/basic-operations.md b/docs/src/charm/tutorial/basic-operations.md index f43011c20..0645163d7 100644 --- a/docs/src/charm/tutorial/basic-operations.md +++ b/docs/src/charm/tutorial/basic-operations.md @@ -1,10 +1,10 @@ -# Basic operations with the charm +# Basic {{ product }} charm operations This tutorial walks you through common management tasks for your {{ product }} -cluster using the `k8s` charm. You'll learn how to scale your cluster, manage -workers, and interact with it using `kubectl`. +cluster using the `k8s` control plane charm. You will learn how to scale your +cluster, manage workers, and interact with the cluster using `kubectl`. -## What you will need +## Prerequisites - A running {{ product }} cluster deployed with the `k8s` charm - The Juju [client][Juju client] @@ -15,8 +15,8 @@ workers, and interact with it using `kubectl`. The `k8s` charm provides flexibility to scale your cluster as needed by adding or removing control plane nodes or worker nodes. -To increase the control plane's capacity or ensure high availability, you can -add more units to the `k8s` application: +To increase the control plane's capacity or ensure [high availability], you +can add more units of the `k8s` application: ``` juju add-unit k8s -n 1 @@ -25,19 +25,15 @@ juju add-unit k8s -n 1 Use `juju status` to view all the units in your cluster and monitor their status. -```{tip} -For high availability, we recommend deploying at least three `k8s` charm units. -``` - Similarly, you can add more worker nodes when your workload demands increase: ``` juju add-unit k8s-worker -n 1 ``` -This command deploys an additional instance of the `k8s-worker` charm. Juju -manages all instances within the same application, so no extra configuration -is needed. After running this command, new units will appear in your cluster, +This command deploys an additional instance of the `k8s-worker` charm. No extra +configurations is needed as Juju manages all instances within the same +application. After running this command, new units will appear in your cluster, such as `k8s-worker/0` and `k8s-worker/1`. To scale up multiple units at once, adjust the unit count: @@ -58,24 +54,23 @@ Replace the unit name with the appropriate application name (e.g., `k8s` or ## Set up `kubectl` -[kubectl][] is the standard upstream tool for interacting with a Kubernetes +[kubectl] is the standard upstream tool for interacting with a Kubernetes cluster. This is the command that can be used to inspect and manage your cluster. -If you don't already have `kubectl`, it can be installed from a snap: +If necessary `kubectl`, it can be installed from a snap: ``` sudo snap install kubectl --classic ``` -If you have just installed it, you should also create a file to contain -the configuration: +Create a directory to house the kubeconfig: ``` mkdir ~/.kube ``` -To fetch the configuration information from the cluster we can run: +Fetch the configuration information from the cluster: ``` juju run k8s/0 get-kubeconfig @@ -86,40 +81,25 @@ task. In this case it collects the cluster information - the YAML formatted details of the cluster and the keys required to connect to it. ```{warning} -If you already have `kubectl` and are using it to manage other clusters, you -should edit the relevant parts of the cluster yaml output and append them to +If you already have `kubectl` installed and are using it to manage other +clusters, edit the relevant parts of the cluster yaml output and append them to your current kubeconfig file. ``` -We can use pipe to append your cluster's kubeconfig information directly to a -config file which will just require a bit of editing: - -``` -juju run k8s/0 get-kubeconfig >> ~/.kube/config -``` - -The output includes the root of the YAML, `kubeconfig: |`, so we can just use an -editor to remove that line: +Use `yq` to append your cluster's kubeconfig information directly to the +config file: ``` -vim ~/.kube/config +juju run k8s/0 get-kubeconfig | yq '.kubeconfig' >> ~/.kube/config ``` -Please use the editor of your choice to delete the first line and save the file. - -Alternatively, if you are a `yq` user, the same can be achieved with: - -``` -juju run k8s/0 get-kubeconfig | yq '.kubeconfig' -r >> ~/.kube/config -``` - -You can now confirm `kubectl` can read the kubeconfig file: +Confirm that `kubectl` can read the kubeconfig file: ``` kubectl config show ``` -...which should output something like this: +The output will be similar to this: ``` apiVersion: v1 @@ -142,18 +122,18 @@ users: token: REDACTED ``` -You can then further confirm that it is possible to inspect the cluster by -running a simple command such as : +Run a simple command to inspect your cluster: ``` kubectl get pods -A ``` -This should return some pods, confirming the command can reach the cluster. +This command returns a list of pods, confirming that `kubectl` can reach the +cluster. ## Next steps -Now that you're familiar with basic cluster operations, you might want to: +Now that you are familiar with the basic cluster operations, learn to: - Deploy applications to your cluster - Configure storage solutions like [Ceph] @@ -166,6 +146,7 @@ documentation and release [notes][release notes]. [Ceph]: ../howto/ceph-csi [COS]: ../howto/cos-lite +[high availability]: ../../snap/explanation/high-availability [Juju client]: https://juju.is/docs/juju/install-and-manage-the-client [Kubectl]: https://kubernetes.io/docs/reference/kubectl/ [release notes]: ../reference/releases From 66b48c3851b37809d2e34fe191cf23ab8cf262d6 Mon Sep 17 00:00:00 2001 From: Mateo Florido Date: Mon, 13 Jan 2025 10:10:18 -0500 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Louise K. Schmidtgen --- docs/src/charm/tutorial/basic-operations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/charm/tutorial/basic-operations.md b/docs/src/charm/tutorial/basic-operations.md index 0645163d7..d58ea12ba 100644 --- a/docs/src/charm/tutorial/basic-operations.md +++ b/docs/src/charm/tutorial/basic-operations.md @@ -32,7 +32,7 @@ juju add-unit k8s-worker -n 1 ``` This command deploys an additional instance of the `k8s-worker` charm. No extra -configurations is needed as Juju manages all instances within the same +configuration is needed as Juju manages all instances within the same application. After running this command, new units will appear in your cluster, such as `k8s-worker/0` and `k8s-worker/1`. @@ -58,7 +58,7 @@ Replace the unit name with the appropriate application name (e.g., `k8s` or cluster. This is the command that can be used to inspect and manage your cluster. -If necessary `kubectl`, it can be installed from a snap: +If necessary, `kubectl` can be installed from a snap: ``` sudo snap install kubectl --classic