Merge pull request #248660 from kaarthis/maintenances

Team recommendations

Author: prmerger-automator[bot]

articles/aks/planned-maintenance.md

@@ -1,5 +1,6 @@
 ---
-title: Use Planned Maintenance to schedule and control upgrades for your Azure Kubernetes Service (AKS) cluster (preview)
+title: Use Planned Maintenance to schedule and control upgrades for your Azure Kubernetes Service (AKS) cluster 
+
 titleSuffix: Azure Kubernetes Service
 description: Learn how to use Planned Maintenance to schedule and control cluster and node image upgrades in Azure Kubernetes Service (AKS).
 ms.topic: article
@@ -9,53 +10,31 @@ ms.author: nickoman
 author: nickomang
 ---
 
-# Use Planned Maintenance to schedule and control upgrades for your Azure Kubernetes Service (AKS) cluster (preview)
+# Use Planned Maintenance to schedule and control upgrades for your Azure Kubernetes Service (AKS) cluster 
+
+Your AKS cluster has regular maintenance performed on it automatically. There are two types of regular maintenance - AKS initiated and those that you initiate. Planned Maintenance feature allows you to run both types of maintenance in a cadence of your choice thereby minimizing any workload impact. 
 
-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.
+AKS intiated maintenance refers to the AKS releases. These releases are weekly rounds of fixes and feature and component updates that affect your clusters. The type of maintenance that you initiate regularly are [cluster auto-upgrades][aks-upgrade] and [Node OS automatic security updates][node-image-auto-upgrade].
 
 There are currently three available configuration types: `default`, `aksManagedAutoUpgradeSchedule`, `aksManagedNodeOSUpgradeSchedule`:
 
-- `default` corresponds to a basic configuration that is mostly suitable for basic scheduling of [weekly releases][release-tracker].
+- `default` corresponds to a basic configuration that is used to control AKS releases, these releases can take up to two weeks to roll out to all regions from the initial time of shipping due to Azure Safe Deployment Practices (SDP). Choose `default` to schedule these updates in such a way that it's least disruptive for you. You can monitor the status of an ongoing AKS release by region from the [weekly releases tracker][release-tracker].  
 
 - `aksManagedAutoUpgradeSchedule` controls when cluster upgrades scheduled by your designated auto-upgrade channel are performed. More finely controlled cadence and recurrence settings are possible than in a `default` configuration. For more information on cluster auto-upgrade, see [Automatically upgrade an Azure Kubernetes Service (AKS) cluster][aks-upgrade].
 
-- `aksManagedNodeOSUpgradeSchedule` controls when node operating system upgrades scheduled by your node OS auto-upgrade channel are performed. More finely controlled cadence and recurrence settings are possible than in a `default configuration. For more information on node OS auto-upgrade, see [Automatically patch and update AKS cluster node images][node-image-auto-upgrade]
+- `aksManagedNodeOSUpgradeSchedule` controls when the node operating system security patching scheduled by your node OS auto-upgrade channel are performed. More finely controlled cadence and recurrence settings are possible than in a `default configuration. For more information on node OS auto-upgrade channel, see [Automatically patch and update AKS cluster node images][node-image-auto-upgrade]
 
