diff --git a/docs/canonicalk8s/index.md b/docs/canonicalk8s/index.md index e62526846..6b9ba94b1 100644 --- a/docs/canonicalk8s/index.md +++ b/docs/canonicalk8s/index.md @@ -16,7 +16,7 @@ development and innovation without having to worry about the infrastructure. Whether you are deploying a small cluster to get accustomed to Kubernetes or a huge enterprise level deployment across the globe, {{product}} can cater to -your needs. If would like to jump straight in, head to the +your needs. If you would like to jump straight in, head to the [snap getting started tutorial!](src/snap/tutorial/getting-started.md) ![Illustration depicting working on components and clouds][logo] diff --git a/docs/src/snap/explanation/about.md b/docs/src/snap/explanation/about.md index 3a07a2851..b32d051c9 100644 --- a/docs/src/snap/explanation/about.md +++ b/docs/src/snap/explanation/about.md @@ -3,16 +3,15 @@ At its core, {{product}} is a full implementation of upstream [Kubernetes] delivered in a compact, secure, reliable [snap] package. As the upstream Kubernetes services are not all that is required for a fully -functional cluster, additional services and features are built in. You can -deploy the snap and have a single-node cluster up and running in minutes. +functional cluster, additional services and features are built in. ## Why a snap? Snaps are self-contained, simple to install, secure, cross-platform, and dependency-free. They can be installed on any Linux system which supports the `snapd` service (see the [snapd documentation] for more information). Security -and robustness are their key features, alongside being easy to install, easy to -maintain and easy to upgrade. +and robustness are their key features, alongside being easy to install, +maintain and upgrade. ## What else comes with it? @@ -41,8 +40,8 @@ method] page to see which method best suits your project's needs. Yes. {{product}} is designed to be eminently scalable. You can start with a single node and add more as and when the need arises. Scale up or down -at any time. Systems with more than three nodes will automatically become -Highly Available. +at any time. Systems with more than three control plane nodes will automatically +become Highly Available. ## Does it come with support? diff --git a/docs/src/snap/howto/install/lxd.md b/docs/src/snap/howto/install/lxd.md index 6833ad5a7..1aa9a49f3 100644 --- a/docs/src/snap/howto/install/lxd.md +++ b/docs/src/snap/howto/install/lxd.md @@ -32,8 +32,8 @@ wget https://raw.githubusercontent.com/canonical/k8s-snap/main/tests/integration ``` -```{note} For an explanation of the settings in this file, [see below] -(explain-rules) +```{note} For an explanation of the settings in this file, +[see below](explain-rules) ``` To pipe the content of the file into the k8s LXD profile, run: @@ -107,7 +107,7 @@ you can access it via the LXD container’s IP address. This can be done using `k8s kubectl expose`. This example will expose the deployment’s port 80 to a port assigned by Kubernetes. -In this example, we will use [Microbot] as it provides a simple HTTP endpoint +We will use [Microbot] as it provides a simple HTTP endpoint to expose. These steps can be applied to any other deployment. First, initialise the k8s cluster with @@ -129,7 +129,7 @@ Then check that the deployment has come up. lxc exec k8s -- sudo k8s kubectl get all ``` -...should return output similar to: +...should return an output similar to: ``` @@ -194,10 +194,14 @@ And it can be permanently removed with: lxc delete k8s ``` + + (explain-rules)= - ## Explanation of custom LXD rules + + + **linux.kernel_modules**: Comma separated list of kernel modules to load before starting the container diff --git a/docs/src/snap/howto/install/offline.md b/docs/src/snap/howto/install/offline.md index 8ef698df4..ee9a45478 100644 --- a/docs/src/snap/howto/install/offline.md +++ b/docs/src/snap/howto/install/offline.md @@ -302,8 +302,8 @@ by running the command: sudo k8s bootstrap --address MY-NODE-IP ``` -Add and remove nodes as described in the -[add-and-remove-nodes tutorial][nodes]. +Adding nodes requires the same steps to be repeated but instead of +bootstrapping you would need to join the node to the cluster. After a while, confirm that all the cluster nodes show up in the output of the `sudo k8s kubectl get node` command. diff --git a/docs/src/snap/reference/community.md b/docs/src/snap/reference/community.md index 4b0f3de93..53474fb0a 100644 --- a/docs/src/snap/reference/community.md +++ b/docs/src/snap/reference/community.md @@ -3,12 +3,12 @@ This rapidly growing community is a diverse bunch of people - developers, Kubernetes admins, inventors, researchers, students… and we all share the joy of a reliable, flexible, secure, timely version of upstream Kubernetes. The -team recognise the important role each and every user plays in the success of +team recognizes the important role each and every user plays in the success of the project as a whole and how valuable your contributions are. ## Do you have questions? -Do you have questions about {{product}}? Perhaps you want some ideas +Do you have questions about {{product}}? Perhaps you want to share some ideas on how to best achieve a certain goal or maybe some aspect of your Kubernetes doesn't behave the way you expect. Perhaps you'd just like some advice from more experienced users. There are a number of ways to get in touch: diff --git a/docs/src/snap/tutorial/add-remove-nodes.md b/docs/src/snap/tutorial/add-remove-nodes.md index e9442c46c..52d71b94f 100644 --- a/docs/src/snap/tutorial/add-remove-nodes.md +++ b/docs/src/snap/tutorial/add-remove-nodes.md @@ -10,13 +10,13 @@ the foundational aspects of clustering using {{product}} without the complexities of a full-scale, production setup. If your nodes are already installed, you can skip the Multipass setup and go to [step 2](step2). -## Before starting +## Before we begin In this tutorial, "**control plane**" refers to the Multipass VM that operates the control plane, while "**worker**" denotes the Multipass VM running the worker node. -## What you will need +## Prerequisites - Multipass (See [Multipass Installation][Multipass Installation]) @@ -33,7 +33,6 @@ multipass launch 22.04 --name worker -m 4G -c 4 -d 8G ``` This step can take a few minutes as Multipass creates the new virtual machines. -It's normal and expected. Once the virtual machine has been created, you can run commands on it by opening a shell. For example: @@ -58,16 +57,16 @@ Install {{product}} on both VMs with the following command: ### 2. Bootstrap your control plane node + +{{product}} allows you to create two types of nodes: control plane and +worker nodes. In this example, we just initialise a control plane node. + Bootstrap the control plane node with default configuration: ``` sudo k8s bootstrap ``` -{{product}} allows you to create two types of nodes: control plane and -worker nodes. In this example, we just initialised a control plane node, now -let's create a worker node. - Generate the token required for the worker node to join the cluster by executing the following command on the control-plane node: @@ -125,9 +124,10 @@ It is important to clean-up your nodes before tearing down the VMs. Keep in mind the consequences of removing nodes: -```{warning} Do not remove the leader node. -If you have less than 3 nodes and you remove any node you will lose availability - of your cluster. +```{warning} If you have less than 3 control plane nodes the cluster +is not in high availability mode. In such a setup the first node, ie the node you called +`k8s bootstrap` on, plays the role of the leader. If you remove the leader +you will lose availability of your cluster. ``` To tear down the entire cluster, execute: diff --git a/docs/src/snap/tutorial/getting-started.md b/docs/src/snap/tutorial/getting-started.md index 2567537e1..91a56f41c 100644 --- a/docs/src/snap/tutorial/getting-started.md +++ b/docs/src/snap/tutorial/getting-started.md @@ -51,34 +51,22 @@ should run: sudo k8s status ``` -It may take a few moments for the cluster to be ready. Confirm that {{product}} -has transitioned to the `cluster status ready` state by running: - ```{important} By default, the command waits a few minutes before timing out. -On a very slow network connection, this default timeout might be insufficient, resulting in a "Context cancelled" error. -In that case, you can either increase the timeout using the `--timeout` flag or re-run the command to +On a very slow network connection, this default timeout might be insufficient, +resulting in a "Context cancelled" error. In that case, you can either increase +the timeout using the `--timeout` flag or re-run the command to continue waiting until the cluster is ready. ``` -``` -sudo k8s status --wait-ready -``` +It may take a few moments for the cluster to be ready. Use `k8s status` to wait +for {{product}} to get to a `cluster status ready` state by running: -Run the following command to list all the pods in the `kube-system` -namespace: ``` -sudo k8s kubectl get pods -n kube-system +sudo k8s status --wait-ready ``` -You will observe at least three pods running. The functions of these three pods -are: - -- **CoreDNS**: Provides DNS resolution services. -- **Network operator**: Manages the life-cycle of the networking solution. -- **Network agent**: Facilitates network management. - ### 5. Access Kubernetes The standard tool for deploying and managing workloads on Kubernetes @@ -97,6 +85,21 @@ sudo k8s kubectl get nodes sudo k8s kubectl get services ``` +Run the following command to list all the pods in the `kube-system` +namespace: + +``` +sudo k8s kubectl get pods -n kube-system +``` + +You will observe at least three pods running. The functions of these three pods +are: + +- **CoreDNS**: Provides DNS resolution services. +- **Network operator**: Manages the life-cycle of the networking solution. +- **Network agent**: Facilitates network management. + + ### 6. Deploy an app Kubernetes is meant for deploying apps and services. diff --git a/docs/src/snap/tutorial/kubectl.md b/docs/src/snap/tutorial/kubectl.md index 4dda79425..fd31411f1 100644 --- a/docs/src/snap/tutorial/kubectl.md +++ b/docs/src/snap/tutorial/kubectl.md @@ -17,7 +17,7 @@ Before you begin, make sure you have the following: The `kubectl` command communicates with the [Kubernetes API server][kubernetes-api-server]. -{{product}} includes a `kubectl` which is built from the +{{product}} includes `kubectl`, built from the original upstream source into the `k8s` snap you have installed and is configured to work with the cluster out of the box.