Labelling workload clusters
Guide on using labels with workload clusters for the purpose of grouping, categorization and selection.
The workload clusters, like any other Kubernetes custom 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 referred to in this article are those on that resource type only.
Special purpose labels
Some of the controllers the platform uses to manage clusters rely on the presence of certain labels. Hence the creation, modification, or deletion are restricted 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.iox-k8s.io
For your own labelling purposes, our recommendation is 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, 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. You can use this class for clusters serving user-facing applications, production traffic, etc.lowest: The lowest priority class. Use 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, the default is service priority highest.
Other values than the three mentioned above are not permitted and will be rejected by the platform 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 you may also prevent setting it on other resource types in the future.
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, use kubectl label command towards the cluster resource. See below for details.
Modify cluster labels using kubectl
With access to the platform API, 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.
