Managing Kubernetes node labels

Written by

Improved by

Updated at May 5, 2025

Restrictions for Kubernetes label names and values
Assigning Kubernetes labels when creating a node group
Assigning a Kubernetes label for an existing node group
Deleting a Kubernetes label from a node group

Individual nodes in node groups are Yandex Compute Cloud virtual machines with automatically generated names. To configure nodes, follow the instructions below or other node group management guides.

Alert

Do not change node VM settings, including names, network interfaces, and SSH keys, using the Compute Cloud interfaces or SSH connections to the VM.

This can disrupt the operation of individual nodes, groups of nodes, and the whole Managed Service for Kubernetes cluster.

Restrictions for Kubernetes label names and values

Kubernetes labels are key:value pairs.

Kubernetes label keys of nodes may consist of two parts separated by /: prefix and name.

A prefix is an optional part of a key. The prefix requirements are as follows:

It must be a DNS subdomain, i.e., a series of DNS tags separated by ..
It may be up to 253 characters long.
The last character must be followed by /.

A name is a required part of a key. Follow these naming requirements:

May be up to 63 characters long.
It may contain lowercase Latin letters, numbers, and -_. symbols.
Use a letter or number for the first and last characters.

The same rules apply to the value as to the name.

Label example: app.kubernetes.io/name: mysql, where app.kubernetes.io/ is the prefix, name is the name, and mysql, the value.

Assigning Kubernetes labels when creating a node group

You can add Kubernetes labels to all Managed Service for Kubernetes nodes in a node group at the same time. To do this, specify the labels in the node_labels parameter when creating a Managed Service for Kubernetes node group.

Create a Managed Service for Kubernetes cluster.

You can use an existing Managed Service for Kubernetes cluster or create a new one.
Create a node group with Kubernetes labels:
Management console

CLI

Terraform

API
1. In the management console, select the folder where you created the Managed Service for Kubernetes cluster.
2. From the list of services, select Managed Service for Kubernetes.
3. Select the Managed Service for Kubernetes cluster to create a node group for.
4. On the Managed Service for Kubernetes cluster page, go to the Node manager tab.
5. Click Create a node group.
6. Enter a name for the Managed Service for Kubernetes node group.
7. In the Kubernetes version field, select a Kubernetes version for Managed Service for Kubernetes nodes.
8. Under Scaling:
  - Select the scaling policy type.
  - Specify the number of nodes in the Managed Service for Kubernetes node group.
9. Under Changes during creation and updates, specify the maximum number of instances by which you can exceed or reduce the size of the Managed Service for Kubernetes group.
10. Under Computing resources:
  - Select a platform.
  - Specify the required number of vCPUs, guaranteed vCPU performance, and the amount of RAM.
11. Under Storage:
  - Specify the Managed Service for Kubernetes node Disk type:
    
    HDD: Standard network drive; HDD network block storage.
    
    SSD: Fast network drive; SSD network block storage.
    
    Non-replicated SSD: Network drive with enhanced performance achieved by eliminating redundancy. You can only change the size of this type of disk in 93 GB increments.
    
    SSD IO: Network drive with the same performance characteristics as Non-replicated SSD, plus redundancy. You can only change the size of this type of disk in 93 GB increments.
  - Specify the Managed Service for Kubernetes node disk size.
12. Under Network settings:
  - In the Public address field, select an IP address assignment method:
    
    Auto: Assign a random IP address from the Yandex Cloud IP address pool.
    
    No address: Not to assign a public IP address.
  - Specify how Managed Service for Kubernetes nodes should be distributed across the availability zones and networks.
13. Under Access, specify the information required to access the Managed Service for Kubernetes node:
  - Under Login, enter a username.
  - In the SSH key field, paste the contents of the public key file.
14. Under Maintenance window settings:
  - In the Maintenance frequency / Disable field, select your preferred maintenance window:
    
    Disable: Automatic updates disabled.
    
    Anytime: Updates allowed at any time.
    
    Daily: Updates will take place within the time interval specified in the Time (UTC) and duration field.
    
    Custom: Updates will take place within the time interval specified in the Weekly schedule field.
15. Under Additional:
  - In the Node labels field, click Add label and specify the label key and value. Add multiple labels if needed.
