Skip to content

Commit a437abb

Browse files
laurabrenlaurabren
authored
Merge pull request #186839 from erik-ha-msft/erikha-aks-reserved-labels
Initial creation of use-labels.md
2 parents 229aeb4 + 5eef12a commit a437abb

File tree

2 files changed

+196
-0
lines changed

2 files changed

+196
-0
lines changed

‎articles/aks/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,8 @@
226226
href: kubernetes-portal.md
227227
- name: Use tags
228228
href: use-tags.md
229+
- name: Use labels
230+
href: use-labels.md
229231
- name: Security and authentication
230232
items:
231233
- name: Overview of Defender for Containers

‎articles/aks/use-labels.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Use labels in an Azure Kubernetes Service (AKS) cluster
3+
description: Learn how to use labels in an Azure Kubernetes Service (AKS) cluster.
4+
author: erik-ha-msft
5+
ms.author: erikha
6+
ms.service: container-service
7+
ms.topic: how-to
8+
ms.date: 03/03/2022
9+
ms.custom: template-how-to
10+
#Customer intent: As a cluster operator, I want to learn how to use labels in an AKS cluster so that I can set scheduling rules for nodes.
11+
---
12+
13+
# Use labels in an Azure Kubernetes Service (AKS) cluster
14+
15+
If you have multiple node pools, you may want to add a label during node pool creation. [These labels][kubernetes-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.
16+
17+
In this how-to guide, you'll learn how to use labels in an AKS cluster.
18+
19+
## Prerequisites
20+
21+
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][install-azure-cli].
22+
23+
## Create an AKS cluster with a label
24+
25+
To create an AKS cluster with a label, use [az aks create][az-aks-create]. Specify the `--node-labels` parameter to set your labels. Labels must be a key/value pair and have a [valid syntax][kubernetes-label-syntax].
26+
27+
```azurecli-interactive
28+
az aks create \
29+
--resource-group myResourceGroup \
30+
--name myAKSCluster \
31+
--node-count 2 \
32+
--nodepool-labels dept=IT costcenter=9000
33+
```
34+
35+
Verify the labels were set by running `kubectl get nodes --show-labels`.
36+
37+
```bash
38+
kubectl get nodes --show-labels | grep -e "costcenter=9000" -e "dept=IT"
39+
```
40+
41+
## Create a node pool with a label
42+
43+
To create a node pool with a label, use [az aks nodepool add][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][kubernetes-label-syntax]
44+
45+
```azurecli-interactive
46+
az aks nodepool add \
47+
--resource-group myResourceGroup \
48+
--cluster-name myAKSCluster \
49+
--name labelnp \
50+
--node-count 1 \
51+
--labels dept=HR costcenter=5000 \
52+
--no-wait
53+
```
54+
55+
The following example output from the [az aks nodepool list][az-aks-nodepool-list] command shows that *labelnp* is *Creating* nodes with the specified *nodeLabels*:
56+
57+
```azurecli
58+
az aks nodepool list -g myResourceGroup --cluster-name myAKSCluster
59+
60+
```output
61+
[
62+
{
63+
...
64+
"count": 1,
65+
...
66+
"name": "labelnp",
67+
"orchestratorVersion": "1.15.7",
68+
...
69+
"provisioningState": "Creating",
70+
...
71+
"nodeLabels": {
72+
"costcenter": "5000",
73+
"dept": "HR"
74+
},
75+
...
76+
},
77+
...
78+
]
79+
```
80+
81+
Verify the labels were set by running `kubectl get nodes --show-labels`.
82+
83+
```bash
84+
kubectl get nodes --show-labels | grep -e "costcenter=5000" -e "dept=HR"
85+
```
86+
87+
## Updating labels on existing node pools
88+
89+
To update a label on existing node pools, use [az aks nodepool update][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][kubernetes-label-syntax].
90+
91+
```azurecli-interactive
92+
az aks nodepool update \
93+
--resource-group myResourceGroup \
94+
--cluster-name myAKSCluster \
95+
--name labelnp \
96+
--labels dept=ACCT costcenter=6000 \
97+
--no-wait
98+
```
99+
100+
Verify the labels were set by running `kubectl get nodes --show-labels`.
101+
102+
```bash
103+
kubectl get nodes --show-labels | grep -e "costcenter=6000" -e "dept=ACCT"
104+
```
105+
106+
## Unavailable labels
107+
108+
### Reserved system labels
109+
110+
Since the [2021-08-19 AKS release][aks-release-2021-gh], 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.
111+
112+
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.
113+
114+
Some properties that these system features change aren't available on the virtual nodes, because they require modifying the host.
115+
116+
| Label | Value | Example/Options | Virtual node usage |
117+
| ---- | --- | --- | --- |
118+
| kubernetes.azure.com/agentpool | \<agent pool name> | nodepool1 | Same |
119+
| kubernetes.io/arch | amd64 | runtime.GOARCH | N/A |
120+
| kubernetes.io/os | \<OS Type> | Linux/Windows | Same |
121+
| node.kubernetes.io/instance-type | \<VM size> | Standard_NC6 | Virtual |
122+
| topology.kubernetes.io/region | \<Azure region> | westus2 | Same |
123+
| topology.kubernetes.io/zone | \<Azure zone> | 0 | Same |
124+
| kubernetes.azure.com/cluster | \<MC_RgName> | MC_aks_myAKSCluster_westus2 | Same |
125+
| kubernetes.azure.com/mode | \<mode> | User or system | User |
126+
| kubernetes.azure.com/role | agent | Agent | Same |
127+
| kubernetes.azure.com/scalesetpriority | \<VMSS priority> | Spot or regular | N/A |
128+
| kubernetes.io/hostname | \<hostname> | aks-nodepool-00000000-vmss000000 | Same |
129+
| kubernetes.azure.com/storageprofile | \<OS disk storage profile> | Managed | N/A |
130+
| kubernetes.azure.com/storagetier | \<OS disk storage tier> | Premium_LRS | N/A |
131+
| kubernetes.azure.com/instance-sku | \<SKU family> | Standard_N | Virtual |
132+
| kubernetes.azure.com/node-image-version | \<VHD version> | AKSUbuntu-1804-2020.03.05 | Virtual node version |
133+
| kubernetes.azure.com/subnet | \<nodepool subnet name> | subnetName | Virtual node subnet name |
134+
| kubernetes.azure.com/vnet | \<nodepool vnet name> | vnetName | Virtual node virtual network |
135+
| kubernetes.azure.com/ppg | \<nodepool ppg name> | ppgName | N/A |
136+
| kubernetes.azure.com/encrypted-set | \<nodepool encrypted-set name> | encrypted-set-name | N/A |
137+
| kubernetes.azure.com/accelerator | \<accelerator> | nvidia | N/A |
138+
| kubernetes.azure.com/fips_enabled | \<is fips enabled?> | true | N/A |
139+
| kubernetes.azure.com/os-sku | \<os/sku> | [Create or update OS SKU][create-or-update-os-sku] | Linux |
140+
141+
* *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*.
142+
* *Virtual node version* refers to the current version of the [virtual Kubelet-ACI connector release][virtual-kubelet-release].
143+
* *Virtual node subnet name* is the name of the subnet where virtual node pods are deployed into Azure Container Instance (ACI).
144+
* *Virtual node virtual network* is the name of the virtual network, which contains the subnet where virtual node pods are deployed on ACI.
145+
146+
### Reserved prefixes
147+
148+
The following list of prefixes are reserved for usage by AKS and can't be used for any node.
149+
150+
* kubernetes.azure.com/
151+
* kubernetes.io/
152+
153+
For additional reserved prefixes, see [Kubernetes well-known labels, annotations, and taints][kubernetes-well-known-labels].
154+
155+
### Deprecated labels
156+
157+
The following labels are planned for deprecation with the release of [Kubernetes v1.24][aks-release-calendar]. Customers should change any label references to the recommended substitute.
158+
159+
| Label | Recommended substitute | Maintainer |
160+
| --- | --- | --- |
161+
| failure-domain.beta.kubernetes.io/region | topology.kubernetes.io/region | [Kubernetes][kubernetes-labels]
162+
| failure-domain.beta.kubernetes.io/zone | topology.kubernetes.io/zone | [Kubernetes][kubernetes-labels]
163+
| beta.kubernetes.io/arch | kubernetes.io/arch | [Kubernetes][kubernetes-labels]
164+
| beta.kubernetes.io/instance-type | node.kubernetes.io/instance-type | [Kubernetes][kubernetes-labels]
165+
| beta.kubernetes.io/os | kubernetes.io/os | [Kubernetes][kubernetes-labels]
166+
| node-role.kubernetes.io/agent* | kubernetes.azure.com/role=agent | Azure Kubernetes Service
167+
| kubernetes.io/role* | kubernetes.azure.com/role=agent | Azure Kubernetes Service
168+
| Agentpool* | kubernetes.azure.com/agentpool | Azure Kubernetes Service
169+
| Storageprofile* | kubernetes.azure.com/storageprofile | Azure Kubernetes Service
170+
| Storagetier* | kubernetes.azure.com/storagetier | Azure Kubernetes Service
171+
| Accelerator* | kubernetes.azure.com/accelerator | Azure Kubernetes Service
172+
173+
*Newly deprecated. For more information, see [Release Notes][aks-release-notes-gh] on when these labels will no longer be maintained.
174+
175+
## Next steps
176+
177+
Learn more about Kubernetes labels at the [Kubernetes labels documentation][kubernetes-labels].
178+
179+
<!-- LINKS - external -->
180+
[aks-release-2021-gh]: https://github.com/Azure/AKS/releases/tag/2021-08-19
181+
[aks-release-notes-gh]: https://github.com/Azure/AKS/releases
182+
[kubernetes-labels]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
183+
[kubernetes-label-syntax]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set
184+
[kubernetes-well-known-labels]: https://kubernetes.io/docs/reference/labels-annotations-taints/
185+
[virtual-kubelet-release]: https://github.com/virtual-kubelet/azure-aci/releases
186+
187+
<!-- LINKS - internal -->
188+
[aks-release-calendar]: ./supported-kubernetes-versions.md#aks-kubernetes-release-calendar
189+
[az-aks-create]: /cli/azure/aks#az-aks-create
190+
[az-aks-nodepool-add]: /cli/azure/aks#az-aks-nodepool-add
191+
[az-aks-nodepool-list]: /cli/azure/aks/nodepool#az-aks-nodepool-list
192+
[az-aks-nodepool-update]: /cli/azure/aks/nodepool#az-aks-nodepool-update
193+
[create-or-update-os-sku]: /rest/api/aks/agent-pools/create-or-update#ossku
194+
[install-azure-cli]: /cli/azure/install-azure-cli

0 commit comments

Comments
 (0)