Last modified September 6, 2023
Labelling workload clusters
AWS |
|
---|---|
Azure |
|
Introduction
Workload clusters, like any other Kubernetes resource, can be enriched with labels. Labels are key-value-pairs, where each key can be used only once per object (here: per workload cluster).
Workload clusters are defined by a main Cluster resource (clusters.cluster.x-k8s.io
). Accordingly, the labels we refer to in this article are those on that resource type only.
Special purpose labels
Some of the controllers we use to manage clusters rely on the presence of certain labels. Hence we restrict the creation, modification, or deletion of certain labels you find on the cluster resources.
As a rule of thumb, labels containing the following patterns in their key are restricted:
giantswarm.io
x-k8s.io
The complete ruleset is implemented in our provider specific admission controllers (AWS, Azure).
For your own labelling purposes, we strongly recommend to introduce a unique key prefix, ideally based on a domain name. Example:
example.tld/my-label: my-value
Service priority
Giant Swarm recommends to assign a service priority to a cluster, using the following label:
giantswarm.io/service-priority
Service priority is a relative ranking of the importance of clusters. It helps Giant Swarm staff and potentially, if your organization decides so, also your stakeholders to vet the priority of clusters in case of problems in several clusters. The possible label values are:
highest
: Clusters with this label value are considered the most important ones. We expect customers to use this class for clusters serving user-facing applications, production traffic, etc.lowest
: The lowest priority class. We recommend this value for clusters that are not relied on, or which can be replaced easily and quickly. A typical case would be a cluster created for temporary testing purposes.medium
: Clusters carrying this label value are considered less important than those withhighest
, but more important than clusters classified aslowest
. Typical use cases would be staging clusters, clusters handling batch workloads, or development clusters that cannot be replaced easily by creating a new cluster.
If a cluster resource does not carry the giantswarm.io/service-priority
label, we consider its service priority to be highest
.
Other values than the three mentioned above are not permitted and will be rejected by the Management API’s admission controller. Also note that the label is only meant to be used on the main cluster resource. It will be ignored on other resource types, and we may also prevent setting it on other resource types in the future.
Monitoring
By default each cluster is being monitored by Giant Swarm to ensure 24/7 support.
This can be disabled using the following label:
giantswarm.io/monitoring: "false"
You can find more details about this in the Disable Monitoring article.
Deletion Prevention
To protect clusters from accidental deletion you can use the following label:
giantswarm.io/prevent-deletion: ""
For more information, please read the Deletion Prevention article.
Setting labels when creating a cluster
Depending on the method you use to create a cluster, you can specify labels when creating your cluster.
If you use kubectl gs template cluster
to create a cluster manifest, you can apply the --label
flag with your initial command, as often as required. You are also free to modify the created manifest before applying it. Example:
kubectl gs template cluster \
--label giantswarm.io/service-priority lowest \
--label example.tld/environment testing \
...
Modifying cluster labels
To modify labels on a cluster, several methods are supported:
- Our web UI allows adding, modifying, and deleting labels interactively.
- The
kubectl label
command can be used with the cluster resource. See below for details.
Modify cluster labels using kubectl
With access to the management cluster, you are able to use kubectl
to manage workload cluster labels.
The underlying resource to operate on is clusters.cluster.x-k8s.io
from the upstream cluster-api project.
The kubectl label
command is the most convenient way to set, modify, and delete labels of a cluster resource.
The following example shows how to set a label my-org/team
with value upstate
on a cluster named 7g4di
:
kubectl label clusters.cluster.x-k8s.io/7g4di my-org/team=upstate
Note that if the label already exists on the cluster, the --overwrite
flag must be set. Otherwise the attempt to overwrite a label will result in an error.
Need help, got feedback?
We listen to your Slack support channel. You can also reach us at support@giantswarm.io. And of course, we welcome your pull requests!