Getting started

Installing Canonical Kubernetes should only take a few minutes. This tutorial explains how to install the snap package and some typical operations.

Prerequisites

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

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

  • A system without any previous installations of containerd/docker. Installing either with Canonical Kubernetes will cause conflicts. If a containerization solution is required on your system, consider using LXD to isolate your installation.

1. Install Canonical Kubernetes

Install the Canonical Kubernetes snap with:

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

2. Bootstrap a Kubernetes cluster

The bootstrap command initialises your cluster and configures your host system as a Kubernetes node. 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

Bootstrapping the cluster can only be done once.

3. Check cluster status

To confirm the installation was successful and your node is ready you should run:

sudo k8s status

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 continue waiting until the cluster is ready.

It may take a few moments for the cluster to be ready. Use k8s status to wait for Canonical Kubernetes to get to a cluster status ready state by running:

sudo k8s status --wait-ready

5. 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 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. 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.

7. 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

8. 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 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

9. Disable local storage

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

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

Next, disable the local storage:

sudo k8s disable local-storage

10. Remove Canonical Kubernetes (Optional)

To uninstall the Canonical Kubernetes snap, execute:

sudo snap remove k8s

This command removes the k8s snap and automatically creates a snapshot of all data for future restoration.

If you wish to remove the snap without saving a snapshot of its data, add --purge to the command:

sudo snap remove k8s --purge

This option ensures complete removal of the snap and its associated data.

Next steps