Merge pull request #218309 from Nickomang/aks-upgrade-changes

Upgrade overview article

Author: v-stsavell

articles/aks/TOC.yml

@@ -178,6 +178,8 @@
   items:
     - name: Cluster operations
       items:
+        - name: Maintaining and upgrading an AKS cluster
+          href: upgrade.md
         - name: Abort long running operations
           href: manage-abort-operations.md
         - name: Automatically upgrade an AKS cluster

articles/aks/auto-upgrade-cluster.md

@@ -14,13 +14,18 @@ Part of the AKS cluster lifecycle involves performing periodic upgrades to the l
 
 > [!NOTE]
 > 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].
+>
+> Auto-upgrade will first upgrade the control plane, and then proceed to upgrade agent pools one by one.
 
 ## Why use auto-upgrade
 
 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.
 
 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 [Supported Kubernetes versions][supported-kubernetes-versions].
 
+
+Even if using node image auto upgrade (which won't change the Kubernetes version), it still requires MC to be in a supported version
+
 ## Using auto-upgrade
 
 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.
@@ -38,6 +43,9 @@ The following upgrade channels are available:
 > [!NOTE]
 > Cluster auto-upgrade only updates to GA versions of Kubernetes and will not update to preview versions.
 
+> [!NOTE]
+> 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.
+
 Automatically upgrading a cluster follows the same process as manually upgrading a cluster. For more information, see [Upgrade an AKS cluster][upgrade-aks-cluster].
 
 To set the auto-upgrade channel when creating a cluster, use the *auto-upgrade-channel* parameter, similar to the following example.

articles/aks/upgrade.md

@@ -0,0 +1,66 @@
+---
+title: Overview of upgrading Azure Kubernetes Service (AKS) clusters and components
+description: Learn about the various upgradeable components of an Azure Kubernetes Service (AKS) cluster and how to maintain them.
+author: nickomang
+ms.author: nickoman
+ms.service: container-service
+ms.topic: conceptual
+ms.date: 11/11/2022
+---
+
+# Upgrading Azure Kubernetes Service clusters and node pools
+
+An Azure Kubernetes Service (AKS) cluster will periodically need to be updated to ensure security and compatibility with the latest features. There are two components of an AKS cluster that are necessary to maintain:
+
+- *Cluster Kubernetes version*: Part of the AKS cluster lifecycle involves performing upgrades to the latest Kubernetes version. It’s important you upgrade to apply the latest security releases and to get access to the latest Kubernetes features, as well as to stay within the [AKS support window][supported-k8s-versions].
+- *Node image version*: AKS regularly provides new node images with the latest OS and runtime updates. It's beneficial to upgrade your nodes' images regularly to ensure support for the latest AKS features and to apply essential security patches and hot fixes.
+
+The following table summarizes the details of updating each component:
+
+|Component name|Frequency of upgrade|Planned Maintenance supported|Supported operation methods|Documentation link|
+|--|--|--|--|--|
+|Cluster Kubernetes version (minor) upgrade|Roughly every three months|Yes| Automatic, Manual|[Upgrade an AKS cluster][upgrade-cluster]|
+|Cluster Kubernetes version upgrade to supported patch version|Approximately weekly. To determine the latest applicable version in your region, see the [AKS release tracker][release-tracker]|Yes|Automatic, Manual|[Upgrade an AKS cluster][upgrade-cluster]|
+|Node image version upgrade|**Linux**: weekly<br>**Windows**: monthly|Yes|Automatic, Manual|[AKS node image upgrade][node-image-upgrade]|
+|Security patches and hot fixes for node images|As-necessary||||
+
+## Automatic upgrades
+
+Automatic upgrades can be performed through [auto upgrade channels][auto-upgrade] or via [GitHub Actions][gh-actions-upgrade].
+
+## Planned maintenance
+
+ [Planned maintenance][planned-maintenance] allows you to schedule weekly maintenance windows that will update your control plane as well as your kube-system pods, helping to minimize workload impact.
+
+## Troubleshooting
+
+To find details and solutions to specific issues, view the following troubleshooting guides:
+
+- [Upgrade fails because of NSG rules][ts-nsg]
+
+- [PodDrainFailure error][ts-pod-drain]
+
+- [PublicIPCountLimitReached error][ts-ip-limit]
+
+- [QuotaExceeded error][ts-quota-exceeded]
+
+- [SubnetIsFull error][ts-subnet-full]
+
+## Next steps
+
+For more information what cluster operations may trigger specific upgrade events, see the [AKS operator's guide on patching][operator-guide-patching].
+
+<!-- LINKS -->
+[auto-upgrade]: ./auto-upgrade-cluster.md
+[planned-maintenance]: ./planned-maintenance.md
+[upgrade-cluster]: ./upgrade-cluster.md
+[release-tracker]: ./release-tracker.md
+[node-image-upgrade]: ./node-image-upgrade.md
+[gh-actions-upgrade]: ./node-upgrade-github-actions.md 
+[operator-guide-patching]: /azure/architecture/operator-guides/aks/aks-upgrade-practices.md#considerations
+[supported-k8s-versions]: ./supported-kubernetes-versions.md#kubernetes-version-support-policy
+[ts-nsg]: /troubleshoot/azure/azure-kubernetes/upgrade-fails-because-of-nsg-rules
+[ts-pod-drain]: /troubleshoot/azure/azure-kubernetes/error-code-poddrainfailure
+[ts-ip-limit]: /troubleshoot/azure/azure-kubernetes/error-code-publicipcountlimitreached
+[ts-quota-exceeded]: /troubleshoot/azure/azure-kubernetes/error-code-quotaexceeded
+[ts-subnet-full]: /troubleshoot/azure/azure-kubernetes/error-code-subnetisfull-upgrade