Merge pull request #227010 from Nickomang/aks-upgrade

AKS upgrade experience updates

Author: American-Dipper

articles/aks/TOC.yml

@@ -200,7 +200,7 @@
           href: scale-down-mode.md
         - name: Stop an AKS cluster
           href: start-stop-cluster.md
-        - name: Use planned maintenance (preview)
+        - name: Use planned maintenance to schedule and control upgrades (preview)
           href: planned-maintenance.md
         - name: Planned Maintenance for AKS weekly releases (preview)
           href: aks-planned-maintenance-weekly-releases.md

articles/aks/aks-planned-maintenance-weekly-releases.md

@@ -14,6 +14,8 @@ author: kaarthis
 
  Planned Maintenance allows you to schedule weekly maintenance windows that will ensure the weekly releases [releases] are controlled. Maintenance Windows are configured using the Azure CLI, allowing you to select from a set of pre-available configurations.
 
+Weekly releases can also be scheduled with more fine-grained control using Planned Maintenance's `default` configuration type. For more information, see [Planned Maintenance to schedule and control upgrades][planned-maintenance].
+
 ## Before you begin
 
 This article assumes that you have an existing AKS cluster. If you need an AKS cluster, see the AKS quickstart [using the Azure CLI][aks-quickstart-cli], [using Azure PowerShell][aks-quickstart-powershell], or [using the Azure portal][aks-quickstart-portal].
@@ -106,4 +108,5 @@ az maintenance assignment delete --name assignmentName --provider-name "Microsof
 [az-aks-install-cli]: /cli/azure/aks#az_aks_install_cli
 [az-provider-register]: /cli/azure/provider#az_provider_register
 [aks-upgrade]: upgrade-cluster.md
-[releases]:release-tracker.md
+[releases]:release-tracker.md
+[planned-maintenance]: ./planned-maintenance.md

articles/aks/auto-upgrade-cluster.md

@@ -60,6 +60,14 @@ To set the auto-upgrade channel on existing cluster, update the *auto-upgrade-ch
 az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable
 ```
 
+## Auto-upgrade in the Azure portal
+
+If you're using the Azure portal, you can find auto-upgrade settings under the *Settings* > *Cluster configuration* blade by selecting *Upgrade version*. By default, the `Patch` channel is selected.
+
+:::image type="content" source="./media/auto-upgrade-cluster/portal-upgrade.png" alt-text="The screenshot of the upgrade blade for an AKS cluster in the Azure portal. The automatic upgrade field shows 'patch' selected, and several APIs deprecated between the selected Kubernetes version and the cluster's current version are described.":::
+
+The Azure portal also highlights all the deprecated APIs between your current version and newer, available versions you intend to migrate to. For more information, see [the Kubernetes API Removal and Deprecation process][k8s-deprecation].
+
 ## Using auto-upgrade with Planned Maintenance
 
 If you’re using Planned Maintenance and Auto-Upgrade, your upgrade will start during your specified maintenance window. 
@@ -92,3 +100,4 @@ The following best practices will help maximize your success when using auto-upg
 <!-- EXTERNAL LINKS -->
 [pdb-best-practices]: https://kubernetes.io/docs/tasks/run-application/configure-pdb/
 [release-tracker]: release-tracker.md
+[k8s-deprecation]: https://kubernetes.io/blog/2022/11/18/upcoming-changes-in-kubernetes-1-26/#:~:text=A%20deprecated%20API%20is%20one%20that%20has%20been,point%20you%20must%20migrate%20to%20using%20the%20replacement

articles/aks/media/auto-upgrade-cluster/portal-upgrade.png

@@ -1,17 +1,25 @@
 ---
-title: Use Planned Maintenance for your Azure Kubernetes Service (AKS) cluster (preview)
+title: Use Planned Maintenance to schedule and control upgrades for your Azure Kubernetes Service (AKS) cluster (preview)
 titleSuffix: Azure Kubernetes Service
-description: Learn how to use Planned Maintenance in Azure Kubernetes Service (AKS).
+description: Learn how to use Planned Maintenance to schedule and control cluster and node image upgrades in Azure Kubernetes Service (AKS).
 services: container-service
 ms.topic: article
 ms.date: 01/17/2023
 ms.author: qpetraroia
 author: qpetraroia
 ---
 
-# Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster (preview)
+# Use Planned Maintenance to schedule and control upgrades for your Azure Kubernetes Service (AKS) cluster (preview)
 
-Your AKS cluster has regular maintenance performed on it automatically. By default, this work can happen at any time. Planned Maintenance allows you to schedule weekly maintenance windows to perform updates and minimize workload impact. Once scheduled, maintenance will occur only during the window you selected.
+Your AKS cluster has regular maintenance performed on it automatically. By default, this work can happen at any time. Planned Maintenance allows you to schedule weekly maintenance windows to perform updates and minimize workload impact. Once scheduled, upgrades occur only during the window you selected.
+
+There are currently two available configuration types: `default` and `aksManagedAutoUpgradeSchedule`:
+
+- `default` corresponds to a basic configuration that updates your control plane and your kube-system pods on a Virtual Machine Scale Sets instance. It is a legacy configuration that is mostly suitable for basic scheduling of [weekly releases][release-tracker]. Another way of accomplishing this behavior, using pre-configured windows, is detailed at [use Planned Maintenance to schedule weekly releases][pm-weekly]
+
+- `aksManagedAutoUpgradeSchedule` is a more complex configuration that controls when upgrades scheduled by your designated auto-upgrade channel are performed. More finely controlled cadence and recurrence settings are possible. For more information on cluster auto-upgrade, see [Automatically an Azure Kubernetes Service (AKS) cluster][aks-upgrade].
+
+We recommend using `aksManagedAutoUpgradeSchedule` for all maintenance and upgrade scenarios, while `default` is meant exclusively for weekly releases. You can port `default` configurations to `aksManagedAutoUpgradeSchedule` configurations via the `az aks maintenanceconfiguration update` command.
 
 ## Before you begin
 
@@ -39,25 +47,13 @@ az extension add --name aks-preview
 az extension update --name aks-preview
 ```
 
