Add annotations docs (#652)

--------- Co-authored-by: Nick Veitch <nick.veitch@canonical.com>
canonical · Sep 10, 2024 · 98f396e · 98f396e
1 parent c2f6925
commit 98f396e
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 0 deletions.
diff --git a/docs/src/capi/reference/annotations.md b/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          |
diff --git a/docs/src/capi/reference/index.md b/docs/src/capi/reference/index.md
@@ -11,6 +11,7 @@ Overview <self>
 ```{toctree}
 :titlesonly:
 releases
+annotations
 community
 configs
 

diff --git a/docs/src/snap/reference/annotations.md b/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
diff --git a/docs/src/snap/reference/index.md b/docs/src/snap/reference/index.md
@@ -13,6 +13,7 @@ Overview <self>
 
 releases
 commands
+annotations
 certificates
 bootstrap-config-reference
 proxy