| title | description | author | ms.author | ms.service | ms.topic | ms.date | ms.custom |
|---|---|---|---|---|---|---|---|
Use labels in an Azure Kubernetes Service (AKS) cluster |
Learn how to use labels in an Azure Kubernetes Service (AKS) cluster. |
erik-ha-msft |
erikha |
container-service |
how-to |
03/03/2022 |
template-how-to |
If you have multiple node pools, you may want to add a label during node pool creation. These labels are visible in Kubernetes for handling scheduling rules for nodes. You can add labels to a node pool anytime, and they'll be set on all nodes in the node pool.
In this how-to guide, you'll learn how to use labels in an AKS cluster.
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.
To create an AKS cluster with a label, use az aks create. 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
Verify the labels were set by running kubectl get nodes --show-labels.
kubectl get nodes --show-labels | grep -e "costcenter=9000" -e "dept=IT"To create a node pool with a label, use az aks nodepool add. Specify the name labelnp and use the --labels parameter to specify dept=HR and costcenter=5000 for labels. Labels must be a key/value pair and have a valid syntax
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 that labelnp is Creating nodes with the specified nodeLabels:
az aks nodepool list -g myResourceGroup --cluster-name myAKSCluster
```output
[
{
...
"count": 1,
...
"name": "labelnp",
"orchestratorVersion": "1.15.7",
...
"provisioningState": "Creating",
...
"nodeLabels": {
"costcenter": "5000",
"dept": "HR"
},
...
},
...
]
Verify the labels were set by running kubectl get nodes --show-labels.
kubectl get nodes --show-labels | grep -e "costcenter=5000" -e "dept=HR"To update a label on existing node pools, use az aks nodepool update. Updating labels on existing node pools will overwrite 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
Verify the labels were set by running kubectl get nodes --show-labels.
kubectl get nodes --show-labels | grep -e "costcenter=6000" -e "dept=ACCT"Since the 2021-08-19 AKS release, Azure Kubernetes Service (AKS) has stopped the ability to make changes to AKS reserved labels. Attempting to change these labels will result in an error message.
The following labels are reserved for use by AKS. 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.
| Label | Value | Example/Options | Virtual node usage |
|---|---|---|---|
| kubernetes.azure.com/agentpool | <agent pool name> | nodepool1 | Same |
| kubernetes.io/arch | amd64 | runtime.GOARCH | N/A |
| kubernetes.io/os | <OS Type> | Linux/Windows | Same |
| node.kubernetes.io/instance-type | <VM size> | Standard_NC6 | Virtual |
| topology.kubernetes.io/region | <Azure region> | westus2 | Same |
| topology.kubernetes.io/zone | <Azure zone> | 0 | Same |
| kubernetes.azure.com/cluster | <MC_RgName> | MC_aks_myAKSCluster_westus2 | Same |
| kubernetes.azure.com/mode | <mode> | User or system | User |
| kubernetes.azure.com/role | agent | Agent | Same |
| kubernetes.azure.com/scalesetpriority | <VMSS priority> | Spot or regular | N/A |
| kubernetes.io/hostname | <hostname> | aks-nodepool-00000000-vmss000000 | Same |
| kubernetes.azure.com/storageprofile | <OS disk storage profile> | Managed | N/A |
| kubernetes.azure.com/storagetier | <OS disk storage tier> | Premium_LRS | N/A |
| kubernetes.azure.com/instance-sku | <SKU family> | Standard_N | Virtual |
| kubernetes.azure.com/node-image-version | <VHD version> | AKSUbuntu-1804-2020.03.05 | Virtual node version |
| kubernetes.azure.com/subnet | <nodepool subnet name> | subnetName | Virtual node subnet name |
| kubernetes.azure.com/vnet | <nodepool vnet name> | vnetName | Virtual node virtual network |
| kubernetes.azure.com/ppg | <nodepool ppg name> | ppgName | N/A |
| kubernetes.azure.com/encrypted-set | <nodepool encrypted-set name> | encrypted-set-name | N/A |
| kubernetes.azure.com/accelerator | <accelerator> | nvidia | N/A |
| kubernetes.azure.com/fips_enabled | <is fips enabled?> | true | N/A |
| kubernetes.azure.com/os-sku | <os/sku> | Create or update OS SKU | Linux |
- 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.
The following list of prefixes are reserved for usage by AKS and can't be used for any node.
- kubernetes.azure.com/
- kubernetes.io/
For additional reserved prefixes, see Kubernetes well-known labels, annotations, and taints.
The following labels are planned for deprecation with the release of Kubernetes v1.24. Customers should change any label references to the recommended substitute.
| Label | Recommended substitute | Maintainer |
|---|---|---|
| failure-domain.beta.kubernetes.io/region | topology.kubernetes.io/region | Kubernetes |
| failure-domain.beta.kubernetes.io/zone | topology.kubernetes.io/zone | Kubernetes |
| beta.kubernetes.io/arch | kubernetes.io/arch | Kubernetes |
| beta.kubernetes.io/instance-type | node.kubernetes.io/instance-type | Kubernetes |
| beta.kubernetes.io/os | kubernetes.io/os | Kubernetes |
| node-role.kubernetes.io/agent* | kubernetes.azure.com/role=agent | Azure Kubernetes Service |
| kubernetes.io/role* | kubernetes.azure.com/role=agent | Azure Kubernetes Service |
| Agentpool* | kubernetes.azure.com/agentpool | Azure Kubernetes Service |
| Storageprofile* | kubernetes.azure.com/storageprofile | Azure Kubernetes Service |
| Storagetier* | kubernetes.azure.com/storagetier | Azure Kubernetes Service |
| Accelerator* | kubernetes.azure.com/accelerator | Azure Kubernetes Service |
*Newly deprecated. For more information, see Release Notes on when these labels will no longer be maintained.
Learn more about Kubernetes labels at the Kubernetes labels documentation.