**StackSets** extend CloudFormation to deploy the same template across **multiple AWS accounts and Regions** in a single operation. They are the primitive AWS provides for landing-zone governance: rolling out a baseline (logging, IAM roles, security guardrails) to dozens or hundreds of member accounts at once. ## The mental model ``` Administrator account └── StackSet "guardrails-baseline" (regional resource — lives in one region) ├── Stack instance: Account A, us-east-1 → Stack ├── Stack instance: Account A, eu-west-1 → Stack ├── Stack instance: Account B, us-east-1 → Stack └── Stack instance: Account C, us-east-1 → Stack (FAILED creation, instance still exists) ``` Three layers: - **StackSet** — the container, holds the template + deployment configuration - **Stack instance** — a reference to a stack in a specific account+region; one StackSet has many - **Stack** — the actual CFN stack in the target account, just like any other stack ## Key terminology | Term | Meaning | |------|---------| | **Administrator account** | The account where the StackSet is created and managed. Either the management account (service-managed) or any account you choose (self-managed). | | **Target account** | An account where stacks are deployed. Must have a trust relationship with the admin account. | | **Stack instance** | The metadata link between a StackSet and a stack in a target account+region. Can exist *without* an underlying stack (e.g., create failed). | | **StackSet operation** | An action that affects all (or a subset of) stack instances: Create / Update / Delete. | ## StackSet is a regional resource The StackSet itself lives in **one region** of the administrator account, even though it can deploy to many regions. To list a StackSet you must be in the right region in the console / CLI. This is a common pitfall — "I can't find my StackSet" usually means you're in the wrong region. The stacks the StackSet creates can be in any combination of accounts × regions; the StackSet metadata that orchestrates them is single-region. ## Operations | Operation | What it does | |-----------|--------------| | **Create StackSet** | Define the template + target accounts + regions; deploy initial stacks | | **Update StackSet** | Push template/parameter changes to **all** stack instances. Can also add new accounts or regions to the StackSet's scope. | | **Delete stacks** | Remove stacks from some accounts/regions but keep the StackSet | | **Delete StackSet** | Removes the StackSet itself; all stack instances must be removed first | **Critical constraint on Update**: > Your template updates always affect all stacks; you can't selectively update the template for some stacks in the StackSet, but not others. To vary behavior per instance, use **parameter overrides** (set per account/region) — never branch templates per instance. ## Stack instances can exist without stacks This is unique to StackSets. If a stack create operation fails in a target account, the **stack instance record persists** in the StackSet — but no actual stack exists in the target account. The instance shows the failure reason. You can retry by re-running the StackSet create operation; the instance will attempt creation again. This is why stack instances have their own status code (`CURRENT`, `OUTDATED`, `INOPERABLE`, `FAILED`, `PENDING`, etc.) separate from underlying stack status. ## Status codes **StackSet operation level**: | Status | Meaning | |--------|---------| | `RUNNING` | Operation in progress | | `SUCCEEDED` | Completed without exceeding failure tolerance | | `FAILED` | Failure tolerance exceeded; remaining regions cancelled | | `QUEUED` | (service-managed only) Waiting for previous operations on same target | | `STOPPING` / `STOPPED` | Manual stop | **Stack instance level**: | Status | Meaning | |--------|---------| | `CURRENT` | Stack matches StackSet's current state | | `OUTDATED` | Last create/update on this instance failed or was stopped | | `INOPERABLE` | DeleteStackInstances failed; instance stuck — must `RetainStacks=true` then delete manually | | `CANCELLED` | Operation aborted (failure tolerance exceeded, or user stopped) | | `FAILED` / `FAILED_IMPORT` | Operation failed for this specific instance | | `PENDING` / `RUNNING` / `SUCCEEDED` | Standard lifecycle | | `SKIPPED_SUSPENDED_ACCOUNT` | Target account was suspended at operation time | ## Tags Tags applied to a StackSet flow down to **all stacks and their resources**. This is the canonical way to apply organizational tagging (cost center, business unit) at scale. **Don't prefix tag keys with `aws:`** — that's reserved. ## Relation to nested stacks Nested stacks and StackSets are sometimes confused. They solve different problems: | | Nested stacks | StackSets | |---|---------------|-----------| | Scope | One account, one region | Many accounts, many regions | | Composition | Hierarchy of stacks under one root | Flat set of stack instances | | Update model | Update root → propagates | Update StackSet → propagates to all instances | | Per-instance variation | Via parent passing different parameters per nested stack | Via parameter overrides per stack instance | | Identity | One root stack ID covers all | Separate stack IDs per target account+region | You can use them together: a StackSet's template can itself contain nested stacks. Common pattern for landing zones. ## Related - [[CFN Nested Stacks Hierarchical Composition]] - [[CFN StackSet Permission Models Self-Managed vs Service-Managed]] - [[CFN StackSet Deployment Controls]] - [[CFN Stack Concept]]