[Now Generally Available] What-If for Azure Deployment Stacks

We are proud to announce that what-if for Azure Deployment Stacks is now generally available, in all regions.

To be precise about what this is, since the names are similar: what-if for standard template deployments has been around for a while. This release brings what-if to the deployment stacks resource type. A Stacks What-if result is composed of the list of change types (e.g. create, modify, delete, etc.) and their corresponding resources, the changes to the stack resource itself (e.g. changes to deny settings of a stack), and lastly the changes to the resources a stack manages (e.g. managed resources to be detached or deleted).

Furthermore, the new Stacks What-if filters out "noise" (noisy properties that are flagged by what-if as changes that are false positives) by using a baseline recorded when the stack was deployed. And the result it produces is a Stacks What-If Resource you name and can retrieve later, rather than output that disappears when your terminal scrolls.

This is the most requested feature we have had for deployment stacks. Thank you to everyone who kept that conversation going. This release is a direct result of it.

Why this matters

Deployment stacks manage a collection of resources as a single unit. With deployment stacks, users are able to perform a single delete operation on the stack that is applied to all of its managed resources rather than having to go one-by-one or scope-by-scope to perform that delete. More surgically, a user can also choose to delete a subset of managed resources by removing their definition from the bicep or ARM template that defines the state of the stack. This capability is extremely powerful, and it is also what makes updating a stack feel risky. A change to your template does not just add or modify resources. Depending on the actionOnUnmanage setting, it can also remove resources from the stack's management, or delete them outright.

Until now, the only way to know for certain what a stack update would do was to run it. For teams running production estates on stacks, that is an uncomfortable place to be.

Stacks What-if answers the following questions before you deploy changes:

What is about to happen to my resources?

What resources will be deleted?

What is included

• Stacks What-if at resource group, subscription, and management group scope, in Azure CLI, Azure PowerShell, and the Azure SDKs.
• Detach and Delete changes, so you can see which resources are about to leave the stack's management or be removed from Azure.
• Standard change types on managed resources, such as create, modify, and delete, including property level diff detail.
• Noise reduction, enabled in all regions, for more accurate results, with false positives (aka noise) removed from the Stacks What-if response.
• Stacks What-If Result as a New Resource Type, which you can reference by URI and use as an approval artifact in a pipeline.

What Stacks What-if reports

Stacks What-if evaluates your template against the current state of the resources the stack manages, and reports each one as a change type. It makes no changes to your resources.

That list is specific to stacks, and it is not the same set you get from deployment what-if. Detach and Delete are the two that matter most here (e.g. a resource you removed from your template is about to leave the stack's management, or be deleted outright), and they are the reason this feature exists. They tell you which resources are affected before you deploy, not after.

The one thing to know if you're coming from deployments

If you already use what-if for regular Bicep or ARM template deployments, there is one difference worth internalizing.

For a standard deployment, what-if is an operation. You run it, Azure returns the predicted changes, and nothing persists.

For a deployment stack, Stacks What-if creates a Stacks What-If Resource, which stores the Stacks What-If response. The result is a standalone Azure resource of type Microsoft.Resources/deploymentStacksWhatIfResults. You give it a name, it gets its own resource ID, and it references the stack it was evaluated against through properties.deploymentStackResourceId.

That means a Stacks What-If Resource ID looks like this:

/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Resources/deploymentStacksWhatIfResults/{what-if-result-name}

Get started running Stacks What-if

Azure CLI, at resource group scope:

az stack-whatif group create \
  --name "my-preview" \
  --resource-group "my-rg" \
  --stack-id "/subscriptions/<sub-id>/resourceGroups/my-rg/providers/Microsoft.Resources/deploymentStacks/my-stack" \
  --template-file "main.bicep" \
  --action-on-unmanage "detachAll" \
  --deny-settings-mode "none" \
  --retention-interval "PT3H"

Azure PowerShell:

New-AzResourceGroupDeploymentStackWhatIfResult `
  -Name "my-preview" `
  -ResourceGroupName "my-rg" `
  -StackResourceId "<stack-resource-id>" `
  -TemplateFile "main.bicep" `
  -ActionOnUnmanage "DetachAll" `
  -DenySettingsMode "None" `
  -RetentionInterval "PT3H"

Real output from a Stacks What-if run against a demo stack. The legend maps each symbol to a change type, then each managed resource is listed with the property changes underneath it:

Subscription and management group scopes work the same way, using az stack-whatif sub and az stack-whatif mg, or the New-AzSubscriptionDeploymentStackWhatIfResult and New-AzManagementGroupDeploymentStackWhatIfResult cmdlets.

A detail that is easy to miss: the stack does not have to exist yet. If it doesn't, Stacks What-if reports the stack itself as a new resource, so you can preview the very first deployment of a stack before you create anything.

Using it in a pipeline

The durability of a Stacks What-If Resource is what makes this useful in CI. A pattern that works well:

1. On a pull request, run Stacks What-if against the target stack and give the result a name that includes the build or PR number.
2. Post the output, or a link to the result, as PR feedback so a reviewer sees the predicted changes next to the template diff that caused them.
3. Gate the deploy stage on approval. If someone wants to re-check before approving, they retrieve the same stored result rather than rerunning the evaluation and hoping it matches.

Point 3 is the part that's genuinely different. With deployment what-if you get output in a log, and if you want it again you rerun and hope nothing drifted underneath you. With a Stacks What-If Resource you retrieve the exact evaluation the reviewer looked at.

Set the retention interval to cover your review window and no longer. PT3H gets cleaned up for you, so it's a good default for per pull request runs.

Resources

• Preview deployment stack changes with what-if. The documentation for what is being announced here. Change types, running Stacks What-if at each scope, retrieving and deleting Stacks What-If Resources, and noise reduction.
• Create and deploy Azure deployment stacks in Bicep. The main deployment stacks article, if you are new to stacks or want a refresher on actionOnUnmanage.
• Preview Bicep deployment changes by using what-if. What-if for standard template deployments. This is the separate, existing feature described earlier, included here for comparison rather than as part of this release.

Tell us what you think

This feature exists because people filed issues and kept talking to us about them. That has not changed. If Stacks What-if reports something that looks wrong, or the output is awkward in your pipeline, open an issue in Azure/deployment-stacks. We read them, and several are already shaping what we do next.