Skip to content

Commit 17bad14

Browse files
author
naman-msft
committed
added new aks docs
1 parent 6b50195 commit 17bad14

File tree

4 files changed

+450
-2
lines changed

4 files changed

+450
-2
lines changed

‎scenarios/azure-aks-docs/articles/aks/auto-upgrade-cluster.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,6 @@ az aks create --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER_NAME --auto-u
9797
* Set the auto-upgrade channel on an existing cluster using the [`az aks update`][az-aks-update] command with the `auto-upgrade-channel` parameter.
9898

9999
```azurecli-interactive
100-
export RESOURCE_GROUP="apache-airflow-rg"
101-
export AKS_CLUSTER_NAME="apache-airflow-aks"
102100
az aks update --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER_NAME --auto-upgrade-channel stable
103101
```
104102

‎scenarios/azure-aks-docs/articles/aks/auto-upgrade-node-os-image.md

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: autoupgrade Node OS Images
3+
description: Learn how to choose an upgrade channel that best supports your needs for cluster's node OS security and maintenance.
4+
ms.topic: how-to
5+
ms.custom: build-2023, devx-track-azurecli, innovation-engine
6+
ms.author: kaarthis
7+
author: kaarthis
8+
ms.subservice: aks-upgrade
9+
ms.date: 05/10/2024
10+
---
11+
12+
# autoupgrade node OS images
13+
14+
AKS provides multiple autoupgrade channels dedicated to timely node-level OS security updates. This channel is different from cluster-level Kubernetes version upgrades and supersedes it.
15+
16+
## Interactions between node OS autoupgrade and cluster autoupgrade
17+
18+
Node-level OS security updates are released at a faster rate than Kubernetes patch or minor version updates. The node OS autoupgrade channel grants you flexibility and enables a customized strategy for node-level OS security updates. Then, you can choose a separate plan for cluster-level Kubernetes version [autoupgrades][Autoupgrade].
19+
It's best to use both cluster-level [autoupgrades][Autoupgrade] and the node OS autoupgrade channel together. Scheduling can be fine-tuned by applying two separate sets of [maintenance windows][planned-maintenance] - `aksManagedAutoUpgradeSchedule` for the cluster [autoupgrade][Autoupgrade] channel and `aksManagedNodeOSUpgradeSchedule` for the node OS autoupgrade channel.
20+
21+
## Channels for node OS image upgrades
22+
23+
The selected channel determines the timing of upgrades. When making changes to node OS auto-upgrade channels, allow up to 24 hours for the changes to take effect.
24+
25+
> [!NOTE]
26+
> - Once you change from one channel to another channel, **a reimage is triggered leading to rolling nodes**.
27+
> - Node OS image auto-upgrade won't affect the cluster's Kubernetes version. Starting with API version 2023-06-01, the default for any new cluster created is `NodeImage`.
28+
29+
The following upgrade channels are available. You're allowed to choose one of these options:
30+
31+
|Channel|Description|OS-specific behavior|
32+
|---|---|---|
33+
| `None`| Your nodes don't have security updates applied automatically. This means you're solely responsible for your security updates.|N/A|
34+
| `Unmanaged`|OS updates are applied automatically through the OS built-in patching infrastructure. Newly allocated machines are unpatched initially. The OS's infrastructure patches them at some point.|Ubuntu and Azure Linux (CPU node pools) apply security patches through unattended upgrade/dnf-automatic roughly once per day around 06:00 UTC. Windows doesn't automatically apply security patches, so this option behaves equivalently to `None`. You need to manage the reboot process by using a tool like [kured][kured].|
35+
| `SecurityPatch`|OS security patches, which are AKS-tested, fully managed, and applied with safe deployment practices. AKS regularly updates the node's virtual hard disk (VHD) with patches from the image maintainer labeled "security only." There might be disruptions when the security patches are applied to the nodes. However AKS is limiting disruptions by only reimaging your nodes only when necessary, such as for certain kernel security packages. When the patches are applied, the VHD is updated and existing machines are upgraded to that VHD, honoring maintenance windows and surge settings. If AKS decides that reimaging nodes isn't necessary, it patches nodes live without draining pods and performs no VHD update. This option incurs the extra cost of hosting the VHDs in your node resource group. If you use this channel, Linux [unattended upgrades][unattended-upgrades] are disabled by default.|Azure Linux doesn't support this channel on GPU-enabled VMs. `SecurityPatch` works on kubernetes patch versions that are deprecated, so long as the minor Kubernetes version is still supported.|
36+
| `NodeImage`|AKS updates the nodes with a newly patched VHD containing security fixes and bug fixes on a weekly cadence. The update to the new VHD is disruptive, following maintenance windows and surge settings. No extra VHD cost is incurred when choosing this option. If you use this channel, Linux [unattended upgrades][unattended-upgrades] are disabled by default. Node image upgrades are supported as long as cluster k8s minor version is still in support. Node images are AKS-tested, fully managed, and applied with safe deployment practices.|
37+
38+
## What to choose - SecurityPatch Channel or NodeImage Channel?
39+
40+
There are two important considerations for you to choose between `SecurityPatch` or `NodeImage` channels.
41+
42+
|Property|NodeImage Channel|SecurityPatch Channel|Recommended Channel|
43+
|---|---|---|---|
44+
| `Speed of shipping`|The typical build, test, release, and rollout timelines for a new VHD can take approximately 2 weeks following safe deployment practices. Although in the event of CVEs, accelerated rollouts can occur on a case by case basis. The exact timing when a new VHD hits a region can be monitored via [release-tracker]. | SecurityPatch releases are relatively faster than `NodeImage`, even with safe deployment practices. SecurityPatch has the advantage of 'Live-patching' in Linux environments, where patching leads to selective 'reimaging' and does not reimage every time a patch gets applied. Re-image if it happens is controlled by maintenance windows. |`SecurityPatch`|
45+
| `Bugfixes`| Carries bug fixes in addition to security fixes.| Strictly carries only security fixes.| `NodeImage`|
46+
47+
## Set the node OS autoupgrade channel on a new cluster
48+
49+
### [Azure CLI](#tab/azure-cli)
50+
51+
* Set the node OS autoupgrade channel on a new cluster using the [`az aks create`][az-aks-create] command with the `--node-os-upgrade-channel` parameter. The following example sets the node OS autoupgrade channel to `SecurityPatch`.
52+
53+
```text
54+
export RANDOM_SUFFIX=$(openssl rand -hex 3)
55+
export RESOURCE_GROUP="myResourceGroup$RANDOM_SUFFIX"
56+
export AKS_CLUSTER="myAKSCluster$RANDOM_SUFFIX"
57+
az aks create \
58+
--resource-group $RESOURCE_GROUP \
59+
--name $AKS_CLUSTER \
60+
--node-os-upgrade-channel SecurityPatch \
61+
--generate-ssh-keys
62+
```
63+
64+
### [Azure portal](#tab/azure-portal)
65+
66+
1. In the Azure portal, select **Create a resource** > **Containers** > **Azure Kubernetes Service (AKS)**.
67+
2. In the **Basics** tab, under **Cluster details**, select the desired channel type from the **Node security channel type** dropdown.
68+
69+
:::image type="content" source="./media/auto-upgrade-node-os-image/set-nodeimage-channel-portal.png" alt-text="A screenshot of the Azure portal showing the node security channel type option in the Basics tab of the AKS cluster creation page.":::
70+
71+
3. Select **Security channel scheduler** and choose the desired maintenance window using the [Planned Maintenance feature](./planned-maintenance.md). We recommend selecting the default option **Every week on Sunday (recommended)**.
72+
73+
:::image type="content" source="./media/auto-upgrade-node-os-image/set-nodeimage-maintenance-window-portal.png" alt-text="A screenshot of the Azure portal showing the security channel scheduler option in the Basics tab of the AKS cluster creation page.":::
74+
75+
4. Complete the remaining steps to create the cluster.
76+
77+
---
78+
79+
## Set the node OS autoupgrade channel on an existing cluster
80+
81+
### [Azure CLI](#tab/azure-cli)
82+
83+
* Set the node os autoupgrade channel on an existing cluster using the [`az aks update`][az-aks-update] command with the `--node-os-upgrade-channel` parameter. The following example sets the node OS autoupgrade channel to `SecurityPatch`.
84+
85+
```azurecli-interactive
86+
az aks update --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER --node-os-upgrade-channel SecurityPatch
87+
```
88+
89+
Results:
90+
91+
<!-- expected_similarity=0.3 -->
92+
```JSON
93+
{
94+
"autoUpgradeProfile": {
95+
"nodeOsUpgradeChannel": "SecurityPatch"
96+
}
97+
}
98+
```
99+
100+
### [Azure portal](#tab/azure-portal)
101+
102+
1. In the Azure portal, navigate to your AKS cluster.
103+
2. In the **Settings** section, select **Cluster configuration**.
104+
3. Under **Security updates**, select the desired channel type from the **Node security channel type** dropdown.
105+
106+
:::image type="content" source="./media/auto-upgrade-node-os-image/set-nodeimage-channel-portal-existing.png" alt-text="A screenshot of the Azure portal showing the node security channel type option in the Cluster configuration page of an existing AKS cluster.":::
107+
108+
4. For **Security channel scheduler**, select **Add schedule**.
109+
5. On the **Add maintenance schedule** page, configure the following maintenance window settings using the [Planned Maintenance feature](./planned-maintenance.md):
110+
111+
* **Repeats**: Select the desired frequency for the maintenance window. We recommend selecting **Weekly**.
112+
* **Frequency**: Select the desired day of the week for the maintenance window. We recommend selecting **Sunday**.
113+
* **Maintenance start date**: Select the desired start date for the maintenance window.
114+
* **Maintenance start time**: Select the desired start time for the maintenance window.
115+
* **UTC offset**: Select the desired UTC offset for the maintenance window. If not set, the default is **+00:00**.
116+
117+
:::image type="content" source="./media/auto-upgrade-node-os-image/set-nodeimage-maintenance-window-portal-existing.png" alt-text="A screenshot of the Azure portal showing the maintenance schedule configuration options in the Add maintenance schedule page of an existing AKS cluster.":::
118+
119+
6. Select **Save** > **Apply**.
120+
121+
---
122+
123+
## Update ownership and schedule
124+
125+
The default cadence means there's no planned maintenance window applied.
126+
127+
|Channel|Updates Ownership|Default cadence|
128+
|---|---|---|
129+
| `Unmanaged`|OS driven security updates. AKS has no control over these updates.|Nightly around 6AM UTC for Ubuntu and Azure Linux. Monthly for Windows.|
130+
| `SecurityPatch`|AKS-tested, fully managed, and applied with safe deployment practices. For more information, see [Increased security and resiliency of Canonical workloads on Azure][Blog].|Typically faster than weekly, AKS determined cadence.|
131+
| `NodeImage`|AKS-tested, fully managed, and applied with safe deployment practices. For more real time information on releases, look up [AKS Node Images in Release tracker][release-tracker] |Weekly.|
132+
133+
> [!NOTE]
134+
> While Windows security updates are released on a monthly basis, using the `Unmanaged` channel will not automatically apply these updates to Windows nodes. If you choose the `Unmanaged` channel, you need to manage the reboot process for Windows nodes.
135+
136+
## Node channel known limitations
137+
138+
- Currently, when you set the [cluster autoupgrade channel][Autoupgrade] to `node-image`, it also automatically sets the node OS autoupgrade channel to `NodeImage`. You can't change node OS autoupgrade channel value if your cluster autoupgrade channel is `node-image`. In order to set the node OS autoupgrade channel value, check the [cluster autoupgrade channel][Autoupgrade] value isn't `node-image`.
139+
140+
- The `SecurityPatch` channel isn't supported on Windows OS node pools.
141+
142+
> [!NOTE]
143+
> Use CLI version 2.61.0 or above for the `SecurityPatch` channel.
144+
145+
## Node OS planned maintenance windows
146+
147+
Planned maintenance for the node OS autoupgrade starts at your specified maintenance window.
148+
149+
> [!NOTE]
150+
> To ensure proper functionality, use a maintenance window of four hours or more.
151+
152+
For more information on Planned Maintenance, see [Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster][planned-maintenance].
153+
154+
## Node OS autoupgrades FAQ
155+
156+
### How can I check the current nodeOsUpgradeChannel value on a cluster?
157+
158+
Run the `az aks show` command and check the "autoUpgradeProfile" to determine what value the `nodeOsUpgradeChannel` is set to:
159+
160+
```azurecli-interactive
161+
az aks show --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER --query "autoUpgradeProfile"
162+
```
163+
164+
Results:
165+
166+
<!-- expected_similarity=0.3 -->
167+
```JSON
168+
{
169+
"nodeOsUpgradeChannel": "SecurityPatch"
170+
}
171+
```
172+
173+
### How can I monitor the status of node OS autoupgrades?
174+
175+
To view the status of your node OS auto upgrades, look up [activity logs][monitor-aks] on your cluster. You can also look up specific upgrade-related events as mentioned in [Upgrade an AKS cluster][aks-upgrade]. AKS also emits upgrade-related Event Grid events. To learn more, see [AKS as an Event Grid source][aks-eventgrid].
176+
177+
### Can I change the node OS autoupgrade channel value if my cluster autoupgrade channel is set to `node-image`?
178+
179+
No. Currently, when you set the [cluster autoupgrade channel][Autoupgrade] to `node-image`, it also automatically sets the node OS autoupgrade channel to `NodeImage`. You can't change the node OS autoupgrade channel value if your cluster autoupgrade channel is `node-image`. In order to be able to change the node OS autoupgrade channel values, make sure the [cluster autoupgrade channel][Autoupgrade] isn't `node-image`.
180+
181+
### Why is `SecurityPatch` recommended over `Unmanaged` channel?
182+
183+
On the `Unmanaged` channel, AKS has no control over how and when the security updates are delivered. With `SecurityPatch`, the security updates are fully tested and follow safe deployment practices. `SecurityPatch` also honors maintenance windows. For more details, see [Increased security and resiliency of Canonical workloads on Azure][Blog].
184+
185+
### Does `SecurityPatch` always lead to a reimage of my nodes?
186+
187+
AKS limits reimages to only when absolutely necessary, such as certain kernel packages that may require a reimage to get fully applied. `SecurityPatch` is designed to minimize disruptions as much as possible. If AKS decides reimaging nodes isn't necessary, it will patch nodes live without draining pods and no VHD update is performed in such cases.
188+
189+
### Why does `SecurityPatch` channel requires to reach `snapshot.ubuntu.com` endpoint?
190+
191+
With the `SecurityPatch` channel, the Linux cluster nodes have to download the required security patches and updates from ubuntu snapshot service described in [ubuntu-snapshots-on-azure-ensuring-predictability-and-consistency-in-cloud-deployments](https://ubuntu.com/blog/ubuntu-snapshots-on-azure-ensuring-predictability-and-consistency-in-cloud-deployments).
192+
193+
### How do I know if a `SecurityPatch` or `NodeImage` upgrade is applied on my node?
194+
195+
Run the `kubectl get nodes --show-labels` command to list the nodes in your cluster and their labels
196+
197+
Among the returned labels, you should see a line similar to the following output:
198+
199+
```output
200+
kubernetes.azure.com/node-image-version=AKSUbuntu-2204gen2containerd-202410.27.0-2024.12.01
201+
```
202+
203+
Here, the base node image version is `AKSUbuntu-2204gen2containerd-202410.27.0`. If applicable, the security patch version typically follows. In the above example, it's `2024.12.01`.
204+
205+
The same details also be looked up in the Azure portal under the node label view:
206+
207+
:::image type="content" source="./media/auto-upgrade-node-os-image/nodeimage-securitypatch-inline.png" alt-text="A screenshot of the nodes page for an AKS cluster in the Azure portal. The label for node image version clearly shows the base node image and the latest applied security patch date." lightbox="./media/auto-upgrade-node-os-image/nodeimage-securitypatch.png":::
208+
209+
## Next steps
210+
211+
For a detailed discussion of upgrade best practices and other considerations, see [AKS patch and upgrade guidance][upgrade-operators-guide].
212+
213+
<!-- LINKS -->
214+
[planned-maintenance]: planned-maintenance.md
215+
[release-tracker]: release-tracker.md
216+
[az-provider-register]: /cli/azure/provider#az-provider-register
217+
[az-feature-register]: /cli/azure/feature#az-feature-register
218+
[az-feature-show]: /cli/azure/feature#az-feature-show
219+
[upgrade-aks-cluster]: upgrade-cluster.md
220+
[unattended-upgrades]: https://help.ubuntu.com/community/AutomaticSecurityUpdates
221+
[Autoupgrade]: auto-upgrade-cluster.md
222+
[kured]: node-updates-kured.md
223+
[supported]: ./support-policies.md
224+
[monitor-aks]: ./monitor-aks-reference.md
225+
[aks-eventgrid]: ./quickstart-event-grid.md
226+
[aks-upgrade]: ./upgrade-cluster.md
227+
[upgrade-operators-guide]: /azure/architecture/operator-guides/aks/aks-upgrade-practices
228+
[az-aks-create]: /cli/azure/aks#az-aks-create
229+
[az-aks-update]: /cli/azure/aks#az-aks-update
230+
231+
<!-- LINKS - external -->
232+
[Blog]: https://techcommunity.microsoft.com/t5/linux-and-open-source-blog/increased-security-and-resiliency-of-canonical-workloads-on/ba-p/3970623

0 commit comments

Comments
 (0)