Upgrade preference for App Service Environment planned maintenance

Azure App Service is regularly updated to provide new features, new runtime versions, performance improvements, and bug fixes. This is also known as planned maintenance. The upgrade happens automatically. The upgrades are applied progressively through the regions following Azure Safe Deployment Practices. An App Service Environment is an Azure App Service feature that provides a fully isolated and dedicated environment for running App Service apps securely at high scale. Because of the isolated nature of App Service Environment, you have an opportunity to influence the upgrade process.

If you don't have an App Service Environment, see How to Create an App Service Environment v3.

With App Service Environment v3, you can specify your preference for when and how the planned maintenance is applied. The upgrade can be applied automatically or manually. Even with your preference set to automatic, you have some options to influence the timing.

Automatic upgrade preference

When you use an automatic upgrade preference, the platform upgrades your App Service Environment instance when the upgrade is available in the region in which the instance is deployed. You can choose from one of these options:

• None is the default option. This option automatically applies the upgrade during the upgrade process for that region.
• Early applies the upgrade automatically, but prioritizes it as one of the first instances in the region to be upgraded.
• Late applies the upgrade automatically, but the instance is one of the last in the region to be upgraded.

In smaller regions, Early and Late upgrade preferences might be very close to each other.

Manual upgrade preference

Manual upgrade preference gives you the option to receive a notification when an upgrade is available. The availability is also visible in the Azure portal. After the upgrade is available, you'll have 15 days to start the upgrade process. If you don't start the upgrade within the 15 days, the upgrade is processed with the remaining automatic upgrades in the region.

Upgrades normally don't affect the availability of your apps. The upgrade adds extra instances to ensure that the same capacity is available during upgrade. Patched and restarted instances are added back in rotation, and when you have workloads sensitive to restarts you should plan to start the maintenance during non-business hours. The full upgrade process normally finishes within 18 hours, but could take longer. Once the upgrade is started the upgrade runs until it's complete and isn't paused during standard business hours.

Configure notifications

When an upgrade is available, Azure adds a planned maintenance event in the Service Health dashboard of Azure Monitor. To see past notifications in the Azure portal, navigate to Home > Monitor > Service Health > Planned maintenance. To make it easy to find the relevant events, select the Service box and check only the App Service type. You can also filter by subscription and region.

You can configure alerts to send a message to your email address and/or SMS phone number when an event is generated in Azure Monitor. You can also set up a trigger for your custom Azure Function or Logic App, which allows you to automatically take action on your resources. This action could be to automatically divert the traffic from your App Service Environment in one region that is upgraded to an App Service Environment in another region. Then, you can automatically change the traffic back to normal when an upgrade completes.

To configure alerts for upgrade notifications, select the Add service health alert at the top of the dashboard. Learn more about Azure Monitor Alerts. This how-to article guides you through configuring alerts for service health events. Finally, you can follow this how-to guide to learn how to create actions groups that trigger based on the alert.

Send test notifications

As you build your automation and notification logic, you want to test it before the actual upgrade is available as this upgrade could be more than a month out. The Azure portal has the ability to send a special test upgrade available notification, which you can use to verify your automation logic. The message is similar to the real notification, but the title is prefixed with "[Test]" and the description is different. You can send test notifications after you configured your upgrade preference to Manual.

To send a test notification, navigate to the Configuration page for your App Service Environment and select the Send test notification link. The test notifications are sent in batches every 15 minutes.

ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-Resource-Group>
az resource show --name $ASE_NAME -g $ASE_RG --resource-type "Microsoft.Web/hostingEnvironments" --query properties.upgradePreference

ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-Resource-Group>
az resource update --name $ASE_NAME -g $ASE_RG --resource-type "Microsoft.Web/hostingEnvironments" --set properties.upgradePreference=Manual

ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-Resource-Group>
ASE_ID=$(az appservice ase show --name $ASE_NAME --resource-group $ASE_RG --query id --output tsv)

az rest --method POST --uri "${ASE_ID}/testUpgradeAvailableNotification?api-version=2022-03-01"

az rest --method POST --uri "${ASE_ID}/upgrade?api-version=2022-03-01"

Next steps