Last modified September 6, 2023

Labelling workload clusters

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 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 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.