-## Understanding maintenance window configuration types
-
-There are currently two available configuration types: `default` and `aksManagedAutoUpgradeSchedule`:
-
-- `default` corresponds to a basic configuration that will update your control plane and your kube-system pods on a virtual machine scale sets instance. It is a legacy configuration that is mostly suitable for basic scheduling of [weekly releases][release-tracker].
-
-- `aksManagedAutoUpgradeSchedule` is a more complex configuration that controls when upgrades scheduled by your designated auto-upgrade channel are performed. More finely controlled cadence and recurrence settings are possible. For more information on cluster auto-upgrade, see [Automatically an Azure Kubernetes Service (AKS) cluster][aks-upgrade].
-
-### Choosing between configuration types
+## Creating a maintenance window
 
-We recommend using `aksManagedAutoUpgradeSchedule` for all maintenance and upgrade scenarios, while `default` is meant exclusively for weekly releases. You can port `default` configurations to `aksManagedAutoUpgradeSchedule` configurations via the `az aks maintenanceconfiguration update` command.
+To create a maintenance window, you can use the `az aks maintenanceconfiguration add` command using the  `--name` value `default` or `aksManagedAutoUpgradeSchedule`. The name value should reflect the desired configuration type. Using any other name will cause your maintenance window not to run.
 
 > [!NOTE]
 > When using auto-upgrade, to ensure proper functionality, use a maintenance window with a duration of four hours or more.
 
-## Creating a maintenance window
-
-To create a maintenance window, you can use the `az aks maintenanceconfiguration add` command using the  `--name` value `default` or `aksManagedAutoUpgradeSchedule`. The name value should reflect the desired configuration type. Using any other name will cause your maintenance window not to run.
-
 Planned Maintenance windows are specified in Coordinated Universal Time (UTC).
 
 A `default` maintenance window has the following properties:
@@ -74,7 +70,7 @@ An `aksManagedAutoUpgradeSchedule` has the following properties:
 |Name|Description|Default value|
 |--|--|--|
 |`utcOffset`|Used to determine the timezone for cluster maintenance|`+00:00`|
-|`startDate`|The date on which the maintenance window will begin to take effect|The current date at creation time|
+|`startDate`|The date on which the maintenance window begins to take effect|The current date at creation time|
 |`startTime`|The time for maintenance to begin, based on the timezone determined by `utcOffset`|N/A|
 |`schedule`|Used to determine frequency. Three types are available: `Weekly`, `AbsoluteMonthly`, and `RelativeMonthly`|N/A|
 |`intervalWeeks`|The interval in weeks for maintenance runs|N/A|
