Manage pre and post events maintenance configuration events (preview)

Applies to: ✔️ Windows VMs ✔️ Linux VMs ✔️ On-premises environment ✔️ Azure Arc-enabled servers ✔️ Azure VMs.

This article describes on how to register your subscription and manage pre and post events in Azure Update Manager.

Register your subscription for public preview

To self-register your subscription for public preview, follow these steps:

Azure portal

1. Sign in to the Azure portal and select More services.

2. On the All services page, search for Preview features.

3. On the Preview Features page, search and select Pre and Post Events.

4. Select the feature and then select Register to register the subscription.

   

Azure CLI

az feature register --name InGuestPatchPrePostMaintenanceActivity --namespace Microsoft.Maintenance

PowerShell

Register-AzProviderFeature -FeatureName "InGuestPatchPrePostMaintenanceActivity" -ProviderNamespace "Microsoft.Maintenance"

Manage pre and post events

View pre and post events

To view the pre and post events, follow these steps:

1. Sign in to the Azure portal and go to Azure Update Manager.

2. Under Manage, select Machines, Maintenance Configurations.

3. In the Maintenance Configuration page, select the maintenance configuration to which you want to add a pre and post event.

4. Select Overview and check the Maintenance events. You can see the count of the pre and post events associated to the configuration.

   

5. Select the count of the pre and post events to view the list of events and the event types.

   

Edit pre and post events

To edit the pre and post events, follow these steps:

1. Follow the steps listed in View pre and post events.
2. In the selected events page, select the pre or post event you want to edit.
3. In the selected pre or post event page, you can edit the Event handler/endpoint used or the location of the endpoint.

Manage the execution of pre/post event and schedule run

To check the successful delivery of a pre and post event to an endpoint from Event Grid, follow these steps:

1. Sign in to the Azure portal and go to Azure Update Manager.
2. Under Manage, select Machines.
3. Select Maintenance Configurations from the ribbon at the top.
4. In the Maintenance Configuration page, select the maintenance configuration for which you want to view a pre and post event.
5. On the selected Maintenance Configuration page, under Settings in the ToC, select Events.
6. In the Essentials section, you can view the metrics for all the events under the selected event subscription. In the graph, the count of the Published Events metric should match with the count of Matched Events metric. Both values should also correspond with the Delivered Events count.
7. To view the metrics specific to a pre or a post event, select the name of the event from the grid. Here, the count of Matched Events metric should match with the Delivered Events count.
8. To view the time at which the event was triggered, hover over the line graph. Learn more.

Note

Azure Event Grid adheres to an at-least-once delivery paradigm. This implies that, in exceptional circumstances, there is a chance of the event handler being invoked more than once for a given event. We recommend you to ensure that the event handler actions are idempotent. In other words, if the event handler is executed multiple times, it should not have any adverse effects. Implementing idempotency ensures the robustness of your application in the face of potential duplicate event invocations.

To check if the endpoint has been triggered and completed in the pre or post event

Automation Runbooks via Webhooks

1. Sign in to the Azure portal and go to Azure Automation account.

2. In your Automation account, under Process Automation, select Runbooks.

3. Select the pre or post script that is linked to your Webhook in Event Grid.

4. In Overview, you can view the status of the Runbook job. The trigger time should be approximately 30 minutes before the schedule start time. Once the job is finished, you can come back to the same section to confirm if the status is Completed. For example, ensure that the VM has been either powered on or off.

   

   For more information on how to retrieve details from Automation account's activity log and job statuses, see Manage runbooks in Azure Automation.

Azure Functions

1. Sign in to the Azure portal and go to your Azure Function app.
2. In your Azure Function app, go to the Overview page.
3. Select the specific function from the grid in the Overview page.
4. Under the Monitor column, select Invocations and more.
5. This will take you to the Invocations tab, which displays the execution details and status of the function.

To use application insights to monitor executions in Azure functions, refer here.

Cancel a schedule run before it begins to run

To cancel the schedule run, the cancelation API in your pre-event must get triggered at least 10 minutes before the schedule maintenance configuration start time. You must call the cancelation API in your pre-event, that is, Runbook script or Azure function code.

To cancel the schedule maintenance run

Azure portal

1. Sign in to the Azure portal and go to Azure Update Manager.
2. Under Manage in the ToC, select History.
3. Select the By Maintenance run ID tab, and select the maintenance run ID for which you want to view the history.
4. Select Cancel schedule update. This option is enabled for 10 minutes before the start of the maintenance configuration.

REST API

Apply Updates - Create Or Update Or Cancel - REST API (Azure Maintenance) | Microsoft Learn

PowerShell

New-AzApplyUpdate (Az.Maintenance) | Microsoft Learn

CLI

az maintenance applyupdate | Microsoft Learn

You can obtain the list of machines in the maintenance run from the following ARG query. You can also view the correlation ID by selecting See details:

