major updates to CLI doc

Author: pruphil

articles/virtual-machines/maintenance-configurations-cli.md

@@ -15,70 +15,98 @@ ms.author: cynthn
 
 **Applies to:** :heavy_check_mark: Linux VMs :heavy_check_mark: Windows VMs :heavy_check_mark: Flexible scale sets :heavy_check_mark: Uniform scale sets
 
-Maintenance Configurations lets you decide when to apply platform updates to various Azure resources. This topic covers the Azure CLI options for Dedicated Hosts and Isolated VMs. For more about benefits of using Maintenance Configurations, its limitations, and other management options, see [Managing platform updates with Maintenance Configurations](maintenance-configurations.md).
+Maintenance Configurations lets you decide when to apply platform updates to various Azure resources. This topic covers the Azure CLI options for using this service. For more about benefits of using Maintenance Configurations, its limitations, and other management options, see [Managing platform updates with Maintenance Configurations](maintenance-configurations.md).
 
 > [!IMPORTANT]
 > There are different **scopes** which support certain machine types and schedules, so please ensure you are selecting the right scope for your virtual machine.
 
 ## Create a maintenance configuration
 
-Use `az maintenance configuration create` to create a maintenance configuration. This example creates a maintenance configuration named *myConfig* scoped to the host. 
+The first step to creating a maintenance configuration is creating a resource group as a container for your configuration. In this example, a resource group named *myMaintenanceRG* is created in *eastus*. If you already have a resource group that you want to use, you can skip this part and replace the resource group name with your own in the rest of the examples.
 
 ```azurecli-interactive
 az group create \
    --location eastus \
    --name myMaintenanceRG
-az maintenance configuration create \
-   -g myMaintenanceRG \
-   --resource-name myConfig \
-   --maintenance-scope host\
-   --location eastus
 ```
 
-Copy the configuration ID from the output to use later.
+After creating the resource group, use `az maintenance configuration create` to create a maintenance configuration. 
+
+### Host
 
-Using `--maintenance-scope host` ensures that the maintenance configuration is used for controlling updates to the host infrastructure.
+This example creates a maintenance configuration named *myConfig* scoped to host machines with a scheduled window of 5 hours on the fourth Monday of every month.
 
-If you try to create a configuration with the same name, but in a different location, you will get an error. Configuration names must be unique to your resource group.
+```azurecli-interactive
+az maintenance configuration create \
+   --resource-group myMaintenanceRG \
+   --resource-name myConfig \
+   --maintenance-scope host \
+   --location eastus \
+   --maintenance-window-duration "05:00" \
+   --maintenance-window-recur-every "Month Fourth Monday" \
+   --maintenance-window-start-date-time "2020-12-30 08:00" \
+   --maintenance-window-time-zone "Pacific Standard Time"
+```
+ 
+Using `--maintenance-scope host` ensures that the maintenance configuration is used for controlling updates to the host infrastructure. If you try to create a configuration with the same name, but in a different location, you will get an error. Configuration names must be unique to your resource group.
 
-You can query for available maintenance configurations using `az maintenance configuration list`.
+You can check if you have created the maintenance configuration successfully by querying for available maintenance configurations using `az maintenance configuration list`. 
 
 ```azurecli-interactive
-az maintenance configuration list --query "[].{Name:name, ID:id}" -o table 
+az maintenance configuration list 
+   --query "[].{Name:name, ID:id}" 
+   --output table 
 ```
 
-### Create a maintenance configuration with scheduled window
-You can also declare a scheduled window when Azure will apply the updates on your resources. This example creates a maintenance configuration named myConfig with a scheduled window of 5 hours on the fourth Monday of every month. Once you create a scheduled window you no longer have to apply the updates manually.
+> [!NOTE]
+> Maintenance recurrence can be expressed as daily, weekly or monthly. Some examples are:
+> - **daily**- maintenance-window-recur-every: "Day" **or** "3Days"
+> - **weekly**- maintenance-window-recur-every: "3Weeks" **or** "Week Saturday,Sunday"
+> - **monthly**- maintenance-window-recur-every: "Month day23,day24" **or** "Month Last Sunday" **or** "Month Fourth Monday"
+
+### Virtual Machine Scale Sets 
+
+This example creates a maintenance configuration named *myConfig* with the osimage scope for virtual machine scale sets with a scheduled window of 5 hours on the fourth Monday of every month.
 
 ```azurecli-interactive
 az maintenance configuration create \
-   -g myMaintenanceRG \
+   --resource-group myMaintenanceRG \
    --resource-name myConfig \
-   --maintenance-scope host \
+   --maintenance-scope osimage \
    --location eastus \
    --maintenance-window-duration "05:00" \
    --maintenance-window-recur-every "Month Fourth Monday" \
    --maintenance-window-start-date-time "2020-12-30 08:00" \
    --maintenance-window-time-zone "Pacific Standard Time"
 ```
 
