Add how-to for capi in place upgrades (#671)

* Add how-to for capi in place upgrades

* Addressing comments

* Linting fixes

* Update docs/src/capi/howto/in-place-upgrades.md

---------

Co-authored-by: Nick Veitch <nick.veitch@canonical.com>

docs/src/capi/howto/in-place-upgrades.md

@@ -0,0 +1,98 @@
+# Perform an in-place upgrade for a machine
+
+This guide walks you through the steps to perform an in-place upgrade for a
+Cluster API managed machine.
+
+## Prerequisites
+
+To follow this guide, you will need:
+
+- A Kubernetes management cluster with Cluster API and providers installed
+  and configured.
+- A target workload cluster managed by CAPI.
+- `kubectl` installed and configured to access your management cluster.
+- The workload cluster kubeconfig.
+
+Please refer to the [getting-started guide][getting-started] for further
+details on the required setup.
+This guide refers to the workload cluster as `c1` and its
+kubeconfig as `c1-kubeconfig.yaml`.
+
+## Check the current cluster status
+
+Prior to the upgrade, ensure that the management cluster is in a healthy
+state.
+
+```
+kubectl get nodes -o wide
+```
+
+Confirm the Kubernetes version of the workload cluster:
+
+```
+kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide
+```
+
+## Annotate the machine
+
+In this first step, annotate the Machine resource with 
+the in-place upgrade annotation. In this example, the machine
+is called `c1-control-plane-xyzbw`.
+
+```
+kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-to=<upgrade-option>"
+```
+
+`<upgrade-option>` can be one of:
+
+* `channel=<snap-channel>` which refreshes k8s to the given snap channel.
+  e.g. `channel=1.30-classic/stable`
+* `revision=<revision>` which refreshes k8s to the given revision.
+  e.g. `revision=123`
+* `localPath=<path>` which refreshes k8s with the snap file from 
+  the given absolute path. e.g. `localPath=full/path/to/k8s.snap`
+
+Please refer to the [ClusterAPI Annotations Reference][annotations-reference]
+for further details on these options.
+
+## Monitor the in-place upgrade
+
+Watch the status of the in-place upgrade for the machine,
+by running the following command and checking the
+`v1beta2.k8sd.io/in-place-upgrade-status` annotation:
+
+```
+kubectl get machine c1-control-plane-xyzbw -o yaml
+```
+
+On a successful upgrade:
+
+* Value of the `v1beta2.k8sd.io/in-place-upgrade-status` annotation
+  will be changed to `done`
+* Value of the `v1beta2.k8sd.io/in-place-upgrade-release` annotation
+  will be changed to the `<upgrade-option>` used to perform the upgrade.
+
+## Cancelling a failing upgrade
+
+The upgrade is retried periodically if the operation was unsuccessful.
+
+The upgrade can be cancelled by running the following commands
+that remove the annotations:
+
+```
+kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-to-"
+kubectl annotate machine c1-control-plane-xyzbw "v1beta2.k8sd.io/in-place-upgrade-change-id-"
+```
+
+## Verify the Kubernetes upgrade
+
+Confirm that the node is healthy and runs on the new Kubernetes version:
+
+```
+kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide
+```
+
+
+<!-- LINKS -->
+[getting-started]: ../tutorial/getting-started.md
+[annotations-reference]: ../reference/annotations.md

docs/src/capi/howto/index.md

@@ -16,6 +16,7 @@ Overview <self>
 
 external-etcd
 rollout-upgrades
+in-place-upgrades
 upgrade-providers
 migrate-management
 custom-ck8s