Skip to content

Commit

Permalink
[Docs] Clarify node-labels are additive or destructive (#949)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
addyess authored Jan 14, 2025
1 parent 108cbf2 commit 87aab71
Show file tree
Hide file tree
Showing 3 changed files with 95 additions and 2 deletions.
14 changes: 12 additions & 2 deletions docs/src/charm/howto/install-custom.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions docs/src/charm/reference/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ proxy
architecture
Ports and Services <ports-and-services>
charm-configurations
troubleshooting
Community <community>
```
Expand Down
82 changes: 82 additions & 0 deletions docs/src/charm/reference/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -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=-"
```

0 comments on commit 87aab71

Please sign in to comment.