Set upgrade preference for App Service Environment planned maintenance

Microsoft regularly updates Azure App Service to provide new features, new runtime versions, performance improvements, and bug fixes. The upgrade process is referred to as planned maintenance. Upgrades happen automatically and they're applied progressively through the regions following Advancing Safe Deployment Practices.

This article describes how to configure the upgrade preference for an App Service Environment v3. An App Service Environment provides a fully isolated and dedicated environment for running App Service apps securely at high scale. Because of the isolated nature of the environment, you have an opportunity to influence the upgrade process.

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. Procedures are provided to set your preferences in the Azure portal or by using the Azure CLI.

Prerequisites

An App Service Environment v3. To create a new environment, follow the steps in Quickstart: Create an App Service Environment.

Review automatic upgrade options

When you configure automatic upgrades, the platform upgrades your App Service Environment instance when the upgrade is available in the deployment region for the instance. You can choose from the following options:

None: (Default) Upgrade automatically during the upgrade process for the region.
Early: Upgrade automatically with a high prioritization compared with other instances in the region.
Late: Upgrade automatically with a low prioritization compared with other instances in the region.

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

Review manual upgrade options

When you configure manual upgrades, you receive a notification when an upgrade is available. The availability is also visible in the Azure portal. After the upgrade is available, you typically 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 the same capacity is available during upgrade. Patched and restarted instances are added back in rotation. When you have workloads sensitive to restarts, you should plan to start the maintenance during nonbusiness hours. The full upgrade process normally finishes within 18 hours, but can take longer. After the upgrade starts, the upgrade runs until it's complete and isn't paused during standard business hours.

Important considerations

If you choose manual upgrades, there are important considerations to keep in mind:

You might receive less than 15 days notice. Microsoft usually provides a 15-day notice before the upgrade is applied automatically. In rare cases, the notice period is less than 15 days. The "End Time" for the planned maintenance event that you receive always indicates the end of the notice period.
A manual upgrade can transition to automatic. In rare cases, the availability of an upgrade for manual application can transition to an automatic upgrade. A security hotfix might supersede the planned upgrade. A regression might be discovered in a planned upgrade before the updates are applied to your instance. In these cases, the available upgrade is removed and the process transitions to automatic upgrade.
An upgrade is available, but you don't receive a notification. You might see a notice in the Azure portal that an upgrade is available for your App Service Environment, but you don't receive a Service Health notification. (Notifications are sent according to your configuration.) If you don't receive the notification, the available upgrade isn't required and the 15-day time limit doesn't apply. This issue is currently under investigation.

View upgrade notifications

When an upgrade is available, the platform adds an upgrade event on the Service Health dashboard.

In the Azure portal, go to the Azure Monitor > Service Health dashboard.
To see the list of available (unapplied) upgrades, expand the ACTIVE EVENTS > Planned maintenance section.
Use the filters (Scope, Subscription, Region, Service, Event tags) and adjust the list results as needed.
To see more information about a specific upgrade, select the upgrade name in the list. A pane opens showing a summary about the upgrade. Select Issue Updates, Impacted Services, and Impacted Resources for more details.

Configure notifications

You can configure alerts to send a message to your email address 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. You might use the action to automatically divert traffic from your App Service Environment in one region that's being upgraded to an App Service Environment in another region. After the upgrade completes, you can automatically change the traffic back to normal.

In the Azure portal, go to the Azure Monitor > Service Health dashboard.
On the right, select Create service health alert:
Configure the new alert by following the instructions in Create service health alerts.
Create and manage action groups that trigger based on the alert.

For more information, see What are Azure Monitor alerts?

Test notifications for manual upgrades

As you build your automation and notification logic, you want to test it before an actual upgrade occurs. It might be month or more before an upgrade is available.

If you set the Upgrade preference for your App Service Environment to Manual, you can send a test upgrade available notification. The test helps you verify your automation logic. The test message is similar to a real notification, but the title is prefixed with "[Test]" and the description details are different.

In the Azure portal, go to your App Service Environment resource.
In the left menu, select Settings > Configuration.
Locate the Upgrade preference setting, and select the Send test notification link.

Test notifications are sent in batches every 15 minutes.
Allow time for the notification to send. Verify the test notification is listed on the Service Health dashboard in the Azure portal.

You can also send a test notification by using the Azure CLI. For more information, see the procedure described in Apply upgrade to App Service Environment (Azure CLI).

Configure upgrade preference

Use the following procedure to configure the upgrade preference for your App Service Environment. The recommended approach is to use the Azure portal.

Azure portal
Azure CLI

In the Azure portal, go to your App Service Environment resource.
In the left menu, select Settings > Configuration.
Locate the Upgrade preference setting, and select Automatic or Manual.
Select Apply for your changes to take effect.

Run the following commands with the Azure CLI or use the Azure Cloud Shell.

Set the <placeholder> command parameters to the values for your App Service Environment:
```
ASE_NAME=<App-Service-Environment>
ASE_RG=<Resource-Group>
```
View the current upgrade preference for the App Service Environment:
```
az resource show --name $ASE_NAME -g $ASE_RG --resource-type "Microsoft.Web/hostingEnvironments" --query properties.upgradePreference
```
The output displays "Manual" for manual upgrade, or the automatic upgrade type: "Early," "Late," or "None."
Configure the Upgrade preference setting for the App Service Environment:
- For manual upgrade, set the upgradePreference property to Manual:
```
az resource update --name $ASE_NAME -g $ASE_RG --resource-type "Microsoft.Web/hostingEnvironments" --set properties.upgradePreference=Manual
```
  The output shows a detailed listing of the property settings for the App Service Environment.
  
  Confirm the upgrade preference is set as expected:
```
"upgradePreference": "Manual",
```
- For automatic upgrade, set the upgradePreference property to the automatic value: Early, Late, or None. The following example sets the preference to Early automatic upgrades:
```
az resource update --name $ASE_NAME -g $ASE_RG --resource-type "Microsoft.Web/hostingEnvironments" --set properties.upgradePreference=Early
```
  Confirm the upgrade preference is set as expected:
```
"upgradePreference": "Early",
```

Apply upgrade to App Service Environment

When an upgrade is available, a banner displays in the Azure portal. Use the following procedure to apply the upgrade to your App Service Environment.

Azure portal
Azure CLI

In the Azure portal, go to your App Service Environment resource.
In the left menu, select Settings > Configuration.
Locate the Upgrade preference setting, and select Upgrade now:

The portal displays a confirmation message.
Select Start upgrade to upgrade.

Run the following commands with the Azure CLI or use the Azure Cloud Shell.

The following procedure sends a test upgrade notification for the App Service Environment, and demonstrates how to initiate the upgrade process.

Set the <placeholder> command parameters to the values for your App Service Environment:
```
ASE_NAME=<App-Service-Environment>
ASE_RG=<Resource-Group>
```

Get your App Service Environment ID:

ASE_ID=$(az appservice ase show --name $ASE_NAME --resource-group $ASE_RG --query id --output tsv)

Start the upgrade process:

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

During the upgrade process, the platform sends notifications, according to your configuration.

Feedback

Was this page helpful?

Last updated on 2026-03-12