Managing Kubernetes node labels

Written by

Improved by

Updated at December 12, 2025

Restrictions for Kubernetes label names and values
Adding Kubernetes labels when creating a node group
Adding a Kubernetes label to an existing node group
Removing 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.

Adding Kubernetes labels when creating a node group

You can add Kubernetes labels to all Managed Service for Kubernetes nodes in a node group at once. 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. In 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 the Kubernetes version for the 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 VMs by which you can exceed or reduce the Managed Service for Kubernetes group size.
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 disk type in 93 GB increments.
    
    SSD IO: Network drive with the same performance specifications as Non-replicated SSD, plus redundancy. You can only change the size of this disk type in 93 GB increments.
  - Specify the Managed Service for Kubernetes node disk size.
12. Under Network settings:
  - In the Public address field, select the IP address assignment method:
    
    Auto: Assign a random IP address from the Yandex Cloud IP address pool.
    
    No address: Do not assign a public IP address.
  - Specify how Managed Service for Kubernetes nodes should be placed across the availability zones and networks.
13. Under Access, specify the credentials to access the Managed Service for Kubernetes node:
  - In the Login field, enter the 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 its 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.
1. Open the current configuration file describing the Managed Service for Kubernetes node group.
  
  Learn how to create this file in Creating a node group.
2. Add the node_labels property 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.
  Timeouts
  
  The Terraform provider sets time limits for operations with Managed Service for Kubernetes cluster node groups:
  
  Creating and editing: 60 minutes.
  
  Deleting: 20 minutes.
  
  Operations in excess of this time will be interrupted.
  
  How do I modify these limits?
  Add the timeouts section to the cluster node group description, e.g.:
  
  resource "yandex_kubernetes_node_group" "<node_group_name>" { ... timeouts { create = "1h30m" update = "1h30m" delete = "60m" } }
  For more information, see this Terraform provider guide.
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.
In the list of services, select Managed Service for Kubernetes.
Select the Managed Service for Kubernetes cluster where you created the node group.
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 navigate 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 about the 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 the Managed Service for Kubernetes node details, use the list method for the NodeGroup resource.

Adding a Kubernetes label to an existing node group

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

CLI

Terraform

API

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To add a Kubernetes label to 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 or multiple labels separated by commas.

To add a Kubernetes label to an existing node group:

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

Learn how to create this file in 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 add multiple labels by specifying 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.
Timeouts
The Terraform provider sets time limits for operations with Managed Service for Kubernetes cluster node groups:
- Creating and editing: 60 minutes.
- Deleting: 20 minutes.
Operations in excess of this time will be interrupted.
How do I modify these limits?
Add the timeouts section to the cluster node group description, e.g.:

resource "yandex_kubernetes_node_group" "<node_group_name>" { ... timeouts { create = "1h30m" update = "1h30m" delete = "60m" } }
For more information, see this Terraform provider guide.

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

Removing a Kubernetes label from a node group

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

CLI

Terraform

API

If you do not have the Yandex Cloud CLI installed 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 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.

Learn how to create this file in Creating a node group.
In the node group description, remove 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.
Timeouts
The Terraform provider sets time limits for operations with Managed Service for Kubernetes cluster node groups:
- Creating and editing: 60 minutes.
- Deleting: 20 minutes.
Operations in excess of this time will be interrupted.
How do I modify these limits?
Add the timeouts section to the cluster node group description, e.g.:

resource "yandex_kubernetes_node_group" "<node_group_name>" { ... timeouts { create = "1h30m" update = "1h30m" delete = "60m" } }
For more information, see this Terraform provider guide.

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

Adding Kubernetes labels when creating a node groupAdding Kubernetes labels when creating a node group

Adding a Kubernetes label to an existing node groupAdding a Kubernetes label to an existing node group

Removing a Kubernetes label from a node groupRemoving a Kubernetes label from a node group

Was the article helpful?

Restrictions for Kubernetes label names and values

Adding Kubernetes labels when creating a node group

Adding a Kubernetes label to an existing node group

Removing a Kubernetes label from a node group