Last modified March 6, 2022
Labelling workload clusters
AWS |
|
---|---|
Azure |
|
Introduction
It is possible to assign key value labels to Giant Swarm workload clusters with workload cluster release v10.0.0 and above on AWS.
Labels are a mechanism to assign short pieces of additional information to your Giant Swarm workload clusters.
Under the hood, workload cluster labels are Kubernetes labels attached to Cluster
(clusters.cluster.x-k8s.io
) resources.
Therefore, all means of listing workload cluster labels will return all Kubernetes labels attached to Cluster
resources requested.
Label keys and values are freely modifiable except labels with keys containing giantswarm.io
.
Working with workload cluster labels works likewise as working with Kubernetes labels. More information about Kubernetes Labels can be found in the Kubernetes Labels and Selectors and our cluster labels API documentation.
Note: You can also manage cluster labels directly through happa
, our web user interface.
Working with workload cluster labels using gsctl
With gsctl
, our CLI, cluster labels can be modified by executing gsctl update cluster
by setting label changes using one or multiple --label
flag.
Deleting a label can be accomplished by setting its value to an empty string. --label labeltodelete=
.
$ gsctl update cluster 7g4di --label my-org/team=upstate --label my-org/environment=testing
Cluster '7g4di' has been modified.
New cluster labels:
my-org/environment=testing
my-org/team=upstate
Once clusters are labelled, the output of gsctl list clusters
can be augmented by setting flag --selector
(or -l
)
It takes a Kubernetes Label selector to specify requirements on cluster labels to select.
The output of gsctl show cluster
will contain all labels currently attached to the selected cluster.
Working with workload cluster labels using the Giant Swarm REST API
Workload cluster labels of clusters with workload cluster release v10.0.0
and above for AWS are returned by executing a getClusters request.
The field labels
of suitable workload clusters contains the labels currently attached to the cluster.
Labels of a single workload cluster can be retrieved using the getClusterLabels endpoint.
Selecting workload clusters based on a set of labels can be achieved through the getV5ClustersByLabel operation.
The operation accepts label selectors in the same way that kubectl get -l
does (Kubernetes Label selectors) for listing clusters based on their labels.
The labels of a workload cluster can be modified by issuing a setClusterLabels request to the API.
Keys and labels should adhere to Kubernetes labels syntax and character set.
Label changes should be written as a JSON Merge Patch, RFC 7386.
Changes to labels with keys containing giantswarm.io
is forbidden, changes to label release.giantswarm.io/version
will be validated against available workload cluster releases.
Differing from gsctl
, listing workload cluster labels with the API will show management labels required for operation.
These usually contain giantswarm.io
in its label keys and cannot be changed.
Example
Let’s play through a simple workflow of assigning labels to a newly created workload cluster and selecting it based on the given label.
For brevity authentication and unrelated parts of requests and responses are left out.
After creation, a workload cluster will already have some labels containing information about the workload cluster release and operator version.
GET /v5/clusters/7g4di
{
"api_endpoint": "...",
"create_date": "...",
"id": "7g4di",
"master": {...},
"name": "...",
"owner": "my-org",
"release_version": "11.2.0",
"conditions": [...],
"labels": {
"cluster-operator.giantswarm.io/version": "2.1.9",
"giantswarm.io/cluster": "7g4di",
"giantswarm.io/organization": "my-org",
"release.giantswarm.io/version": "11.2.0"
}
}
In our example, the cluster 7g4di
already has four labels (cluster-operator.giantswarm.io/version
, giantswarm.io/cluster
, giantswarm.io/organization
, release.giantswarm.io/version
).
The newly created cluster will be managed by your team in your upstate office and is planned to be used for testing purposes.
You’ve decided on using label keys my-org/team
and my-org/environment
to specify the clusters designation.
PUT /v5/clusters/7g4di/labels/
{
"labels": {
"my-org/team": "upstate",
"my-org/environment": "testing"
}
}
Another cluster from earlier is also managed by your team in the upstate office but is being used for production.
PUT /v5/clusters/g8s2o/labels/
{
"labels": {
"my-org/team": "upstate",
"my-org/environment": "production"
}
}
From this point on it is possible to select the clusters by label values or label key existence.
POST /v5/clusters/by_label/
{
"labels": "my-org/team=upstate"
}
will return all clusters managed by the upstate office team regardless of other label values.
The full documentation about label selectors can be found on the Kubernetes Labels and Selectors page.
Working with workload 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.
Detailed documentation and examples of kubectl label
and other commands used here can be found in the Kubectl Reference Docs.
Modify workload cluster labels
All means of modifying cluster resources can be used to modify labels of a clusters.cluster.x-k8s.io
resource.
Interactively, cluster labels can be modified using kubectl edit
. Just edit the metadata.labels
property.
kubectl edit clusters.cluster.x-k8s.io/7g4di
It is also possible to modify workload cluster labels with kubectl patch
.
More information about kubectl patch
is available on the Update API Objects in Place Using kubectl patch page.
kubectl patch clusters.cluster.x-k8s.io/7g4di --type merge -p '{"metadata":{"labels":{"my-org/team":"upstate"}}}'
Additionally, kubectl label
can be used to modify workload cluster labels.
kubectl label clusters.cluster.x-k8s.io/7g4di my-org/team=upstate
Show workload cluster labels
Differing from gsctl
, listing workload cluster labels with kubectl
will show management labels required for operation. These usually contain giantswarm.io
in its label keys and cannot be changed.
Labels of all workload clusters:
$ kubectl labels --list --all clusters.cluster.x-k8s.io
Listing labels for Cluster.cluster.x-k8s.io/7g4di:
giantswarm.io/cluster=7g4di
giantswarm.io/organization=my-org
release.giantswarm.io/version=11.2.0
cluster-operator.giantswarm.io/version=2.1.9
my-org/team=upstate
my-org/environment=testing
Listing labels for Cluster.cluster.x-k8s.io/zv86a:
cluster-operator.giantswarm.io/version=2.1.9
giantswarm.io/cluster=q84ct
giantswarm.io/organization=my-org
release.giantswarm.io/version=11.3.0
my-org/team=upstate
my-org/environment=production
Labels of a single workload cluster:
$ kubectl labels --list clusters.cluster.x-k8s.io/7g4di
giantswarm.io/cluster=7g4di
giantswarm.io/organization=my-org
release.giantswarm.io/version=11.2.0
cluster-operator.giantswarm.io/version=2.1.9
my-org/team=upstate
my-org/environment=testing
Select workload clusters by label selector
Many kubectl
commands support the -l, --selector
flag, which allows to limit the selected resources based on given Kubernetes Label selectors.
kubectl get clusters.cluster.x-k8s.io -l 'my-org/team=upstate'
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!