Add annotations docs (#652)

---------

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

docs/src/capi/reference/annotations.md

@@ -0,0 +1,15 @@
+# Annotations
+
+Like annotations for other Kubernetes objects, CAPI annotations are key-value
+pairs that can be used to reflect additional metadata for CAPI resources.
+
+## Machine
+
+The following annotations can be set on CAPI `Machine` resources.
+
+| Name                                          | Description                                          | Values                       | Set by user |
+|-----------------------------------------------|------------------------------------------------------|------------------------------|-------------|
+| `v1beta2.k8sd.io/in-place-upgrade-to`         | Trigger a Kubernetes version upgrade on that machine | snap version e.g.:<br>- `localPath=/full/path/to/k8s.snap`<br>- `revision=123`<br>- `channel=latest/edge` | yes |
+| `v1beta2.k8sd.io/in-place-upgrade-status`     | The status of the version upgrade                    | in-progress\|done\|failed    | no          |
+| `v1beta2.k8sd.io/in-place-upgrade-release`    | The current version on the machine                   | snap version e.g.:<br>- `localPath=/full/path/to/k8s.snap`<br>- `revision=123`<br>- `channel=latest/edge` | no |
+| `v1beta2.k8sd.io/in-place-upgrade-change-id`  | The ID of the currently running upgrade              | ID string                    | no          |

docs/src/capi/reference/index.md

@@ -11,6 +11,7 @@ Overview <self>
 ```{toctree}
 :titlesonly:
 releases
+annotations
 community
 configs
 

docs/src/snap/reference/annotations.md

@@ -0,0 +1,13 @@
+# Annotations
+
+This page outlines the annotations that can be configured during cluster
+[bootstrap]. To do this, set the cluster-config/annotations parameter in
+the bootstrap configuration.
+
+| Name                                                          | Description                                                                                                                                                                                                                                       | Values          |
+|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
+| `k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove` | If set, only microcluster and file cleanup are performed.  This is helpful when an external controller (e.g., CAPI) manages the Kubernetes node lifecycle. By default,  k8sd will remove the Kubernetes node when it is removed from the cluster. | "true"\|"false" |
+
+<!-- Links -->
+
+[bootstrap]: /snap/reference/bootstrap-config-reference

docs/src/snap/reference/index.md

@@ -13,6 +13,7 @@ Overview <self>
 
 releases
 commands
+annotations
 certificates
 bootstrap-config-reference
 proxy