From 98f396ee3d41b7339c0790b787a578c9cae357e8 Mon Sep 17 00:00:00 2001
From: Benjamin Schimke <benjamin.schimke@canonical.com>
Date: Tue, 10 Sep 2024 13:33:26 +0200
Subject: [PATCH] Add annotations docs (#652)

---------

Co-authored-by: Nick Veitch <nick.veitch@canonical.com>
---
 docs/src/capi/reference/annotations.md | 15 +++++++++++++++
 docs/src/capi/reference/index.md       |  1 +
 docs/src/snap/reference/annotations.md | 13 +++++++++++++
 docs/src/snap/reference/index.md       |  1 +
 4 files changed, 30 insertions(+)
 create mode 100644 docs/src/capi/reference/annotations.md
 create mode 100644 docs/src/snap/reference/annotations.md

diff --git a/docs/src/capi/reference/annotations.md b/docs/src/capi/reference/annotations.md
new file mode 100644
index 000000000..8f9e87fa9
--- /dev/null
+++ 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
index 1712305ec..cd239300c 100644
--- 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
new file mode 100644
index 000000000..b5e4404d8
--- /dev/null
+++ 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
index bb2a5735a..f1720e760 100644
--- 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