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

You can create an AKS cluster with node labels to set key/value metadata for workload scheduling.

export RANDOM_SUFFIX=$(openssl rand -hex 3)
export RESOURCE_GROUP="myResourceGroup$RANDOM_SUFFIX"
export AKS_CLUSTER_NAME="myAKSCluster$RANDOM_SUFFIX"
az group create --name $RESOURCE_GROUP --___location $REGION

Results:

{
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroupxxx",
  "___location": "eastus2",
  "managedBy": null,
  "name": "myResourceGroupxxx",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

Create the AKS cluster specifying node labels (e.g., dept=IT, costcenter=9000):

az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_CLUSTER_NAME \
    --node-count 2 \
    --nodepool-labels dept=IT costcenter=9000 \
    --generate-ssh-keys --___location $REGION

Results:

{
  "aadProfile": null,
  "addonProfiles": {},
  "agentPoolProfiles": [
    {
      "count": 2,
      "enableAutoScaling": null,
      "mode": "System",
      "name": "nodepool1",
      "nodeLabels": {
        "costcenter": "9000",
        "dept": "IT"
      }
    }
  ],
  "dnsPrefix": "myaksclusterxxx-dns",
  "fqdn": "myaksclusterxxx-xxxxxxxx.hcp.eastus2.azmk8s.io",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroupxxx/providers/Microsoft.ContainerService/managedClusters/myAKSClusterxxx",
  "___location": "eastus2",
  "name": "myAKSClusterxxx",
  "resourceGroup": "myResourceGroupxxx"
}

Verify the labels were set:

az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER_NAME --overwrite-existing
kubectl get nodes --show-labels | grep -e "costcenter=9000" -e "dept=IT"

Create a node pool with a label

You can create an additional node pool with labels for specific scheduling needs.

export NODEPOOL_NAME="labelnp"
az aks nodepool add \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $AKS_CLUSTER_NAME \
    --name $NODEPOOL_NAME \
    --node-count 1 \
    --labels dept=HR costcenter=5000 \

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

az aks nodepool list --resource-group $RESOURCE_GROUP --cluster-name $AKS_CLUSTER_NAME

Results:

[
  {
    "count": 2,
    "name": "nodepool1",
    "nodeLabels": {
      "costcenter": "9000",
      "dept": "IT"
    }
  },
  {
    "count": 1,
    "name": "labelnp",
    "nodeLabels": {
      "costcenter": "5000",
      "dept": "HR"
    },
    "provisioningState": "Creating"
  }
]

Verify the labels were set:

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

Updating labels on existing node pools

You can update the labels on an existing node pool. Note that updating labels will overwrite the old labels.

az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $AKS_CLUSTER_NAME \
    --name $NODEPOOL_NAME \
    --labels dept=ACCT costcenter=6000 \

Verify the new labels are set:

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.