@@ -306,3 +302,4 @@ az aks maintenanceconfiguration delete -g MyResourceGroup --cluster-name myAKSCl
 [aks-upgrade]: upgrade-cluster.md
 [release-tracker]: release-tracker.md
 [auto-upgrade]: auto-upgrade-cluster.md
+[pm-weekly]: ./aks-planned-maintenance-weekly-releases.md

articles/aks/media/upgrade-cluster/portal-upgrade.png

@@ -111,6 +111,10 @@ To check which Kubernetes releases are available for your cluster:
 
 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.
 
+The Azure portal also highlights all the deprecated APIs between your current version and newer, available versions you intend to migrate to. For more information, see [the Kubernetes API Removal and Deprecation process][k8s-deprecation].
+
+:::image type="content" source="./media/upgrade-cluster/portal-upgrade.png" alt-text="The screenshot of the upgrade blade for an AKS cluster in the Azure portal. The automatic upgrade field shows 'patch' selected, and several APIs deprecated between the selected Kubernetes version and the cluster's current version are described.":::
+
 ---
 
 ## Customize node surge upgrade
@@ -231,6 +235,10 @@ You can also manually upgrade your cluster in the Azure portal.
 4. In **Kubernetes version**, select **Upgrade version**. This will redirect you to a new page.
 5. In **Kubernetes version**, select your desired version and then select **Save**.
 
+The Azure portal also highlights all the deprecated APIs between your current version and newer, available versions you intend to migrate to. For more information, see [the Kubernetes API Removal and Deprecation process][k8s-deprecation].
+
+:::image type="content" source="./media/upgrade-cluster/portal-upgrade.png" alt-text="The screenshot of the upgrade blade for an AKS cluster in the Azure portal. The automatic upgrade field shows 'patch' selected, and several APIs deprecated between the selected Kubernetes version and the cluster's current version are described.":::
+
 It takes a few minutes to upgrade the cluster, depending on how many nodes you have.
 
 To confirm that the upgrade was successful, navigate to your AKS cluster in the Azure portal. On the **Overview** page, select the **Kubernetes version**.
@@ -268,7 +276,7 @@ In addition to manually upgrading a cluster, you can set an auto-upgrade channel
 
 ## Special considerations for node pools that span multiple Availability Zones
 
-AKS uses best-effort zone balancing in node groups. During an Upgrade surge, zone(s) for the surge node(s) in virtual machine scale sets is unknown ahead of time. This can temporarily cause an unbalanced zone configuration during an upgrade. However, AKS deletes the surge node(s) once the upgrade has been completed and preserves the original zone balance. If you desire to keep your zones balanced during upgrade, increase the surge to a multiple of three nodes. Virtual machine scale sets will then balance your nodes across Availability Zones with best-effort zone balancing.
+AKS uses best-effort zone balancing in node groups. During an Upgrade surge, zone(s) for the surge node(s) in Virtual Machine Scale Sets is unknown ahead of time. This can temporarily cause an unbalanced zone configuration during an upgrade. However, AKS deletes the surge node(s) once the upgrade has been completed and preserves the original zone balance. If you desire to keep your zones balanced during upgrade, increase the surge to a multiple of three nodes. Virtual Machine Scale Sets will then balance your nodes across Availability Zones with best-effort zone balancing.
 
 If you have PVCs backed by Azure LRS Disks, they’ll be bound to a particular zone, and they may fail to recover immediately if the surge node doesn’t match the zone of the PVC. This could cause downtime on your application when the Upgrade operation continues to drain nodes but the PVs are bound to a zone. To handle this case and maintain high availability, configure a [Pod Disruption Budget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) on your application. This allows Kubernetes to respect your availability requirements during Upgrade's drain operation.
 
@@ -303,3 +311,4 @@ This article showed you how to upgrade an existing AKS cluster. To learn more ab
 [aks-auto-upgrade]: auto-upgrade-cluster.md
 [release-tracker]: release-tracker.md
 [specific-nodepool]: node-image-upgrade.md#upgrade-a-specific-node-pool
+[k8s-deprecation]: https://kubernetes.io/blog/2022/11/18/upcoming-changes-in-kubernetes-1-26/#:~:text=A%20deprecated%20API%20is%20one%20that%20has%20been,point%20you%20must%20migrate%20to%20using%20the%20replacement