Last modified September 6, 2023
Labelling workload clusters
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:
For your own labelling purposes, we strongly recommend to introduce a unique key prefix, ideally based on a domain name. Example:
Giant Swarm recommends to assign a service priority to a cluster, using the following label:
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 with
highest, but more important than clusters classified as
lowest. 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
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.
By default each cluster is being monitored by Giant Swarm to ensure 24/7 support.
This can be disabled using the following label:
You can find more details about this in the Disable Monitoring article.
To protect clusters from accidental deletion you can use the following label:
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.
kubectl labelcommand can be used with the cluster resource. See below for details.
Modify cluster labels using
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.
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
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.