-> [!IMPORTANT]
-> Maintenance **duration** must be *2 hours* or longer.
-
+### Guest VMs
 
-Maintenance recurrence can be expressed as daily, weekly or monthly. Some examples are:
-- **daily**- maintenance-window-recur-every: "Day" **or** "3Days"
-- **weekly**- maintenance-window-recur-every: "3Weeks" **or** "Week Saturday,Sunday"
-- **monthly**- maintenance-window-recur-every: "Month day23,day24" **or** "Month Last Sunday" **or** "Month Fourth Monday"
+This example creates a maintenance configuration named *myConfig* scoped to guest machines (VMs and Arc enabled servers) with a scheduled window of 2 hours every 20 days.
 
+```azurecli-interactive
+az maintenance configuration create \
+   --resource-group myMaintenanceRG \
+   --resource-name myConfig \
+   --maintenance-scope InGuestPatch \
+   --location eastus 
+   --maintenance-window-duration "02:00" 
+   --maintenance-window-recur-every "20days" 
+   --maintenance-window-start-date-time "2022-12-30 07:00" 
+   --maintenance-window-time-zone "Pacific Standard Time" 
+   --install-patches-linux-parameters package-name-masks-to-exclude="ppt" package-name-masks-to-include="apt" classifications-to-include="Other" 
+   --install-patches-windows-parameters kb-numbers-to-exclude="KB123456" kb-numbers-to-include="KB123456" classifications-to-include="FeaturePack" 
+   --reboot-setting "IfRequired" 
+   --extension-properties InGuestPatchMode="User"
+```
 
 ## Assign the configuration
 
 Use `az maintenance assignment create` to assign the configuration to your machine.
 
 ### Isolated VM
 
-Apply the configuration to a VM using the ID of the configuration. Specify `--resource-type virtualMachines` and supply the name of the VM for `--resource-name`, and the resource group for to the VM in `--resource-group`, and the location of the VM for `--location`. 
+Apply the configuration to an isolated host VM using the ID of the configuration. Specify `--resource-type virtualMachines` and supply the name of the VM for `--resource-name`, and the resource group for to the VM in `--resource-group`, and the location of the VM for `--location`. 
 
 ```azurecli-interactive
 az maintenance assignment create \
@@ -88,7 +116,7 @@ az maintenance assignment create \
    --resource-type virtualMachines \
    --provider-name Microsoft.Compute \
    --configuration-assignment-name myConfig \
-   --maintenance-configuration-id "/subscriptions/1111abcd-1a11-1a2b-1a12-123456789abc/resourcegroups/myMaintenanceRG/providers/Microsoft.Maintenance/maintenanceConfigurations/myConfig"
+   --maintenance-configuration-id "/subscriptions/{subscription ID}/resourcegroups/myMaintenanceRG/providers/Microsoft.Maintenance/maintenanceConfigurations/myConfig"
 ```
 
 ### Dedicated host
