You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/aks/auto-upgrade-cluster.md
+12-11Lines changed: 12 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,16 +17,17 @@ Part of the AKS cluster lifecycle involves performing periodic upgrades to the l
17
17
>
18
18
> Auto-upgrade will first upgrade the control plane, and then proceed to upgrade agent pools one by one.
19
19
20
-
## Why use auto-upgrade
20
+
## Why use cluster auto-upgrade
21
21
22
-
Auto-upgrade provides a set once and forget mechanism that yields tangible time and operational cost benefits. By enabling auto-upgrade, you can ensure your clusters are up to date and don't miss the latest AKS features or patches from AKS and upstream Kubernetes.
22
+
Cluster auto-upgrade provides a set once and forget mechanism that yields tangible time and operational cost benefits. By enabling auto-upgrade, you can ensure your clusters are up to date and don't miss the latest AKS features or patches from AKS and upstream Kubernetes.
23
23
24
24
AKS follows a strict versioning window with regard to supportability. With properly selected auto-upgrade channels, you can avoid clusters falling into an unsupported version. For more on the AKS support window, see [Alias minor versions][supported-kubernetes-versions].
25
25
26
+
## Cluster auto-upgrade limitations
26
27
27
-
Even if using node image autoupgrade (which won't change the Kubernetes version), it still requires MC to be in a supported version
28
+
If you’re using cluster auto-upgrade, you can no longer upgrade the control plane first and then upgrade the individual node pools. Cluster auto-upgrade will always upgrade the control plane and the node pools together. There is no ability of upgrading the control plane only, and trying to run the command `az aks upgrade --control-plane-only` will raise the error: `NotAllAgentPoolOrchestratorVersionSpecifiedAndUnchanged: Using managed cluster api, all Agent pools' OrchestratorVersion must be all specified or all unspecified. If all specified, they must be stay unchanged or the same with control plane.`
28
29
29
-
## Using auto-upgrade
30
+
## Using cluster auto-upgrade
30
31
31
32
Automatically completed upgrades are functionally the same as manual upgrades. The timing of upgrades is determined by the selected channel. When making changes to auto-upgrade, allow 24 hours for the changes to take effect.
32
33
@@ -49,6 +50,9 @@ The following upgrade channels are available:
49
50
> [!NOTE]
50
51
> Auto-upgrade requires the cluster's Kubernetes version to be within the [AKS support window][supported-kubernetes-versions], even if using the `node-image` channel.
51
52
53
+
> [!NOTE]
54
+
> If using the preview API `11-02-preview` or later, if you select the `node-image` cluster auto-upgrade channel the [node image auto-upgrade channel][node-image-auto-upgrade] will automatically be set to `NodeImage`.
55
+
52
56
Automatically upgrading a cluster follows the same process as manually upgrading a cluster. For more information, see [Upgrade an AKS cluster][upgrade-aks-cluster].
53
57
54
58
To set the auto-upgrade channel when creating a cluster, use the *auto-upgrade-channel* parameter, similar to the following example.
@@ -73,23 +77,20 @@ The Azure portal also highlights all the deprecated APIs between your current ve
73
77
74
78
## Using auto-upgrade with Planned Maintenance
75
79
76
-
If you’re using Planned Maintenance and Auto-Upgrade, your upgrade will start during your specified maintenance window.
80
+
If you’re using Planned Maintenance and cluster auto-upgrade, your upgrade will start during your specified maintenance window.
77
81
78
82
> [!NOTE]
79
83
> To ensure proper functionality, use a maintenance window of four hours or more.
80
84
81
85
For more information on Planned Maintenance, see [Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster][planned-maintenance].
82
86
83
-
## Auto upgrade limitations
84
-
85
-
If you’re using Auto-Upgrade you cannot anymore upgrade the control plane first, and then upgrade the individual node pools. Auto-Upgrade will always upgrade the control plane and the node pools together. In Auto-Upgrade there is no concept of upgrading the control plane only, and trying to run the command `az aks upgrade --control-plane-only` will raise the error: `NotAllAgentPoolOrchestratorVersionSpecifiedAndUnchanged: Using managed cluster api, all Agent pools' OrchestratorVersion must be all specified or all unspecified. If all specified, they must be stay unchanged or the same with control plane.`
86
-
87
-
## Best practices for auto-upgrade
87
+
## Best practices for cluster auto-upgrade
88
88
89
89
The following best practices will help maximize your success when using auto-upgrade:
90
90
91
91
- In order to keep your cluster always in a supported version (i.e within the N-2 rule), choose either `stable` or `rapid` channels.
92
92
- If you're interested in getting the latest patches as soon as possible, use the `patch` channel. The `node-image` channel is a good fit if you want your agent pools to always be running the most recent node images.
93
+
- To automatically upgrade node images while using a different cluster upgrade channel, consider using the [node image auto-upgrade][node-image-auto-upgrade]`NodeImage` channel.
93
94
- Follow [Operator best practices][operator-best-practices-scheduler].
94
95
- Follow [PDB best practices][pdb-best-practices].
95
96
@@ -98,7 +99,7 @@ The following best practices will help maximize your success when using auto-upg
title: Automatically upgrade Azure Kubernetes Service (AKS) cluster node operating system images
3
+
description: Learn how to automatically upgrade Azure Kubernetes Service (AKS) cluster node operating system images.
4
+
services: container-service
5
+
ms.topic: article
6
+
ms.author: nickoman
7
+
author: nickomang
8
+
ms.date: 02/03/2023
9
+
---
10
+
11
+
# Automatically upgrade Azure Kubernetes Service cluster node operating system images
12
+
13
+
AKS supports upgrading the images on a node so your cluster is up to date with the newest operating system (OS) and runtime updates. AKS regularly provides new node OS images with the latest updates, so it's beneficial to upgrade your node's images regularly for the latest AKS features and to maintain security. Before learning about auto-upgrade, make sure you understand upgrade fundamentals by reading [Upgrade an AKS cluster][upgrade-aks-cluster].
14
+
15
+
The latest AKS node image information can be found by visiting the [AKS release tracker][release-tracker].
16
+
17
+
## Why use node OS auto-upgrade
18
+
19
+
Node OS auto-upgrade provides a set once and forget mechanism that yields tangible time and operational cost benefits. By enabling auto-upgrade, you can ensure your clusters are up to date and don't miss the latest AKS features or patches from AKS.
20
+
21
+
## Prerequisites
22
+
23
+
- Must be using API version `11-02-preview` or later
24
+
25
+
- If using Azure CLI, the `aks-preview` CLI extension version `0.5.127` or later must be installed
26
+
27
+
- If using the `SecurityPatch` channel, the `NodeOsUpgradeChannelPreview` feature flag must be enabled on your subscription
28
+
29
+
### Register the 'NodeOsUpgradeChannelPreview' feature flag
30
+
31
+
Register the `NodeOsUpgradeChannelPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:
32
+
33
+
```azurecli-interactive
34
+
az feature register --namespace "Microsoft.ContainerService" --name "NodeOsUpgradeChannelPreview"
35
+
```
36
+
37
+
It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature show][az-feature-show] command:
38
+
39
+
```azurecli-interactive
40
+
az feature show --namespace "Microsoft.ContainerService" --name "NodeOsUpgradeChannelPreview"
41
+
```
42
+
43
+
When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:
44
+
45
+
```azurecli-interactive
46
+
az provider register --namespace Microsoft.ContainerService
47
+
```
48
+
49
+
## Using node OS auto-upgrade
50
+
51
+
Automatically completed upgrades are functionally the same as manual upgrades. The timing of upgrades is determined by the selected channel. When making changes to auto-upgrade, allow 24 hours for the changes to take effect. By default, a cluster's node OS auto-upgrade channel is set to `Unmanaged`.
52
+
53
+
> [!NOTE]
54
+
> Node OS image auto-upgrade won't affect the cluster's Kubernetes version, but it still still requires the cluster to be in a supported version to function properly.
55
+
56
+
The following upgrade channels are available:
57
+
58
+
|Channel|Description|OS-specific behavior|
59
+
|---|---|
60
+
|`None`| Your nodes will not have security updates applied automatically. This means you are solely responsible for your security updates|N/A|
61
+
|`Unmanaged`|OS updates will be applied automatically through the OS built-in patching infrastructure. Newly allocated machines will be unpatched initially and will be patched at some point by the OS's infrastructure|Ubuntu applies security patches through unattended upgrade roughly once a day around 06:00 UTC. Windows and Mariner do not apply security patches automatically, so this option behaves equivalently to `None`|
62
+
|`SecurityPatch`|AKS will update the node's virtual hard disk (VHD) with patches from the image maintainer labeled "security only" on a regular basis. Where possible, patches will also be applied without disruption to existing nodes. Some patches, such as kernel patches, cannot be applied to existing nodes without disruption. For such patches, the VHD will be updated and existing machines will be upgraded to that VHD following maintenance windows and surge settings. This option incurs the extra cost of hosting the VHDs in your node resource group.|N/A|
63
+
|`NodeImage`|AKS will update 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.|
64
+
65
+
To set the node OS auto-upgrade channel when creating a cluster, use the *node-os-upgrade-channel* parameter, similar to the following example.
66
+
67
+
```azurecli-interactive
68
+
az aks create --resource-group myResourceGroup --name myAKSCluster --node-os-upgrade-channel SecurityPatch
69
+
```
70
+
71
+
To set the auto-upgrade channel on existing cluster, update the *node-os-upgrade-channel* parameter, similar to the following example.
72
+
73
+
```azurecli-interactive
74
+
az aks update --resource-group myResourceGroup --name myAKSCluster --node-os-upgrade-channel SecurityPatch
75
+
```
76
+
77
+
## Using node OS auto-upgrade with Planned Maintenance
78
+
79
+
If you’re using Planned Maintenance and node OS auto-upgrade, your upgrade will start during your specified maintenance window.
80
+
81
+
> [!NOTE]
82
+
> To ensure proper functionality, use a maintenance window of four hours or more.
83
+
84
+
For more information on Planned Maintenance, see [Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster][planned-maintenance].
0 commit comments