Edit

Control updates with Maintenance Configurations and the Azure CLI

  • Article
  • 7 minutes to read

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets ✔️ 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 using this service. For more about benefits of using Maintenance Configurations, its limitations, and other management options, see Managing platform updates with Maintenance Configurations.

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

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.

az group create \
   --location eastus \
   --name myMaintenanceRG

After creating the resource group, use az maintenance configuration create to create a maintenance configuration.

Host

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.

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 check if you have created the maintenance configuration successfully by querying for available maintenance configurations using az maintenance configuration list.

az maintenance configuration list 
   --query "[].{Name:name, ID:id}" 
   --output table

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.

az maintenance configuration create \
   --resource-group myMaintenanceRG \
   --resource-name myConfig \
   --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"

Guest VMs

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. To learn more about this maintenance configurations on guest VMs see Guest.

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 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.

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"

Dedicated host

To apply a configuration to a dedicated host, you need to include --resource-type hosts, --resource-parent-name with the name of the host group, and --resource-parent-type hostGroups.

The parameter --resource-id is the ID of the host. You can use az-vm-host-get-instance-view to get the ID of your dedicated host.

az maintenance assignment create \
   --resource-group myDHResourceGroup \
   --resource-name myHost \
   --resource-type hosts \
   --provider-name Microsoft.Compute \
   --configuration-assignment-name myConfig \
   --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

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

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.

Isolated VM

az maintenance assignment list \
   --provider-name Microsoft.Compute \
   --resource-group myMaintenanceRG \
   --resource-name myVM \
   --resource-type virtualMachines \
   --query "[].{resource:resourceGroup, configName:name}" \
   --output table

Dedicated host

az maintenance assignment list \
   --resource-group myDHResourceGroup \
   --resource-name myHost \
   --resource-type hosts \
   --provider-name Microsoft.Compute \
   --resource-parent-name myHostGroup \
   --resource-parent-type hostGroups 
   --query "[].{ResourceGroup:resourceGroup,configName:name}" \
   --output table

Virtual Machine Scale Sets

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

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

Use az maintenance update list to see if there are pending updates. Update --subscription to be the ID for the subscription that contains the VM.

If there are no updates, the command will return an error message, which will contain the text: Resource not found...StatusCode: 404.

If there are updates, only one will be returned, even if there are multiple updates pending. The data for this update will be returned in an object:

[
  {
    "impactDurationInSec": 9,
    "impactType": "Freeze",
    "maintenanceScope": "Host",
    "notBefore": "2020-03-03T07:23:04.905538+00:00",
    "resourceId": "/subscriptions/9120c5ff-e78e-4bd0-b29f-75c19cadd078/resourcegroups/DemoRG/providers/Microsoft.Compute/hostGroups/demoHostGroup/hosts/myHost",
    "status": "Pending"
  }
]

Isolated VM

Check for pending updates for an isolated VM. In this example, the output is formatted as a table for readability.

az maintenance update list \
   --subscription {subscription ID} \
   --resourcegroup myMaintenanceRg \
   --resource-name myVM \
   --resource-type virtualMachines \
   --provider-name Microsoft.Compute \
   --output table

Dedicated host

To check for pending updates for a dedicated host. In this example, the output is formatted as a table for readability. Replace the values for the resources with your own.

az maintenance update list \
   --subscription {subscription ID} \
   --resourcegroup myHostResourceGroup \
   --resource-name myHost \
   --resource-type hosts \
   --provider-name Microsoft.Compute \
   --resource-parentname myHostGroup \
   --resource-parent-type hostGroups \
   --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 up to 2 hours to complete.

Isolated VM

Create a request to apply updates to an isolated VM.

az maintenance applyupdate create \
   --subscription {subscriptionID} \
   --resource-group myMaintenanceRG \
   --resource-name myVM \
   --resource-type virtualMachines \
   --provider-name Microsoft.Compute

Dedicated host

Apply updates to a dedicated host.

az maintenance applyupdate create \
   --subscription {subscriptionID} \
   --resource-group myHostResourceGroup \
   --resource-name myHost \
   --resource-type hosts \
   --provider-name Microsoft.Compute \
   --resource-parent-name myHostGroup \
   --resource-parent-type hostGroups

Virtual Machine Scale Sets

Apply update to a scale set

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.

You can use default as the update name to see results for the last update, or replace myUpdateName with the name of the update that was returned when you ran az maintenance applyupdate create.

Status         : Completed
ResourceId     : /subscriptions/12ae7457-4a34-465c-94c1-17c058c2bd25/resourcegroups/TestShantS/providers/Microsoft.Comp
ute/virtualMachines/DXT-test-04-iso
LastUpdateTime : 1/1/2020 12:00:00 AM
Id             : /subscriptions/12ae7457-4a34-465c-94c1-17c058c2bd25/resourcegroups/TestShantS/providers/Microsoft.Comp
ute/virtualMachines/DXT-test-04-iso/providers/Microsoft.Maintenance/applyUpdates/default
Name           : default
Type           : Microsoft.Maintenance/applyUpdates

LastUpdateTime will be the time when the update got complete, either initiated by you or by the platform in case self-maintenance window was not used. If there has never been an update applied through maintenance control it will show default value.

Isolated VM

az maintenance applyupdate get \
   --subscription {subscriptionID} \ 
   --resource-group myMaintenanceRG \
   --resource-name myVM \
   --resource-type virtualMachines \
   --provider-name Microsoft.Compute \
   --apply-update-name myUpdateName \
   --query "{LastUpdate:lastUpdateTime, Name:name, ResourceGroup:resourceGroup, Status:status}" \
   --output table

Dedicated host

az maintenance applyupdate get \
   --subscription {subscriptionID} \ 
   --resource-group myMaintenanceRG \
   --resource-name myHost \
   --resource-type hosts \
   --provider-name Microsoft.Compute \
   --resource-parent-name myHostGroup \ 
   --resource-parent-type hostGroups \
   --apply-update-name myUpdateName \
   --query "{LastUpdate:lastUpdateTime, Name:name, ResourceGroup:resourceGroup, Status:status}" \
   --output table

Virtual Machine Scale Sets

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

Use az maintenance configuration delete to delete a maintenance configuration. Deleting the configuration removes the maintenance control from the associated resources.

az maintenance configuration delete \
   --subscription 1111abcd-1a11-1a2b-1a12-123456789abc \
   -resource-group myResourceGroup \
   --resource-name myConfig

Next steps

To learn more, see Maintenance and updates.