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/upgrade-cluster.md
+60-61Lines changed: 60 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,12 +10,14 @@ ms.date: 04/21/2023
10
10
11
11
Part of the AKS cluster lifecycle involves performing periodic upgrades to the latest Kubernetes version. It’s important you apply the latest security releases, or upgrade to get the latest features. This article shows you how to check for, configure, and apply upgrades to your AKS cluster.
12
12
13
+
For AKS clusters that use multiple node pools or Windows Server nodes, see [Upgrade a node pool in AKS][nodepool-upgrade]. To upgrade a specific node pool without doing a Kubernetes cluster upgrade, see [Upgrade a specific node pool][specific-nodepool].
14
+
15
+
## Kubernetes version upgrades
16
+
13
17
When you upgrade a supported AKS cluster, Kubernetes minor versions can't be skipped. You must perform all upgrades sequentially by major version number. For example, upgrades between *1.14.x* -> *1.15.x* or *1.15.x* -> *1.16.x* are allowed, however *1.14.x* -> *1.16.x* isn't allowed.
14
18
15
19
Skipping multiple versions can only be done when upgrading from an *unsupported version* back to a *supported version*. For example, an upgrade from an unsupported *1.10.x* -> a supported *1.15.x* can be completed if available. When performing an upgrade from an *unsupported version* that skips two or more minor versions, the upgrade is performed without any guarantee of functionality and is excluded from the service-level agreements and limited warranty. If your version is significantly out of date, we recommend you recreate your cluster.
16
20
17
-
For AKS clusters that use multiple node pools or Windows Server nodes, see [Upgrade a node pool in AKS][nodepool-upgrade]. To upgrade a specific node pool without doing a Kubernetes cluster upgrade, see [Upgrade a specific node pool][specific-nodepool].
18
-
19
21
> [!NOTE]
20
22
> Any upgrade operation, whether performed manually or automatically, will upgrade the node image version if not already on the latest. The latest version is contingent on a full AKS release and can be determined by visiting the [AKS release tracker][release-tracker].
21
23
@@ -32,38 +34,38 @@ For AKS clusters that use multiple node pools or Windows Server nodes, see [Upgr
32
34
33
35
### [Azure CLI](#tab/azure-cli)
34
36
35
-
*Check which Kubernetes releases are available for your cluster using the [`az aks get-upgrades`][az-aks-get-upgrades] command.
37
+
Check which Kubernetes releases are available for your cluster using the [`az aks get-upgrades`][az-aks-get-upgrades] command.
36
38
37
-
```azurecli-interactive
38
-
az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster --output table
39
-
```
39
+
```azurecli-interactive
40
+
az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster --output table
41
+
```
40
42
41
-
The following example output shows that the cluster can be upgraded to versions *1.19.1* and *1.19.3*:
43
+
The following example output shows that the cluster can be upgraded to versions *1.19.1* and *1.19.3*:
@@ -85,31 +87,31 @@ The Azure portal highlights all the deprecated APIs between your current version
85
87
86
88
### [Azure CLI](#tab/azure-cli)
87
89
88
-
* The following example output means the `appservice-kube` extension isn't compatible with your Azure CLI version (a minimum of version 2.34.1 is required):
90
+
The following example output means the `appservice-kube` extension isn't compatible with your Azure CLI version (a minimum of version 2.34.1 is required):
89
91
90
-
```output
91
-
The 'appservice-kube' extension is not compatible with this version of the CLI.
92
-
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
93
-
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.
94
-
```
92
+
```output
93
+
The 'appservice-kube' extension is not compatible with this version of the CLI.
94
+
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
95
+
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.
96
+
```
95
97
96
-
If you receive this output, you need to update your Azure CLI version. The `az upgrade` command was added in version 2.11.0 and doesn't work with versions prior to 2.11.0. You can update older versions by reinstalling Azure CLI as described in [Install the Azure CLI](/cli/azure/install-azure-cli). If your Azure CLI version is 2.11.0 or later, you receive a message to run `az upgrade` to upgrade Azure CLI to the latest version.
98
+
If you receive this output, you need to update your Azure CLI version. The `az upgrade` command was added in version 2.11.0 and doesn't work with versions prior to 2.11.0. You can update older versions by reinstalling Azure CLI as described in [Install the Azure CLI](/cli/azure/install-azure-cli). If your Azure CLI version is 2.11.0 or later, you receive a message to run `az upgrade` to upgrade Azure CLI to the latest version.
97
99
98
-
* If your Azure CLI is updated and you receive the following example output, it means that no upgrades are available:
100
+
If your Azure CLI is updated and you receive the following example output, it means that no upgrades are available:
99
101
100
-
```output
101
-
ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.
102
-
```
102
+
```output
103
+
ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.
104
+
```
103
105
104
-
If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when `az aks get-upgrades` shows that no upgrades are available.
106
+
If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when `az aks get-upgrades` shows that no upgrades are available.
105
107
106
108
### [Azure PowerShell](#tab/azure-powershell)
107
109
108
-
* If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when `Get-AzAksUpgradeProfile` shows that no upgrades are available.
110
+
If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when `Get-AzAksUpgradeProfile` shows that no upgrades are available.
109
111
110
112
### [Azure portal](#tab/azure-portal)
111
113
112
-
* If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when no upgrades are available.
114
+
If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when no upgrades are available.
113
115
114
116
---
115
117
@@ -126,7 +128,7 @@ During the cluster upgrade process, AKS performs the following operations:
126
128
[!INCLUDE [alias minor version callout](./includes/aliasminorversion/alias-minor-version-upgrade.md)]
127
129
128
130
> [!IMPORTANT]
129
-
> Ensure that any `PodDisruptionBudgets` (PDBs) allow for at least 1 pod replica to be moved at a time otherwise the drain/evict operation will fail.
131
+
> Ensure that any `PodDisruptionBudgets` (PDBs) allow for at least *one* pod replica to be moved at a time otherwise the drain/evict operation will fail.
130
132
> If the drain operation fails, the upgrade operation will fail by design to ensure that the applications are not disrupted. Please correct what caused the operation to stop (incorrect PDBs, lack of quota, and so on) and re-try the operation.
131
133
132
134
### [Azure CLI](#tab/azure-cli)
@@ -255,38 +257,35 @@ After receiving the error message, you have two options to mitigate the issue. Y
255
257
256
258
:::image type="content" source="./media/upgrade-cluster/applens-api-detection-inline.png" lightbox="./media/upgrade-cluster/applens-api-detection-full.png" alt-text="A screenshot of the Azure portal showing the 'Selected Kubernetes API deprecations' section.":::
257
259
258
-
You can also check past API usage by enabling [container insights][container-insights] and exploring kube audit logs.
259
-
260
260
3. Wait 12 hours from the time the last deprecated API usage was seen.
261
261
262
262
4. Retry your cluster upgrade.
263
263
264
+
You can also check past API usage by enabling [Container Insights][container-insights] and exploring kube audit logs.
265
+
264
266
### Bypass validation to ignore API changes
265
267
266
268
> [!NOTE]
267
269
> This method requires you to use the `aks-preview` Azure CLI extension version 0.5.134 or later. This method isn't recommended, as deprecated APIs in the targeted Kubernetes version may not work long term. We recommend to removing them as soon as possible after the upgrade completes.
268
270
269
-
* Bypass validation to ignore API breaking changes using the [`az aks update`][az-aks-update] command and setting the `upgrade-settings` property to `IgnoreKubernetesDeprecations`.
270
-
271
-
```azurecli-interactive
272
-
az aks update --name myAKSCluster --resource-group myResourceGroup --upgrade-settings IgnoreKubernetesDeprecations --upgrade-override-until 2023-04-01T13:00:00Z
273
-
```
274
-
275
-
The `upgrade-override-until` property is used to define the end of the window during which validation will be bypassed. If no value is set, it defaults the window to three days from the current time. The date and time you specify must be in the future.
271
+
Bypass validation to ignore API breaking changes using the [`az aks update`][az-aks-update] command and setting the `upgrade-settings` property to `IgnoreKubernetesDeprecations` and setting the `upgrade-override-until` property to define the end of the window during which validation is bypassed. If no value is set, it defaults the window to three days from the current time. The date and time you specify must be in the future.
276
272
277
-
`Z` is the zone designator for the zero UTC/GMT offset, also known as 'Zulu' time. This example sets the end of the window to `13:00:00` GMT. For more information, see [Combined date and time representations](https://wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
273
+
```azurecli-interactive
274
+
az aks update --name myAKSCluster --resource-group myResourceGroup --upgrade-settings IgnoreKubernetesDeprecations --upgrade-override-until 2023-04-01T13:00:00Z
275
+
```
278
276
279
-
After a successful override, performing an upgrade operation will ignore any deprecated API usage for the targeted version.
277
+
> [!NOTE]
278
+
> `Z` is the zone designator for the zero UTC/GMT offset, also known as 'Zulu' time. This example sets the end of the window to `13:00:00` GMT. For more information, see [Combined date and time representations](https://wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
280
279
281
280
## Customize node surge upgrade
282
281
283
282
> [!IMPORTANT]
284
283
>
285
-
> * Node surges require subscription quota for the requested max surge count for each upgrade operation. For example, a cluster that has five node pools, each with a count of four nodes, has a total of 20 nodes. If each node pool has a max surge value of 50%, additional compute and IP quota of 10 nodes (2 nodes * 5 pools) is required to complete the upgrade.
284
+
> Node surges require subscription quota for the requested max surge count for each upgrade operation. For example, a cluster that has five node pools, each with a count of four nodes, has a total of 20 nodes. If each node pool has a max surge value of 50%, additional compute and IP quota of 10 nodes (2 nodes * 5 pools) is required to complete the upgrade.
286
285
>
287
-
> * If using Azure CNI, validate there are available IPs in the subnet to [satisfy IP requirements of Azure CNI](configure-azure-cni.md).
286
+
> The max surge setting on a node pool is persistent. Subsequent Kubernetes upgrades or node version upgrades will use this setting. You may change the max surge value for your node pools at any time. For production node pools, we recommend a max-surge setting of 33%.
288
287
>
289
-
> * The max surge setting on a node pool is persistent. Subsequent Kubernetes upgrades or node version upgrades will use this setting. You may change the max surge value for your node pools at any time. For production node pools, we recommend a max-surge setting of 33%.
288
+
> If you're using Azure CNI, validate there are available IPs in the subnet to [satisfy IP requirements of Azure CNI](configure-azure-cni.md).
290
289
291
290
By default, AKS configures upgrades to surge with one extra node. A default value of one for the max surge settings enables AKS to minimize workload disruption by creating an extra node before the cordon/drain of existing applications to replace an older versioned node. The max surge value can be customized per node pool to enable a trade-off between upgrade speed and upgrade disruption. When you increase the max surge value, the upgrade process completes faster. If you set a large value for max surge, you might experience disruptions during the upgrade process.
292
291
@@ -298,15 +297,15 @@ During an upgrade, the max surge value can be a minimum of *1* and a maximum val
298
297
299
298
### Set max surge values
300
299
301
-
* Set max surge values for new or existing node pools using the following commands:
300
+
Set max surge values for new or existing node pools using the following commands:
302
301
303
-
```azurecli-interactive
304
-
# Set max surge for a new node pool
305
-
az aks nodepool add -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%
302
+
```azurecli-interactive
303
+
# Set max surge for a new node pool
304
+
az aks nodepool add -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%
306
305
307
-
# Update max surge for an existing node pool
308
-
az aks nodepool update -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 5
309
-
```
306
+
# Update max surge for an existing node pool
307
+
az aks nodepool update -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 5
0 commit comments