Getting started

Canonical Kubernetes is a distribution of Kubernetes which includes all the necessary tools and services needed to easily deploy and manage a cluster. As the upstream Kubernetes does not come with all that is required for a fully functional cluster by default, we have bundled everything into a snap that should only take a few minutes to install. This tutorial explains how to install the snap package and some typical operations.

Prerequisites

  • System Requirements: Your machine should have at least 40G disk space and 4G of memory

  • An Ubuntu environment to run the commands (or another operating system which supports snapd - see the snapd documentation)

  • A system with no previous installations of containerd/docker as this may cause conflicts. Consider using a LXD virtual machine if you would like an isolated working environment.

Install Canonical Kubernetes

Install the Canonical Kubernetes k8s snap with:

sudo snap install k8s --classic --channel=1.33-classic/stable

This may take a few moments as the snap installs all the necessary Kubernetes components for a fully functioning cluster such as the networking, storage, etc.

Bootstrap a Kubernetes cluster

The bootstrap command initializes your cluster and configures your host system as a Kubernetes node. Bootstrapping the cluster is only done once at cluster creation.

If you would like to bootstrap a Kubernetes cluster with default configuration run:

sudo k8s bootstrap

For custom configurations, you can explore additional options using:

sudo k8s bootstrap --help

Once the bootstrap command has been successfully ran, the output should list the node address and confirm the CNI is being deployed.

Check cluster status

It may take a few minutes for the cluster to be ready. To confirm the installation was successful, use k8s status with the wait-ready flag to wait for Canonical Kubernetes to bring up the cluster:

sudo k8s status --wait-ready

Important

This command waits a few minutes before timing out. On a very slow network connection, or a system with very limited resources, this default timeout might be insufficient resulting in a “Context canceled” error. Please first ensure that your machine meets the system requirements to run a Kubernetes cluster. Then, you can either increase the timeout using the --timeout flag or re-run the command to continue waiting until the cluster is ready.

Access Kubernetes

The standard tool for deploying and managing workloads on Kubernetes is kubectl. For convenience, Canonical Kubernetes bundles a version of kubectl for you to use with no extra setup or configuration. For example, to view your node you can run the command:

sudo k8s kubectl get nodes

…or to see the running services:

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 four pods running. The status of the pods may be in ContainerCreating while they are being initialized. They should turn to Running after a few seconds.

The functions of these pods are:

  • CoreDNS (coredns): Provides DNS resolution services.

  • Network operator (cilium-operator): Manages the life-cycle of the networking solution.

  • Network agent (cilium): Facilitates network management.

  • Storage controller (ck-storage-rawfile-csi-controller): Manages the life-cycle of the local storage solution.

  • Storage agent (ck-storage-rawfile-csi-node) : Facilitates local storage management.

Deploy an app

Kubernetes is meant for deploying apps and services. You can use the kubectl command to do that as with any Kubernetes.

Let’s deploy a demo NGINX server:

sudo k8s kubectl create deployment nginx --image=nginx

This command launches a pod, the smallest deployable unit in Kubernetes, running the NGINX application within a container.

You can check the status of your pods by running:

sudo k8s kubectl get pods

This command shows all pods in the default namespace. It may take a moment for the pod to be ready and running.

Remove an app

To remove the NGINX workload, execute the following command:

sudo k8s kubectl delete deployment nginx

To verify that the pod has been removed, you can check the status of pods by running:

sudo k8s kubectl get pods

Enable local storage

In scenarios where you need to preserve application data beyond the life-cycle of the pod, Kubernetes provides persistent volumes.

With Canonical Kubernetes, you can enable local-storage to configure your storage solutions:

sudo k8s enable local-storage

To verify that the local-storage is enabled, execute:

sudo k8s status

You should see local-storage enabled in the command output.

Let’s create a PersistentVolumeClaim and use it in a Pod. For example, we can deploy the following manifest:

sudo k8s kubectl apply -f https://raw.githubusercontent.com/canonical/k8s-snap/main/docs/canonicalk8s/assets/tutorial-pod-with-pvc.yaml

This command deploys a pod based on the YAML configuration of a storage writer pod and a persistent volume claim called myclaim with a capacity of 1G.

To confirm that the persistent volume is up and running:

sudo k8s kubectl get pvc myclaim

You can inspect the storage-writer-pod with:

sudo k8s kubectl describe pod storage-writer-pod

Disable local storage

Begin by removing the pod along with the persistent volume claim:

sudo k8s kubectl delete pod storage-writer-pod
sudo k8s kubectl delete pvc myclaim

Next, disable the local storage:

sudo k8s disable local-storage

Remove Canonical Kubernetes (Optional)

If you wish to remove the snap without saving a snapshot of its data execute:

sudo snap remove k8s --purge

The --purge flag ensures complete removal of the snap and its associated data. If you would like to maintain a snapshot of the k8s snap for future restoration, simply run :

sudo snap remove k8s

The snapshot is a copy of the user, system and configuration data stored by snapd for the k8s snap. This data can be found in /var/snap/k8s.

Next steps