16. Click Create.
Create a Managed Service for Kubernetes node group:
```
yc managed-kubernetes node-group create \
 --name k8s-labels-node \
 --cluster-name k8s-labels \
 --disk-type network-ssd \
 --fixed-size 1 \
 --node-labels environment=production,apps/tier=backend
```
Where:
- --name: Managed Service for Kubernetes node group name.
- --cluster-name: Name of the Managed Service for Kubernetes cluster to create the node group in.
- --disk-type: Disk type on the Managed Service for Kubernetes node.
- --fixed-size: Number of Managed Service for Kubernetes nodes in the group.
- --node-labels: Managed Service for Kubernetes node labels. You can specify multiple labels separated by commas.
Result:
```
done (2m19s)
id: catkuapro07e********
cluster_id: abcsk1s2f3fm********
created_at: "2020-09-24T13:32:24Z"
name: k8s-labels-node
status: RUNNING
node_template:
  platform_id: standard-v2
  resources_spec:
    memory: "4294967296"
    cores: "2"
    core_fraction: "100"
  boot_disk_spec:
    disk_type_id: network-ssd
    disk_size: "103079215104"
  v4_address_spec: {}
  scheduling_policy: {}
scale_policy:
  fixed_scale:
    size: "1"
allocation_policy:
  locations:
  - zone_id: ru-central1-a
    subnet_id: e9bm87gkjd81********
deploy_policy:
  max_expansion: "3"
instance_group_id: cl1v2gh33j1c********
node_version: "1.17"
version_info:
  current_version: "1.17"
maintenance_policy:
  auto_upgrade: true
  auto_repair: true
  maintenance_window:
    anytime: {}
node_labels:
  apps/tier: backend
  environment: production
```
Warning

A Managed Service for Kubernetes node group will be recreated from scratch.
1. Open the current configuration file describing the Managed Service for Kubernetes node group.
  
  For more information about creating this file, see Creating a node group.
2. Add the node_labels parameter to the Managed Service for Kubernetes node group description:
  resource "yandex_kubernetes_node_group" "<node_group_name>" { cluster_id = yandex_kubernetes_cluster.<cluster_name>.id ... node_labels = { "<label_1>" = "<value_1>" "<label_2>" = "<value_2>" ... } }
3. Make sure the configuration files are correct.
  1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
  2. Run this command:
    
    terraform validate
    
    Terraform will show any errors found in your configuration files.
4. Confirm updating the resources.
  1. Run this command to view the planned changes:
    
    terraform plan
    
    If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
  2. If everything looks correct, apply the changes:
    
    Run this command:
    
    terraform apply
    
    Confirm updating the resources.
    
    Wait for the operation to complete.
  For more information, see the Terraform provider documentation.
To create a Managed Service for Kubernetes node group, use the create method for the NodeGroup resource.

Get information about the created node group with Kubernetes labels:

Management console

CLI

API

In the management console, select the folder where you created the Managed Service for Kubernetes cluster.
From the list of services, select Managed Service for Kubernetes.
Select the Managed Service for Kubernetes cluster where the node group was created.
On the Managed Service for Kubernetes cluster page, go to the Node manager tab.
Open the page of one of the Managed Service for Kubernetes nodes and go to the Labels tab. The tab lists the system and user Kubernetes node labels.

Install kubect and configure it to work with the new cluster.

View all the nodes in a Managed Service for Kubernetes cluster:

kubectl get nodes

Result:

NAME                        STATUS   ROLES    AGE  VERSION
catkuapro07e********-hgjd   Ready    <none>   1h   v1.17.8
catkuapro07e********-lskc   Ready    <none>   1h   v1.17.8

Get information on a selected Managed Service for Kubernetes cluster node:

kubectl describe node catkuapro07e********-hgjd

Result:

Name:               catkuapro07e********-hgjd
Roles:              <none>
Labels:             apps/tier=backend
                    beta.kubernetes.io/arch=amd64
                    beta.kubernetes.io/instance-type=standard-v2
                    beta.kubernetes.io/os=linux
                    environment=production
                    failure-domain.beta.kubernetes.io/zone=ru-central1-a
                    kubernetes.io/arch=amd64
                    kubernetes.io/hostname=catkuapro07e********-hgjd
                    kubernetes.io/os=linux
                    node.kubernetes.io/kube-proxy-ds-ready=true
                    node.kubernetes.io/masq-agent-ds-ready=true
                    node.kubernetes.io/node-problem-detector-ds-ready=true
                    yandex.cloud/node-group-id=catkuapro07e********
                    yandex.cloud/pci-topology=k8s
                    yandex.cloud/preemptible=false

