Management and GovernanceInfrastructure as codepremiumfield-manualoperator-field-manual
What-if deployment
A what-if deployment is a dry-run view for infrastructure as code. Before you deploy a Bicep file or ARM template, Azure Resource Manager compares the desired template with the current Azure state and reports the changes it expects. It does not guarantee every runtime side effect, but it is excellent for spotting accidental deletes, unexpected property changes, missing parameters, and scope mistakes. Engineers use it as a review step before pressing deploy, especially in production subscriptions where a small template change can modify many resources.
ARM what-if deployment, Bicep what-if deployment, deployment preview
Difficulty
fundamentals
CLI mappings
5
Last verified
2026-05-29
Microsoft Learn
A what-if deployment is a preview of changes Azure Resource Manager predicts from an ARM template or Bicep file before deployment. It shows which resources would be created, modified, ignored, or deleted without applying changes, helping teams review infrastructure impact before execution.
Technically, what-if deployment belongs to the ARM deployment control plane. It can run at resource group, subscription, management group, or tenant scope depending on the deployment command. The operation evaluates templates, parameters, conditions, existing resources, dependencies, and deployment mode, then returns predicted change types and property differences. It is used with ARM JSON and Bicep, and it fits naturally into CI/CD pipelines and pull-request checks. It does not execute data-plane work, start applications, migrate databases, or validate every provider-side behavior, so it complements validation and policy checks.
Why it matters
What-if deployment matters because infrastructure code can be syntactically valid and still dangerous. A wrong parameter file can move a resource to a different SKU, remove a diagnostic setting, open public network access, or delete a resource in complete mode. What-if gives reviewers a concrete change set instead of relying on trust or visual inspection of templates. It improves release confidence, reduces surprise outages, and creates evidence for change advisory boards. The biggest value is cultural: teams learn to ask what will change before they deploy across subscriptions, making infrastructure changes more like reviewed software releases than manual cloud edits.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In Azure CLI or pipeline logs, what-if output lists predicted create, modify, delete, no-change, and ignore entries before the deployment command is allowed to proceed.
Signal 02
In pull-request checks, reviewers see the same template and parameter files produce a planned Azure delta, making infrastructure changes easier to approve or reject confidently.
Signal 03
In change tickets or release evidence, teams attach what-if JSON to show expected resource IDs, property differences, deployment scope, and approval context before production and rollback planning
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Block a production Bicep deployment when what-if shows an unapproved delete in complete mode.
Confirm a landing-zone module update changes only diagnostic settings and tags before rollout to many subscriptions.
Review a database, App Service, or networking SKU change for cost and reliability impact before deployment.
Detect parameter-file drift when a pipeline points at the wrong environment values.
Attach predicted resource changes to a change ticket for regulated infrastructure releases.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Insurer prevents a landing-zone delete surprise
An insurance carrier updated a shared landing-zone Bicep module used by claims, actuarial, and analytics subscriptions. A parameter change a
📌Scenario
An insurance carrier updated a shared landing-zone Bicep module used by claims, actuarial, and analytics subscriptions. A parameter change accidentally removed a resource declaration for diagnostic settings.
🎯Business/Technical Objectives
Roll out the module without losing compliance logging.
Detect unintended deletes before production subscriptions were touched.
Create review evidence for the infrastructure change board.
Keep subscription teams from hand-editing the generated resources.
✅Solution Using What-if deployment
The platform team added a what-if deployment gate to the release pipeline at subscription scope. Each target subscription produced a JSON preview before the create step could run. Reviewers searched for delete, public network access, role assignment, and diagnostic-setting changes, then compared the output with the approved module change. The preview showed that diagnostic settings for Key Vault and storage accounts would be deleted in twelve subscriptions because a condition default changed. Engineers fixed the parameter file, reran what-if, and saved the clean output with the change record. The final deployment then ran through the same identity and template path.
📈Results & Business Impact
Twelve diagnostic-setting deletes were caught before production deployment.
Change-board review time fell from two days to four hours because evidence was concrete.
No subscription owners made emergency portal edits during the rollout.
Quarterly audit sampling found continuous Key Vault and storage logging after the module update.
💡Key Takeaway for Glossary Readers
What-if deployment turns infrastructure review from hope into a visible, scope-specific change set.
Case study 02
Game studio avoids launch-week capacity shock
A multiplayer game studio prepared a matchmaking infrastructure update days before a seasonal event. The Bicep module looked small, but one
📌Scenario
A multiplayer game studio prepared a matchmaking infrastructure update days before a seasonal event. The Bicep module looked small, but one environment parameter pointed to the wrong App Service plan SKU.
🎯Business/Technical Objectives
Confirm the deployment changed only routing and diagnostic settings.
Avoid unplanned hosting cost increases during launch week.
Protect the matchmaking API from accidental scale changes.
Give release managers a simple approve-or-stop signal.
✅Solution Using What-if deployment
Engineers ran what-if deployment from the Azure CLI as part of the GitHub Actions workflow. The gate evaluated the resource group template with the production parameter file and emitted a human-readable summary plus raw JSON. The preview showed an App Service plan moving to a higher Premium tier and a Redis cache replica count changing, neither of which was in the release request. The team traced the issue to a copied staging parameter file. After correction, the preview showed only route settings, tags, and diagnostic categories. The release manager approved the deployment once the what-if artifact matched the intended change list.
📈Results & Business Impact
An estimated 38 percent monthly hosting increase was avoided before it started.
The launch-week deployment completed with no capacity or cache topology surprises.
Release review fell from ninety minutes of template reading to twenty minutes of preview review.
Parameter-file drift was added as a permanent pipeline check.
💡Key Takeaway for Glossary Readers
What-if deployment is especially valuable when a tiny parameter mistake can look harmless in code but expensive in Azure.
Case study 03
University research platform proves safe subscription rollout
A university research computing team maintained standard storage, networking, and budget resources across dozens of grant-funded subscriptio
📌Scenario
A university research computing team maintained standard storage, networking, and budget resources across dozens of grant-funded subscriptions. Faculty teams feared that central automation would overwrite local work.
🎯Business/Technical Objectives
Show researchers exactly what central automation would change.
Protect locally approved resources from accidental deletion.
Standardize tags, budgets, and diagnostics across subscriptions.
Reduce manual email approval loops for routine infrastructure updates.
✅Solution Using What-if deployment
The cloud platform team introduced what-if deployment previews for every subscription-level Bicep rollout. Before deploying, the pipeline generated a preview grouped by subscription and posted a summary to the research operations channel. Local technical owners could review planned tag updates, budget resources, diagnostic settings, and role assignments before approval. The team configured the process to stop automatically on delete changes, then required a named owner to approve any modify change to networking. Saved what-if output became the artifact attached to monthly grant-compliance records, replacing spreadsheets that previously listed intended changes without proof.
📈Results & Business Impact
Routine subscription updates moved from twelve approval emails to one preview artifact per rollout.
Unexpected local-resource changes dropped to zero during the first two monthly cycles.
Budget and tag compliance improved from 74 percent to 96 percent across active grants.
Researchers reported fewer fears of automation because planned changes were visible before deployment.
💡Key Takeaway for Glossary Readers
What-if deployment builds trust when central platform teams must change resources owned by many independent groups.
Why use Azure CLI for this?
I use Azure CLI for what-if deployment because the strongest review happens before a pipeline mutates production. After ten years of Azure platform work, I want the preview to run the same way every time: same tenant, scope, template, parameters, mode, and output format. CLI lets me place what-if in pull requests, release gates, and emergency review scripts. It also lets me capture JSON for audit evidence or compare outputs across branches. The portal is useful for learning, but CLI is how teams make what-if a repeatable engineering control instead of an optional final glance in pipelines and shared scripts.
CLI use cases
Run a resource-group what-if preview for a Bicep file before the create command executes.
Run subscription or management-group what-if for landing-zone and governance module changes.
Capture JSON output from what-if and attach it to a pull request or change record.
Compare what-if output between branches to identify unexpected resource additions or deletes.
Fail a release gate when planned changes include delete, replace, or public exposure changes.
Check RBAC because what-if uses deployment permissions similar to a real ARM deployment.
Know whether the deployment uses incremental mode, complete mode, modules, or deployment stacks.
Protect secret parameters and avoid writing sensitive values into public pipeline logs.
Set output format deliberately so reviewers can read the change set without losing raw evidence.
What output tells you
Change types show whether Azure predicts create, modify, delete, ignore, no-change, or unsupported behavior.
Resource IDs and scope show exactly where the template would act if the deployment continued.
Property differences highlight fields that are expected to change, including tags, SKUs, networking, and diagnostics.
Unexpected deletes usually signal complete mode, ownership drift, wrong scope, or a missing resource declaration.
Noisy or unknown values require judgment because some provider properties are resolved only during deployment.
Mapped Azure CLI commands
ARM/Bicep what-if deployment commands
direct
az deployment group what-if --resource-group <resource-group> --template-file main.bicep --parameters @parameters.json
az deployment groupdiscoverManagement and Governance
az deployment sub what-if --location <region> --template-file main.bicep --parameters @parameters.json
az deployment subdiscoverManagement and Governance
az deployment mg what-if --management-group-id <management-group-id> --location <region> --template-file main.bicep
az deployment mgdiscoverManagement and Governance
az deployment tenant what-if --location <region> --template-file main.bicep
az deployment tenantdiscoverManagement and Governance
az deployment group create --resource-group <resource-group> --template-file main.bicep --parameters @parameters.json
az deployment groupsecureManagement and Governance
Architecture context
Architecturally, what-if deployment is the safety checkpoint between source-controlled infrastructure intent and Azure Resource Manager execution. It does not replace design review, policy, template validation, or post-deployment tests, but it ties them together by showing the predicted resource-level delta. In mature platforms, what-if runs in the same pipeline that deploys Bicep modules, landing-zone resources, App Service apps, networking, identities, and diagnostic settings. Reviewers compare the output against the change request and known drift. When complete mode, deployment stacks, policy remediation, or shared resource groups are involved, what-if becomes a guardrail against accidental ownership expansion or resource removal for platform teams.
Security
Security impact is indirect but important. What-if does not enforce access control or encrypt data, yet it exposes security-sensitive changes before they happen. Reviewers can catch a storage account changing public network access, a Key Vault losing purge protection, an App Service disabling HTTPS-only, or an NSG rule opening inbound traffic. The preview output should be treated as change evidence because it can include resource names, IDs, and sensitive architecture details. RBAC still controls who can run deployments and what-if. For production, require least-privilege deployment identities and protect parameter files that contain secrets or references during approval and security review.
Cost
Cost impact is indirect but useful. What-if can reveal SKU upgrades, new instances, additional public IPs, diagnostic settings, private endpoints, redundancy changes, or resources that would be deleted and recreated. Those changes may alter monthly spend even when the template looks routine. It also saves operations cost by preventing rework from bad deployments. However, what-if itself is not a billing optimization tool and may not estimate charges. FinOps teams should use it with cost analysis, budgets, and resource tagging. The best pattern is to flag planned cost-affecting changes before deployment and reconcile actual spend afterward, before monthly budgets are surprised.
Reliability
Reliability impact is indirect because what-if does not keep services running by itself. Its value is preventing reliability mistakes before they ship. A preview can reveal an App Service plan resize, an Availability Zone setting change, removal of diagnostic logs, replacement of a load balancer rule, or deletion risk under complete mode. Teams should review both create and delete operations and subtle property changes that might cause downtime. What-if should be paired with deployment slots, rollback plans, backups, and post-deployment health checks. It reduces surprises in real environments, but it cannot prove application behavior after provider-side changes or data migrations.
Performance
Runtime performance is not directly improved by what-if because it does not run application traffic. The performance benefit is operational: engineers can identify changes that might affect latency, throughput, or capacity before execution. Examples include App Service plan scaling, database SKU changes, cache capacity changes, routing changes, Event Hubs throughput units, or storage redundancy updates. What-if also improves pipeline performance by catching mistakes before a long deployment fails or rolls back. Large templates can produce detailed output, so teams should format and summarize results for reviewers during engineering review without removing important property differences before final release approval with confidence.
Operations
Operators use what-if as a standard preflight check for infrastructure deployments. Common work includes running previews at the correct scope, saving output with the change ticket, comparing planned changes against approved intent, and blocking releases with unexpected deletes or security exposure. During drift cleanup, what-if helps separate deliberate template updates from untracked portal changes. Output should be reviewed by someone who understands the resource types, not just by a pipeline. Teams often filter noisy properties, but they should avoid hiding fields that affect networking, identity, redundancy, diagnostics, cost, or production recovery steps. Review notes should explain any accepted noise or override.
Common mistakes
Running what-if against one parameter file and deploying with another parameter file.
Ignoring scope and reviewing a resource-group preview for a deployment that actually runs at subscription scope.
Treating no template validation errors as proof that the planned changes are safe.
Filtering out delete or network properties because the output is noisy instead of investigating them.
Forgetting that what-if predicts control-plane changes, not application data migrations or runtime behavior.