diff --git a/docs/src/snap/howto/index.md b/docs/src/snap/howto/index.md index 92265bd5e..720cf3218 100644 --- a/docs/src/snap/howto/index.md +++ b/docs/src/snap/howto/index.md @@ -26,6 +26,7 @@ two-node-ha Set up Enhanced Platform Awareness contribute Get support +Managing Upgrades ``` --- diff --git a/docs/src/snap/howto/upgrades.md b/docs/src/snap/howto/upgrades.md new file mode 100644 index 000000000..b70d23afe --- /dev/null +++ b/docs/src/snap/howto/upgrades.md @@ -0,0 +1,98 @@ +# Upgrading the snap + +Upgrading the Kubernetes version of a node is a critical operation that +requires careful planning and execution. {{product}} is shipped as a snap, +which simplifies the upgrade process. +This how-to guide will cover the steps to upgrade the {{product}} snap to a +new version as well as how to freeze upgrades. + +## Important Considerations Before Upgrading + +- According to the [upstream Kubernetes][1], skipping **minor** versions while +upgrading is not supported. For more details, please visit [Version Skew Policy][2]. +- Before performing an upgrade, it's important to back up the cluster data. +This can be done by following the steps outlined in the [backup guide][3]. +- For more info about managing snap updates, please refer to the [snap documentation][4]. +- Managing upgrades in a multi node cluster is a complex operation, and it's +recommended to use lifecycle management tools like [Juju][5] or [Cluster API][6]. + +## What you will need + +- A running {{product}} cluster. + +## Patch Upgrade + +Patch upgrades apply bug fixes and are generally safe without API changes. +Snaps update automatically, and by default, the snapd daemon checks for updates 4 times a day. +{{product}} is installed using a specific track, which consists of a major and minor version. +As an example, if {{product}} is installed using the `1.32` track, +the snap updates automatically to the latest revision of `1.32` during daily checks. +Patch upgrades can also be triggered manually by following the steps below. + +1. **List available revisions:** +``` +snap info k8s +``` + +2. **Refresh the snap:** +``` +snap refresh k8s +``` + +3. **Verify the upgrade:** +Ensure that the upgrade was successful by checking the version of the snap and +confirming that the cluster is ready: +``` +snap info k8s +k8s status --wait-ready +``` + +## Minor Version Upgrade + +Minor versions add new features or deprecate existing features without breaking changes. +To upgrade to a new minor version, the snap channel needs to be changed. + + +1. **List available channels:** +``` +snap info k8s +``` + +2. **Change the snap channel:** +The {{product}} snap channel can be changed either by using the `snap refresh` command or by using the `snap switch` command. +The main difference between these two methods is that `snap refresh` will update the snap to the latest revision in the new channel, while `snap switch` switches to the new channel without doing a refresh. +``` +snap refresh --channel=1.33/stable k8s +``` +Or +``` +snap switch --channel=1.33/stable k8s +``` + +3. **Verify the upgrade:** +Ensure that the upgrade was successful by checking the version of the snap and +confirming that the cluster is ready: +``` +snap info k8s +k8s status --wait-ready +``` + +## Freezing Upgrades + +To prevent automatic updates, the snap can be frozen to a specific revision. +`snap refresh --hold[=]` holds refreshes for a specified duration (or forever, if no value is specified). +``` +snap refresh k8s --hold +``` +Or +``` +snap refresh k8s --hold=24h +``` + + +[1]: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/ +[2]: https://kubernetes.io/docs/setup/release/version-skew-policy/ +[3]: ./backup-restore.md +[4]: https://snapcraft.io/docs/managing-updates +[5]: ../../charm/index.md +[6]: ../../capi/index.md