To view Managed Service for Kubernetes node details, use the list method for the NodeGroup resource.

Assigning a Kubernetes label for an existing node group

Assigning Kubernetes labels does not result in recreation of a node group.

CLI

Terraform

API

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To assign a Kubernetes label for an existing node group, run this command:

yc managed-kubernetes node-group add-node-labels \
   --id <node_group_ID> \
   --labels <key>=<value>, ...

The command contains the following parameters:

--id: Node group ID. You can get it with the list of node groups in the Managed Service for Kubernetes cluster.
--labels: Kubernetes labels in <key>=<value> format. You can specify one label or multiple labels separated by commas.

To assign a Kubernetes label for an existing node group:

Open the current Terraform configuration file describing the Managed Service for Kubernetes node group.

For more information about creating this file, see Creating a node group.

In the node group description, add the node_labels section:

resource "yandex_kubernetes_node_group" "<node_group_name>" {
  ...
  node_labels {
    "<label_name>" = "<label_value>"
    ...
  }
  ...
}

You can assign multiple labels. To do so, specify each label in a separate line.

Make sure the configuration files are correct.
1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
2. Run this command:
```
terraform validate
```
  Terraform will show any errors found in your configuration files.
Confirm updating the resources.
1. Run this command to view the planned changes:
```
terraform plan
```
  If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
2. If everything looks correct, apply the changes:
  1. Run this command:
```
terraform apply
```
  2. Confirm updating the resources.
  3. Wait for the operation to complete.
For more information, see the Terraform provider documentation.

To assign a Kubernetes label to an existing node group, use the update method for the NodeGroup resource and provide the following in the request:

Kubernetes labels in the nodeLabels parameter.
nodeLabels parameter to update in the updateMask parameter.

Warning

The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

Deleting a Kubernetes label from a node group

Deleting Kubernetes labels does not result in recreation of a node group.

CLI

Terraform

API

If you do not have the Yandex Cloud CLI yet, install and initialize it.

To remove a Kubernetes label from a node group, run this command:

yc managed-kubernetes node-group remove-node-labels \
   --id <node_group_ID> \
   --labels <label_key>, ...

The command contains the following parameters:

--id: Node group ID. You can get it with the list of node groups in the Managed Service for Kubernetes cluster.
--labels: Keys of the Kubernetes labels to remove. You can specify one label or multiple labels separated by commas.

To remove a Kubernetes label from a node group:

Open the current Terraform configuration file describing the Managed Service for Kubernetes node group.

For more information about creating this file, see Creating a node group.
In the node group description, delete the Kubernetes labels you no longer need from node_labels.
Make sure the configuration files are correct.
1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
2. Run this command:
```
terraform validate
```
  Terraform will show any errors found in your configuration files.
Confirm updating the resources.
1. Run this command to view the planned changes:
```
terraform plan
```
  If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
2. If everything looks correct, apply the changes:
  1. Run this command:
```
terraform apply
```
  2. Confirm updating the resources.
  3. Wait for the operation to complete.
For more information, see the Terraform provider documentation.

To remove a Kubernetes label from a node group, use the update method for the NodeGroup resource and provide the following in the request:

New list of Kubernetes labels in the nodeLabels parameter. If you want to remove all the labels, provide "nodeLabels": {} in your request.
nodeLabels parameter to update in the updateMask parameter.

Warning

Managing Kubernetes node labels

Restrictions for Kubernetes label names and valuesRestrictions for Kubernetes label names and values

Assigning Kubernetes labels when creating a node groupAssigning Kubernetes labels when creating a node group

Assigning a Kubernetes label for an existing node groupAssigning a Kubernetes label for an existing node group

Deleting a Kubernetes label from a node groupDeleting a Kubernetes label from a node group

Was the article helpful?

Restrictions for Kubernetes label names and values

Assigning Kubernetes labels when creating a node group

Assigning a Kubernetes label for an existing node group

Deleting a Kubernetes label from a node group