@@ -99,17 +127,43 @@ The parameter `--resource-id` is the ID of the host. You can use [az-vm-host-get
 
 ```azurecli-interactive
 az maintenance assignment create \
-   -g myDHResourceGroup \
+   --resource-group myDHResourceGroup \
    --resource-name myHost \
    --resource-type hosts \
    --provider-name Microsoft.Compute \
    --configuration-assignment-name myConfig \
-   --maintenance-configuration-id "/subscriptions/1111abcd-1a11-1a2b-1a12-123456789abc/resourcegroups/myDhResourceGroup/providers/Microsoft.Maintenance/maintenanceConfigurations/myConfig" \
-   -l eastus \
+   --maintenance-configuration-id "/subscriptions/{subscription ID}/resourcegroups/myDhResourceGroup/providers/Microsoft.Maintenance/maintenanceConfigurations/myConfig" \
+   --location eastus \
    --resource-parent-name myHostGroup \
    --resource-parent-type hostGroups 
 ```
 
+### Virtual Machine Scale Sets
+
+```azurecli-interactive
+az maintenance assignment create \
+   --resource-group myMaintenanceRG \
+   --location eastus \
+   --resource-name myVMSS \
+   --resource-type virtualMachineScaleSets \
+   --provider-name Microsoft.Compute \
+   --configuration-assignment-name myConfig \
+   --maintenance-configuration-id "/subscriptions/{subscription ID}/resourcegroups/myMaintenanceRG/providers/Microsoft.Maintenance/maintenanceConfigurations/myConfig"
+```
+
+### Guest VMs
+
+```azurecli-interactive
+az maintenance assignment create \
+   --resource-group myMaintenanceRG \
+   --location eastus \
+   --resource-name myVM \
+   --resource-type virtualMachines \
+   --provider-name Microsoft.Compute \
+   --configuration-assignment-name myConfig \
+   --maintenance-configuration-id "/subscriptions/{subscription ID}/resourcegroups/myMaintenanceRG/providers/Microsoft.Maintenance/maintenanceConfigurations/myConfig"
+```
+
 ## Check configuration
 
 You can verify that the configuration was applied correctly, or check to see what configuration is currently applied using `az maintenance assignment list`.
@@ -137,9 +191,32 @@ az maintenance assignment list \
    --resource-parent-name myHostGroup \
    --resource-parent-type hostGroups 
    --query "[].{ResourceGroup:resourceGroup,configName:name}" \
-   -o table
+   --output table
+```
+
+### Virtual Machine Scale Sets 
+
+```azurecli-interactive
+az maintenance assignment list \
+   --provider-name Microsoft.Compute \
+   --resource-group myMaintenanceRG \
+   --resource-name myVMSS \
+   --resource-type virtualMachines \
+   --query "[].{resource:resourceGroup, configName:name}" \
+   --output table
 ```
 
+### Guest VMs
+
+```azurecli-interactive
+az maintenance assignment list \
+   --provider-name Microsoft.Compute \
+   --resource-group myMaintenanceRG \
+   --resource-name myVM \
+   --resource-type virtualMachines \
+   --query "[].{resource:resourceGroup, configName:name}" \
+   --output table
+```
 
 ## Check for pending updates
 
@@ -168,11 +245,12 @@ Check for pending updates for an isolated VM. In this example, the output is for
 
 ```azurecli-interactive
 az maintenance update list \
-   -g myMaintenanceRg \
+   --subscription {subscription ID} \
+   --resourcegroup myMaintenanceRg \
    --resource-name myVM \
    --resource-type virtualMachines \
    --provider-name Microsoft.Compute \
-   -o table
+   --output table
 ```
 
 ### Dedicated host
@@ -181,27 +259,27 @@ To check for pending updates for a dedicated host. In this example, the output i
 
 ```azurecli-interactive
 az maintenance update list \
-   --subscription 1111abcd-1a11-1a2b-1a12-123456789abc \
-   -g myHostResourceGroup \
+   --subscription {subscription ID} \
+   --resourcegroup myHostResourceGroup \
    --resource-name myHost \
    --resource-type hosts \
    --provider-name Microsoft.Compute \
    --resource-parentname myHostGroup \
    --resource-parent-type hostGroups \
-   -o table
+   --output table
 ```
 
 ## Apply updates
 
-Use `az maintenance apply update` to apply pending updates. On success, this command will return JSON containing the details of the update. Apply update calls can take upto 2 hours to complete.
+Use `az maintenance apply update` to apply pending updates. On success, this command will return JSON containing the details of the update. Apply update calls can take up to 2 hours to complete.
 
 ### Isolated VM
 
 Create a request to apply updates to an isolated VM.
 
 ```azurecli-interactive
 az maintenance applyupdate create \
-   --subscription 1111abcd-1a11-1a2b-1a12-123456789abc \
+   --subscription {subscriptionID} \
    --resource-group myMaintenanceRG \
    --resource-name myVM \
    --resource-type virtualMachines \
@@ -215,7 +293,7 @@ Apply updates to a dedicated host.
 
 ```azurecli-interactive
 az maintenance applyupdate create \
-   --subscription 1111abcd-1a11-1a2b-1a12-123456789abc \
+   --subscription {subscriptionID} \
    --resource-group myHostResourceGroup \
    --resource-name myHost \
    --resource-type hosts \
@@ -224,6 +302,19 @@ az maintenance applyupdate create \
    --resource-parent-type hostGroups
 ```
 
+### Virtual Machine Scale Sets
+
+Apply update to a scale set
+
+```azurecli-interactive
+az maintenance applyupdate create \
+   --subscription {subscriptionID} \
+   --resource-group myMaintenanceRG \
+   --resource-name myVMSS \
+   --resource-type virtualMachineScaleSets \
+   --provider-name Microsoft.Compute
+```
+
 ## Check the status of applying updates 
 
 You can check on the progress of the updates using `az maintenance applyupdate get`. 
@@ -246,18 +337,21 @@ LastUpdateTime will be the time when the update got complete, either initiated b
 
 ```azurecli-interactive
 az maintenance applyupdate get \
+   --subscription {subscriptionID} \ 
    --resource-group myMaintenanceRG \
    --resource-name myVM \
    --resource-type virtualMachines \
    --provider-name Microsoft.Compute \
-   --apply-update-name default 
+   --apply-update-name myUpdateName \
+   --query "{LastUpdate:lastUpdateTime, Name:name, ResourceGroup:resourceGroup, Status:status}" \
+   --output table
 ```
 
 ### Dedicated host
 
 ```azurecli-interactive
 az maintenance applyupdate get \
-   --subscription 1111abcd-1a11-1a2b-1a12-123456789abc \ 
+   --subscription {subscriptionID} \ 
    --resource-group myMaintenanceRG \
    --resource-name myHost \
    --resource-type hosts \
@@ -269,6 +363,19 @@ az maintenance applyupdate get \
    --output table
 ```
 
+### Virtual Machine Scale Sets
+
+```azurecli-interactive
+az maintenance applyupdate get \
+   --subscription {subscriptionID} \ 
+   --resource-group myMaintenanceRG \
+   --resource-name myVMSS \
+   --resource-type virtualMachineScaleSets \
+   --provider-name Microsoft.Compute \
+   --apply-update-name myUpdateName \
+   --query "{LastUpdate:lastUpdateTime, Name:name, ResourceGroup:resourceGroup, Status:status}" \
+   --output table
+```
 
 ## Delete a maintenance configuration
 
@@ -277,7 +384,7 @@ Use `az maintenance configuration delete` to delete a maintenance configuration.
 ```azurecli-interactive
 az maintenance configuration delete \
    --subscription 1111abcd-1a11-1a2b-1a12-123456789abc \
-   -g myResourceGroup \
+   -resource-group myResourceGroup \
    --resource-name myConfig
 ```
 

articles/virtual-machines/maintenance-configurations-powershell.md

@@ -55,7 +55,7 @@ You may also be asked to confirm that you want to install from an *untrusted rep
 
 ## Create a maintenance configuration
 
-Create a resource group as a container for your configuration. In this example, a resource group named *myMaintenanceRG* is created in *eastus*. If you already have a resource group that you want to use, you can skip this part and replace the resource group name with your own in the rest of the examples.
+The first step to creating a maintenance configuration is creating a resource group as a container for your configuration. In this example, a resource group named *myMaintenanceRG* is created in *eastus*. If you already have a resource group that you want to use, you can skip this part and replace the resource group name with your own in the rest of the examples.
 
 ```azurepowershell-interactive
 New-AzResourceGroup `
@@ -188,7 +188,7 @@ After you have created your configuration, you might want to also assign machine
 
 ### Isolated VM
 
-Apply the configuration to a VM using the ID of the configuration. Specify `-ResourceType VirtualMachines` and supply the name of the VM for `-ResourceName`, and the resource group of the VM for `-ResourceGroupName`.
+Assign the configuration to a VM using the ID of the configuration. Specify `-ResourceType VirtualMachines` and supply the name of the VM for `-ResourceName`, and the resource group of the VM for `-ResourceGroupName`.
 
 ```azurepowershell-interactive
 New-AzConfigurationAssignment `
@@ -231,6 +231,20 @@ New-AzConfigurationAssignment `
    -MaintenanceConfigurationId "configID"
 ```
 
+
+### Guest
+
+```azurepowershell-interactive
+New-AzConfigurationAssignment `
+   -ResourceGroupName "myResourceGroup" `
+   -Location "eastus" `
+   -ResourceName "myGuest" `
+   -ResourceType "VirtualMachines" `
+   -ProviderName "Microsoft.Compute" `
+   -ConfigurationAssignmentName "configName" `
+   -MaintenanceConfigurationId "configID"
+```
+
 ## Check for pending updates
 
 Use [Get-AzMaintenanceUpdate](/powershell/module/az.maintenance/get-azmaintenanceupdate) to see if there are pending updates. Use `-subscription` to specify the Azure subscription of the VM if it is different from the one that you are logged into.

articles/virtual-machines/maintenance-configurations.md

@@ -18,7 +18,7 @@ ms.author: cynthn
 Maintenance Configurations gives you the ability to control and manage updates for many Azure virtual machine resources since Azure frequently updates its infrastructure to improve reliability, performance, security or launch new features. Most updates are transparent to users, but some sensitive workloads, like gaming, media streaming, and financial transactions, can't tolerate even few seconds of a VM freezing or disconnecting for maintenance. Maintenance Configurations is integrated with Azure Resource Graph (ARG) for low latency and high scale customer experience.
 
 >[!IMPORTANT]
-> Users are required to have a role of at least contributor in order to use maintenance configurations.
+> Users are required to have a role of at least contributor in order to use maintenance configurations. Users also have to ensure that their subscription is registered with Maintenance Resource Provider to use maintenance configurations.
 
 ## Scopes