---
cuppy_hub: azure
cuppy_path: reference/arm/deployment-stacks.md
cuppy_section: docs
cuppy_doc: 46WD-SV5E
cuppy_doc_uuid: 0f8accd0-fb36-4264-af87-8bcedc1ff115
cuppy_permalink: https://cuppy.io/azure/d/46WD-SV5E
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/azure/docs/reference/arm/deployment-stacks
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 23ace33fc1e37d56a6f344c62bcb53ed152e27b264162cb05ace72eef578a722
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Deployment stacks

**A deployment stack is a resource that remembers which resources a Bicep file created, so an update can delete what you removed from the file and a deny assignment can stop others changing what you deployed.** Microsoft recommends stacks over complete mode, which it is gradually deprecating.

## Create or update

```
az stack group create --name orders --resource-group rg-orders \
  --template-file main.bicep --parameters main.bicepparam \
  --action-on-unmanage detachAll --deny-settings-mode none

az stack sub create --name orders --location eastus2 \
  --template-file main.bicep --action-on-unmanage deleteResources \
  --deny-settings-mode denyDelete --deny-settings-excluded-principals <pipeline-object-id>
```

Both flags are required on create and update.

| `--action-on-unmanage` | When a resource leaves the file (or the stack is deleted) |
|---|---|
| `detachAll` | Resources and resource groups stay; the stack stops tracking them. Safest default |
| `deleteResources` | Resources are deleted; resource groups are detached |
| `deleteAll` | Resources **and** resource groups are deleted |

`--resources-without-delete-support detach|fail` decides what happens to resources the stack can't delete. Key Vault secrets are one: a stack can't delete them, so detach them.

| `--deny-settings-mode` | Blocks for everyone not excluded |
|---|---|
| `none` | Nothing |
| `denyDelete` | Deletes |
| `denyWriteAndDelete` | Updates and deletes |

Exclude your deployment identity with `--deny-settings-excluded-principals`, or exclude specific operations with `--deny-settings-excluded-actions` (up to 200). `--deny-settings-apply-to-child-scopes` extends the deny to child resources (a SQL server's databases). The deny is a **deny assignment**: it beats any role, which is why a protected resource answers 403 to an Owner (`guides/identity/fix-access-denied.md`).

## Roles

- **Azure Deployment Stack Contributor:** manage stacks, but not create or delete their deny assignments.
- **Azure Deployment Stack Owner:** manage stacks including deny assignments.

Enforcement of `Microsoft.Resources/deploymentStacks/manageDenySetting/action` is rolling out across regions. Expect a Contributor-level identity to fail on deny settings it used to set.

## Limits and known gaps

- 800 stacks per scope; 2,000 deny assignments per scope.
- Resources created implicitly by another resource aren't managed: no cleanup, no deny.
- Deny assignments don't support tags, and aren't supported at management-group scope (a management-group stack targeting subscriptions works).
- **A resource-group-scope stack doesn't protect its own resource group.** Deleting the group deletes everything despite the deny settings. Deploy the stack at **subscription** scope with the group in the file, or add a lock.
- **Moving a managed resource to another group removes its protection.** Deny assignments are evaluated at group scope for moves.
- `--bypass-stack-out-of-sync-error` (`--bse`) exists for when the stack's resource list no longer matches Azure: use it only after checking what changed outside the stack.

## Preview

Stack what-if is a separate command, and its result is a resource you name (`Microsoft.Resources/deploymentStacksWhatIfResults`) that shows what would be created, changed, detached or deleted:

```
az stack-whatif group create --name orders-preview --resource-group rg-orders \
  --stack-id <stack-resource-id> --template-file main.bicep \
  --action-on-unmanage deleteResources --deny-settings-mode none --retention-interval PT3H
az stack-whatif group show --name orders-preview --resource-group rg-orders
```

The stack doesn't have to exist yet. Run a preview before switching `--action-on-unmanage` to a delete mode.

## Next

Redeploy patterns and known-bad configurations: `patterns/bicep-idempotent-redeploy.md`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 107 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/azure/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->