Upgrading MicroK8s

As detailed in the documentation for selecting a channel, patch release updates (e.g 1.20.x to 1.20.x+1) happen automatically for the installed version of MicroK8s. This page covers intentionally upgrading to a new minor version (e.g. 1.20 to 1.21).

MicroK8s makes use of snap channels. This restricts automatic updates to new versions published in that channel, providing users with a way of making sure version upgrades only occur when the user asks for them.

MicroK8s channels follow the upstream release versions of Kubernetes. This makes it easy to specify a version of Kubernetes to use when installing MicroK8s, and to restrict updates to non-breaking changes within the same minor version. To upgrade to a new version, it is necessary to refresh the snap to point to a different channel, but some additional steps may be required on a running cluster to minimise disruption (as detailed below).

IMPORTANT NOTE: Add-ons, unless specified otherwise in the documentation, will NOT be upgraded as part of a MicroK8s upgrade. Currently, the most effective way to upgrade these add-ons is to use microk8s disable <add-on> and then re-enable them. Please make sure to read the release notes for specific details referring to add-ons before upgrading.

Cluster upgrades

The Kubenetes project releases strive to be API backwards compatible, so upgrading a cluster should be possible. However, as a cluster administrator you should be aware of changes introduced on every release before attempting one. There are often important changes that affect the behavior of the cluster and the workloads it can serve. Please, consult the upstream release notes of the release you are targeting. Pay particular attention to the deprecation notices for a release you intend to upgrade to

Be also aware of the following constraints set by MicroK8s during an upgrade:

  • “skip-level” updates are NOT tested. Only upgrade through one minor release (e.g. 1.19 to 1.20) at a time.

  • Downgrading (e.g. 1.20 to 1.19) is not tested or supported.

  • Any configuration changes must be migrated incrementally across multiple versons to ensure the configuration is retained.

  • Customisation (e.g. changes to the arguments for kubernetes services) WILL be carried over to upgraded version, but please be aware that version changes may make these customisations incompatible with the updated cluster.

If an upgrade is not possible it is possible to re-install MicroK8s targetting the desired version.

Upgrade a single node cluster

Refreshing the MicroK8s snap to the desired channel effectively upgrades the cluster. For instance, to upgrade a v1.20 cluster to v1.21 simply run snap refresh with the new channel name:

sudo snap refresh microk8s --channel=1.21/stable

Upgrade a multi-node cluster

Kubernetes allows for some degree of service skew. This allows a multi-node cluster to be upgraded one at a time.

For instance, if you have an existing cluster on v1.19 and you want to upgrade to v1.20, you should perform the following on each node:

microk8s kubectl drain <node> --ignore-daemonsets

At this point the node you drained should have no workload pods. Running the command:

microk8s kubectl get po -A -o wide

…should only show daemon set pods.

To upgrade the node, run:

sudo snap refresh microk8s --channel=1.21/stable

After the new version has been fetched and the snap is updated, the node should register with the new version:

microk8s.kubectl get no

The last step is to resume pod scheduling on the upgraded node with:

microk8s kubectl uncordon <node>

These steps should be repeated on all the nodes in the cluster.

Revert a failed upgrade attempt

If for any reason an upgrade does not result in a working cluster, you can revert the node to its state before the latest refresh with:

sudo snap revert microk8s

For diagnostic purposes, you may wish to run:

microk8s inspect

…before reverting the upgrade. This collects a tarball of information about the running cluster/node.

Last updated a month ago. Help improve this document in the forum.