maintenanceresources  
| where type =~ "microsoft.maintenance/maintenanceconfigurations/applyupdates"  
| where properties.correlationId has "/subscriptions/your- subscription -id/resourcegroups/your- ResourceGroupName/providers/microsoft.maintenance/maintenanceconfigurations/mc-name/providers/microsoft.maintenance/applyupdates/"  
| order by name desc

Note

Azure Update Manager or maintenance configuration will not monitor and automatically cancel the schedule. If the user fails to cancel, the schedule run will proceed with installing updates during the user-defined maintenance window.

Post schedule run

View the history of pre and post events

1. Sign in to the Azure portal and go to Azure Update Manager.
2. Under Manage, select History.
3. Select the By Maintenance run ID tab, select the maintenance run ID for which you want to view the history.
4. Select the Events tab in this history page of the selected maintenance run ID.
5. You can view the count of events and event names along with the Event type and endpoint details.

Debug pre and post events

Automation-Webhook

To view the job history of an event created through Webhook, follow these steps:

1. Find the event name for which you want to view the job logs.
2. Under the Job history column, select View runbook history corresponding to the event name. This takes you to the Automation account where the runbooks reside.
3. Select the specific runbook name that is associated to the pre or post event. In the overview page, you can view the recent jobs of the runbook along with the execution and status details.

Azure Function

To view the history of an event created through Azure Function, follow these steps:

1. Find the event name for which you want to view the job logs.
2. Under the Job history column, select View Azure Function history corresponding to the event name. This takes you to the Azure function Invocations page.
3. You can view the recent invocations along with the execution and status details.

View the status of a canceled schedule run

1. Sign in to the Azure portal and go to Azure Update Manager.
2. Under Manage, select History.
3. Select the By Maintenance run ID tab, and then select the maintenance run ID for which you want to view the status.
4. Refer to the Status to view the status. If the maintenance run has been canceled, the status will be displayed as cancelled. Select the status to view the details.

There are two types of cancelations:

• Cancelation by user: When you invoke the cancelation API from your script or code.
• Cancelation by system: When the system invokes the cancelation API due to an internal error. This is done only if the system is unable to send the pre-event to the customer's end point that is 30 minutes before the scheduled patching job. In this case, the upcoming scheduled maintenance configuration will be canceled due to the failure of running the pre-events by the system.

To confirm if the cancelation is by user or system, you can view the status of the maintenance run ID from the ARG query mentioned above in See details. The error message displays whether the schedule run has been canceled by the user or system and the status field confirms the status of the maintenance run.

The above image shows an example of cancelation by the user, where the error message would be Maintenance cancelled using cancellation API at YYYY-MM-DD. If the maintenance run is canceled by the system due to any reason, the error message in the JSON would be Maintenance cancelled due to internal platform failure at YYYY-MM-DD.

Delete pre and post event

Using Azure portal

To delete pre and post events, follow these steps:

1. Sign in to the Azure portal and go to Azure Update Manager.

2. Under Manage, select Machines, Maintenance Configurations.

3. In the Maintenance Configuration page, select the maintenance configuration to which you want to add a pre and post event.

4. In the selected Maintenance configuration page, under Settings, select Events.

5. Select the event Name you want to delete from the grid.

6. On the selected event page, select Delete.

   

Using PowerShell

Removing Event Subscription

    Remove-AzEventGridSystemTopicEventSubscription -EventSubscriptionName $EventSubscriptionName -ResourceGroupName $ResourceGroupForSystemTopic -SystemTopicName $SystemTopicName

Remove System topic

    Remove-AzEventGridSystemTopic -Name $SystemTopicName -ResourceGroupName $ResourceGroupForSystemTopic

Using CLI

Removing Event subscription

    az eventgrid system-topic event-subscription delete --name “<Event subscription name>” --resource-group $ResourceGroupName --system-topic-name     $SystemTopicName

Remove System topic

    az eventgrid system-topic delete --name $SystemTopicName --resource-group $ResourceGroupName

Using REST API

Event subscription Deletion

    DELETE /subscriptions/<subscription Id>/resourceGroups/<resource group name>/providers/Microsoft.EventGrid/systemTopics/<system topic name>/eventSubscriptions/<Event Subscription name>?api-version=2022-06-15

System topic deletion

    DELETE /subscriptions/<subscription Id>/resourceGroups/<resource group name>/providers/Microsoft.EventGrid/systemTopics/<system topic name>;?api-version=2022-06-15

Next steps

• For an overview of pre and post events (preview) in Azure Update Manager, refer here
• To learn on how to create pre and post events, see pre and post maintenance configuration events.
• To learn how to use pre and post events to turn on and off your VMs using Webhooks, refer here.
• To learn how to use pre and post events to turn on and off your VMs using Azure Functions, refer here.