docs: Add snap upgrades how-to

docs/src/snap/howto/index.md

@@ -26,6 +26,7 @@ two-node-ha
 Set up Enhanced Platform Awareness <epa>
 contribute
 Get support <support>
+Managing Upgrades <upgrades>
 ```
 
 ---

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[=<duration>]` holds refreshes for a specified duration (or forever, if no value is specified).
+```
+snap refresh k8s --hold
+```
+Or
+```
+snap refresh k8s --hold=24h
+```
+
+<!-- LINKS -->
+[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