-We recommend using `aksManagedAutoUpgradeSchedule` for all cluster upgrade scenarios and `aksManagedNodeOSUpgradeSchedule` for all node image 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 configure Planned Maintenance using pre-created configurations, see [Use Planned Maintenance pre-created configurations to schedule AKS weekly releases][pm-weekly].
+We recommend using `aksManagedAutoUpgradeSchedule` for all cluster upgrade scenarios and `aksManagedNodeOSUpgradeSchedule` for all node OS security patching scenarios, while `default` is meant exclusively for the AKS weekly releases. You can port `default` configurations to the `aksManagedAutoUpgradeSchedule` or `aksManagedNodeOSUpgradeSchedule` configurations via the `az aks maintenanceconfiguration update` command.
 
 ## 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].
 
 Be sure to upgrade Azure CLI to the latest version using [`az upgrade`](/cli/azure/update-azure-cli#manual-update).
 
-[!INCLUDE [preview features callout](./includes/preview/preview-callout.md)]
-
-### Limitations
-
-When you use Planned Maintenance, the following restrictions apply:
-
-- AKS reserves the right to break these windows for unplanned/reactive maintenance operations that are urgent or critical.
-- Currently, performing maintenance operations are considered *best-effort only* and aren't guaranteed to occur within a specified window.
-- Updates can't be blocked for more than seven days.
-
-### Install aks-preview CLI extension
-
-You also need the *aks-preview* Azure CLI extension version 0.5.124 or later. Install the *aks-preview* Azure CLI extension by using the [az extension add][az-extension-add] command. Or install any available updates by using the [az extension update][az-extension-update] command.
-
-```azurecli-interactive
-# Install the aks-preview extension
-az extension add --name aks-preview
-
-# Update the extension to make sure you have the latest version installed
-az extension update --name aks-preview
-```
-
 ## Creating a maintenance window
 
-To create a maintenance window, you can use the `az aks maintenanceconfiguration add` command using the  `--name` value `default`, `aksManagedAutoUpgradeSchedule`, or `aksManagedNodeOSUpgradeSchedule`. The name value should reflect the desired configuration type. Using any other name will cause your maintenance window not to run.
+To create a maintenance window, you can use the `az aks maintenanceconfiguration add` command using the  `--name` value `default`, `aksManagedAutoUpgradeSchedule`, or `aksManagedNodeOSUpgradeSchedule`. The name value should reflect the desired configuration type. Using any other name causes 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.
@@ -150,6 +129,13 @@ A `RelativeMonthly` schedule may look like *"every two months, on the last Monda
 
 Valid values for `weekIndex` are `First`, `Second`, `Third`, `Fourth`, and `Last`.
 
+### Things to note
+
+When you use Planned Maintenance, the following restrictions apply:
+
+-  AKS reserves the right to break these windows for unplanned, reactive maintenance operations that are urgent or critical. These maintenance operations may even run during the `notAllowedTime` or `notAllowedDates` periods defined in your configuration.
+- Performing maintenance operations are considered *best-effort only* and aren't guaranteed to occur within a specified window.
+
 ## Add a maintenance window configuration with Azure CLI
 
 The following example shows a command to add a new `default` configuration that schedules maintenance to run from 1:00am to 2:00am every Monday:
@@ -304,6 +290,27 @@ To delete a certain maintenance configuration window in your AKS Cluster, use th
 ```azurecli-interactive
 az aks maintenanceconfiguration delete -g myResourceGroup --cluster-name myAKSCluster --name autoUpgradeSchedule
 ```
+## Frequently Asked Questions
+
+* How can I check the existing maintenance configurations in my cluster?
+
+  Use the `az aks maintenanceconfiguration show` command.
+  
+* Can reactive, unplanned maintenance happen during the `notAllowedTime` or `notAllowedDates` periods too?
+
+  Yes, AKS reserves the right to break these windows for unplanned, reactive maintenance operations that are urgent or critical.
+
+* How can you tell if a maintenance event occurred?
+
+  For releases, check your cluster's region and look up release information in [weekly releases][release-tracker] and validate if it matches your maintenance schedule or not. To view the status of your auto upgrades, look up [activity logs][monitor-aks] on your cluster. You may 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].
+
+* Can you use more than one maintenance configuration at the same time?
+   
+  Yes, you can run all three configurations i.e `default`, `aksManagedAutoUpgradeSchedule`, `aksManagedNodeOSUpgradeSchedule`simultaneously.  In case the windows overlap AKS decides the running order. 
+
+*  Are there any best practices for the maintenance configurations?
+   
+  We recommend setting the Node OS security updates schedule[node-image-auto-upgrade] to a weekly cadence if you're using `NodeImage` channel since a new node image gets shipped every week and daily if you opt in for `SecurityPatch` channel to receive daily security updates. Set the auto-upgrade Schedule[auto-upgrade] to a monthly cadence to stay on top of the kubernetes N-2 [support policy][aks-support-policy]. 
 
 ## Next steps
 
@@ -326,3 +333,6 @@ az aks maintenanceconfiguration delete -g myResourceGroup --cluster-name myAKSCl
 [auto-upgrade]: auto-upgrade-cluster.md
 [node-image-auto-upgrade]: auto-upgrade-node-image.md
 [pm-weekly]: ./aks-planned-maintenance-weekly-releases.md
+[monitor-aks]: monitor-aks-reference.md
+[aks-eventgrid]:quickstart-event-grid.md
+[aks-support-policy]:support-policies.md