Use labels in an Azure Kubernetes Service (AKS) cluster

If you have multiple node pools, you may want to add a label during node pool creation. Kubernetes labels handle the scheduling rules for nodes. You can add labels to a node pool anytime and apply them to all nodes in the node pool.

In this how-to guide, you learn how to use labels in an Azure Kubernetes Service (AKS) cluster.

Prerequisites

You need the Azure CLI version 2.2.0 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Create an AKS cluster with a label

1. Create an AKS cluster with a label using the az aks create command and specify the --node-labels parameter to set your labels. Labels must be a key/value pair and have a valid syntax.

   az aks create \
       --resource-group myResourceGroup \
       --name myAKSCluster \
       --node-count 2 \
       --nodepool-labels dept=IT costcenter=9000
   

2. Verify the labels were set using the kubectl get nodes --show-labels command.

   kubectl get nodes --show-labels | grep -e "costcenter=9000" -e "dept=IT"
   

Create a node pool with a label

1. Create a node pool with a label using the az aks nodepool add command and specify a name for the --name parameters and labels for the --labels parameter. Labels must be a key/value pair and have a valid syntax

   The following example command creates a node pool named labelnp with the labels dept=HR and costcenter=5000.

   az aks nodepool add \
       --resource-group myResourceGroup \
       --cluster-name myAKSCluster \
       --name labelnp \
       --node-count 1 \
       --labels dept=HR costcenter=5000 \
       --no-wait
   

   The following example output from the az aks nodepool list command shows the labelnp node pool is Creating nodes with the specified nodeLabels:

   [
     {
       ...
       "count": 1,
       ...
       "name": "labelnp",
       "orchestratorVersion": "1.15.7",
       ...
       "provisioningState": "Creating",
       ...
       "nodeLabels":  {
         "costcenter": "5000",
         "dept": "HR"
       },
       ...
     },
    ...
   ]
   

2. Verify the labels were set using the kubectl get nodes --show-labels command.

   kubectl get nodes --show-labels | grep -e "costcenter=5000" -e "dept=HR"
   

Updating labels on existing node pools

1. Update a label on an existing node pool using the az aks nodepool update command. Updating labels on existing node pools overwrites the old labels with the new labels. Labels must be a key/value pair and have a valid syntax.

   az aks nodepool update \
       --resource-group myResourceGroup \
       --cluster-name myAKSCluster \
       --name labelnp \
       --labels dept=ACCT costcenter=6000 \
       --no-wait
   

2. Verify the labels were set using the kubectl get nodes --show-labels command.

   kubectl get nodes --show-labels | grep -e "costcenter=6000" -e "dept=ACCT"
   

Unavailable labels

Reserved system labels

Since the 2021-08-19 AKS release, AKS stopped the ability to make changes to AKS reserved labels. Attempting to change these labels results in an error message.

The following labels are AKS reserved labels. Virtual node usage specifies if these labels could be a supported system feature on virtual nodes. Some properties that these system features change aren't available on the virtual nodes because they require modifying the host.

• Same is included in places where the expected values for the labels don't differ between a standard node pool and a virtual node pool. As virtual node pods don't expose any underlying virtual machine (VM), the VM SKU values are replaced with the SKU Virtual.
• Virtual node version refers to the current version of the virtual Kubelet-ACI connector release.
• Virtual node subnet name is the name of the subnet where virtual node pods are deployed into Azure Container Instance (ACI).
• Virtual node virtual network is the name of the virtual network, which contains the subnet where virtual node pods are deployed on ACI.

Reserved prefixes

The following prefixes are AKS reserved prefixes and can't be used for any node:

• kubernetes.azure.com/
• kubernetes.io/

For more information on reserved prefixes, see Kubernetes well-known labels, annotations, and taints.

Deprecated labels

The following labels are planned for deprecation with the release of Kubernetes v1.24. You should change any label references to the recommended substitute.

*Newly deprecated. For more information, see the Release Notes.

Next steps

Learn more about Kubernetes labels in the Kubernetes labels documentation.