From 87aab71a0abb8c2323615e3a7e2108eb108ce28e Mon Sep 17 00:00:00 2001
From: Adam Dyess <adam.dyess@canonical.com>
Date: Tue, 14 Jan 2025 11:03:31 -0600
Subject: [PATCH] [Docs] Clarify node-labels are additive or destructive (#949)

* Clarify node-labels are additive or destructive
* Create a troubleshooting page with an example of how to adjust node-labels
* Update install-custom to clarify default-labels are maintained
---
 docs/src/charm/howto/install-custom.md      | 14 +++-
 docs/src/charm/reference/index.md           |  1 +
 docs/src/charm/reference/troubleshooting.md | 82 +++++++++++++++++++++
 3 files changed, 95 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/charm/reference/troubleshooting.md

diff --git a/docs/src/charm/howto/install-custom.md b/docs/src/charm/howto/install-custom.md
index dbb4a74a5..7d0109a20 100644
--- a/docs/src/charm/howto/install-custom.md
+++ b/docs/src/charm/howto/install-custom.md
@@ -6,6 +6,7 @@ configuration options.
 ## What you'll need
 
 This guide assumes the following:
+
 -  You have Juju installed on your system with your cloud credentials
 configured and a controller bootstrapped
 - A Juju model is created and selected
@@ -35,13 +36,22 @@ k8s:
   dns-cluster-domain: "cluster.local"
   dns-upstream-nameservers: "8.8.8.8 8.8.4.4"
 
-  # Add custom node labels
-  node-labels: "environment=production zone=us-east-1"
+  # Add & Remove node-labels from the snap's default labels
+  #   The k8s snap applies its default labels, these labels define what
+  #   are added or removed from those defaults
+  # <key>=<value> ensures the label is added to all the nodes of this application
+  # <key>=-       ensures the label is removed from all the nodes of this application
+  # See charm-configuration notes for more information regarding node labelling
+  node-labels: >-
+    environment=production
+    node-role.kubernetes.io/worker=-
+    zone=us-east-1
 
   # Configure local storage
   local-storage-enabled: true
   local-storage-reclaim-policy: "Retain"
 ```
+
 You can find a full list of configuration options in the
 [charm configurations] page.
 
diff --git a/docs/src/charm/reference/index.md b/docs/src/charm/reference/index.md
index 5299d21ac..63c4e79bb 100644
--- a/docs/src/charm/reference/index.md
+++ b/docs/src/charm/reference/index.md
@@ -17,6 +17,7 @@ proxy
 architecture
 Ports and Services <ports-and-services>
 charm-configurations
+troubleshooting
 Community <community>
 
 ```
diff --git a/docs/src/charm/reference/troubleshooting.md b/docs/src/charm/reference/troubleshooting.md
new file mode 100644
index 000000000..574d2a4d7
--- /dev/null
+++ b/docs/src/charm/reference/troubleshooting.md
@@ -0,0 +1,82 @@
+# Troubleshooting
+
+This page provides techniques for troubleshooting common {{product}}
+issues dealing specifically with the charm.
+
+
+## Adjusting Kubernetes node labels
+
+### Problem
+
+Control-Plane or Worker nodes are automatically marked with a label that is
+unwanted.
+
+For example, the control-plane node may be marked with both control-plane and
+worker roles
+
+```
+node-role.kubernetes.io/control-plane=
+node-role.kubernetes.io/worker=
+```
+
+### Explanation
+
+Each kubernetes node comes with a set of node labels enabled by default. The k8s
+snap defaults with both control-plane and worker role labels, while the worker
+node only has a role label.
+
+For example, consider the following simple deployment with a worker and a
+control-plane.
+
+```sh
+sudo k8s kubectl get nodes
+```
+
+Outputs
+
+```
+NAME            STATUS   ROLES                  AGE     VERSION
+juju-c212aa-1   Ready    worker                 3h37m   v1.32.0
+juju-c212aa-2   Ready    control-plane,worker   3h44m   v1.32.0
+```
+
+### Solution
+
+Adjusting the roles (or any label) be executed by adjusting the application's
+configuration of `node-labels`.
+
+To add another node label:
+
+```sh
+current=$(juju config k8s node-labels)
+if [[ $current == *" label-to-add="* ]]; then
+   # replace an existing configured label
+   updated=${current//label-to-add=*/}
+   juju config k8s node-labels="${updated} label-to-add=and-its-value"
+else
+   # specifically configure a new label
+   juju config k8s node-labels="${current} label-to-add=and-its-value"
+fi
+```
+
+To remove a node label which was added by default
+
+```sh
+current=$(juju config k8s node-labels)
+if [[ $current == *" label-to-remove="* ]]; then
+   # remove an existing configured label
+   updated=${current//label-to-remove=*/}
+   juju config k8s node-labels="${updated}"
+else
+   # remove an automatically applied label
+   juju config k8s node-labels="${current} label-to-remove=-"
+fi
+```
+
+#### Node Role example
+
+To remove the worker node-rule on a control-plane:
+
+```sh
+juju config k8s node-labels="node-role.kubernetes.io/worker=-"
+```