AWS CloudFormation fundamentals
Write a CloudFormation template for a private, KMS-encrypted audit bucket, lint it locally, deploy it through a reviewed change set, read what happens on rollback, and protect data with deletion policies.
Assumes: CloudFormation (template format 2010-09-09) · cfn-lint 1.60.1 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of this lesson you can:
- Name the sections of a CloudFormation template and say which one is required.
- Use parameters, conditions, intrinsic functions, pseudo parameters and outputs correctly.
- Lint and validate a template locally before it ever reaches an account.
- Create a stack through a change set, read the change set, and explain what
Replacement: Truemeans. - Explain what happens on a failed create, a failed update and a failed rollback, and recover from each.
- Choose between
Delete,RetainandSnapshotdeletion policies, and say whyUpdateReplacePolicyis a separate setting. - Describe the alternatives to a single template: nested stacks, exports and imports, modules, and importing existing resources.
Prerequisites
- Why infrastructure as code
- Module 5: Security: KMS key policies and S3 protections (a key policy is used in this lesson).
- Tools: AWS CLI v2 with the
learn-sandboxprofile, Docker Desktop (forcfn-lint), a text editor.
Why this matters in banking
Every CDK deployment and many Terraform setups end up in CloudFormation, either because the CDK synthesizes it or because AWS services deploy it for you (Control Tower, Service Catalog, SAM). When a Harbourline production deployment fails at 17:40 with UPDATE_ROLLBACK_FAILED, the person who can read the template and the stack events gets the payment service healthy again. The person who only knows the CDK does not know where to look.
CloudFormation also carries the safety features auditors like: change sets (a reviewable diff), stack policies and termination protection (guard rails), deletion policies (keep the data when the stack goes), and drift detection (the next lesson).
The idea in plain language
A template is a YAML or JSON document that lists the resources you want. You give it to CloudFormation, and the service creates a stack: one managed group of those resources. Update the template and CloudFormation works out what to create, change or delete. Delete the stack and CloudFormation deletes the resources (unless you told it to keep some).
Analogy: the template is the architect's drawing set. The stack is the building made from it. A change set is the architect's marked-up revision, circled in red and shown to the client before anyone brings a drill.
CloudFormation keeps the record of which real resources belong to which logical names. You do not host any state file. That is the main practical difference from Terraform.
What problem the service solves
CloudFormation gives you ordered, parallel, retried creation of resources with automatic rollback on failure, and a single place to see every resource a deployment owns. Its limits are worth knowing (checked against the AWS quotas page on 2026-11-18):
| Limit | Value |
|---|---|
| Resources per template | 500 |
| Parameters per template | 200 |
| Outputs per template | 200 |
| Mappings per template | 200 |
| Template body in a request | 51,200 bytes (upload to S3 for up to 1 MB) |
| Stack name length | 128 characters |
| Stacks per account per Region | 2,000 (adjustable) |
When a template grows toward 500 resources, split it by lifecycle (network, data, application). The CDK does this for you if you use several stacks.
CloudFormation can be slower to adopt brand-new features than the raw API, and its error messages can be terse. aws cloudformation describe-stack-events is your friend.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | AWS equivalent | What's different |
|---|---|---|
| ARM template | CloudFormation template | YAML is idiomatic; intrinsic functions such as !Ref and !Sub replace ARM expressions |
| Deployment (incremental mode) | Stack update | The stack owns its resources: removing a resource from the template deletes it |
| Resource group | Stack | A stack is a deployment unit with its own history, tags and permissions |
what-if | Change set | A change set is a stored object you can inspect and then execute |
dependsOn | DependsOn | Most dependencies are implied by !Ref and !GetAtt |
| Template parameters | Parameters | Types include AWS::SSM::Parameter::Value<String> to read a Parameter Store value |
| Deployment stacks (deny settings) | Stack policy, termination protection | Narrower: they protect specific resources or the stack itself |
Architecture
Security-boundary view. The bucket denies any request that is not over TLS, blocks public access at four levels, uses BucketOwnerEnforced ownership (ACLs are disabled), encrypts with a customer managed key whose policy trusts IAM in this account, and logs every access to a second bucket. In production an extra statement forbids permanent deletion of object versions.
The stack lifecycle
A stack that failed its first creation ends in ROLLBACK_COMPLETE and cannot be updated: delete it and start again.
Template anatomy
| Section | Required? | Purpose |
|---|---|---|
AWSTemplateFormatVersion | No | Always "2010-09-09" (the only valid value) |
Description | No | Text shown in the console. Up to 1,024 bytes |
Metadata | No | Extra data, for example console parameter grouping |
Parameters | No | Inputs given at deploy time |
Rules | No | Validate parameter combinations |
Mappings | No | Static lookup tables (for example per-Region values) |
Conditions | No | Booleans from parameters, used to include or skip resources and properties |
Transform | No | Macros such as AWS::Serverless-2016-10-31 (SAM) or AWS::LanguageExtensions |
Resources | Yes | The things to create |
Outputs | No | Values to show or export |
Intrinsic functions you will use every day
| Function | Short form | Meaning |
|---|---|---|
Ref | !Ref X | A parameter's value, or a resource's main ID (bucket name, key ID) |
Fn::GetAtt | !GetAtt X.Arn | A named attribute of a resource |
Fn::Sub | !Sub "arn:${AWS::Partition}:s3:::${Name}" | String templating. Write ${!Literal} to print a literal ${Literal} |
Fn::Join, Fn::Select, Fn::Split | !Join ["-", [a, b]] | String and list helpers |
Fn::If, Fn::Equals, Fn::And, Fn::Or, Fn::Not | !If [Cond, a, b] | Conditions |
Fn::FindInMap | !FindInMap [Map, Key1, Key2] | Read a mapping |
Fn::ImportValue | !ImportValue Name | Read another stack's export |
Pseudo parameters are values CloudFormation supplies: AWS::Region, AWS::AccountId, AWS::StackName, AWS::Partition (aws, aws-cn or aws-us-gov; use it in ARNs instead of typing aws), and AWS::NoValue (removes a property or list item when used inside !If).
Dynamic references read secrets and parameters at deploy time without putting values in the template: {{resolve:secretsmanager:name:SecretString:password}} and {{resolve:ssm:/path}}. A template can contain at most 60 of them. Prefer service features that never expose the secret at all (for example an RDS-managed master password) over dynamic references.
Step-by-step implementation
Create the template file
Create a folder iac-m10/cfn and save the template from the "Complete code" section as audit-bucket.yaml. The same file is used for linting and for every CLI step.
Lint it locally
No account is needed. cfn-lint checks syntax, resource properties and many best practices against the CloudFormation specification.
Create a change set for a new stack
--change-set-type CREATE tells CloudFormation this is the first deployment. Read the change set. Execute it only if it shows what you expect.
Update, break, recover
Change a parameter, read the new change set, then deliberately cause a failure to see rollback behaviour (exercises below).
Tear down
Delete the stack, then handle the retained resources (see "Cost and cleanup").
AWS Console instructions
Console → CloudFormation → Stacks → Create stack → With new resources (standard) → Upload a template file. To update, select the stack and choose Update stack, then Make a direct update or the change-set path. On the stack page, the Events tab shows each resource's progress and any failure reason, Resources lists physical IDs, Change sets lists pending diffs, and Stack actions → Edit termination protection switches that guard on. Console labels change from time to time ⚠ VERIFY against the current console.
AWS CLI
# 1. Lint (Docker, no account needed). In PowerShell use ${PWD} instead of $(pwd -W).
docker run --rm -v "$(pwd -W):/work" -w /work python:3.13-slim \
sh -c "pip install --quiet cfn-lint && cfn-lint audit-bucket.yaml"
# 2. Validate syntax with the service (also free; checks less than cfn-lint)
aws cloudformation validate-template --template-body file://audit-bucket.yaml --profile learn-sandbox
# 3. Create a change set for a NEW stack. Stack-level tags flow to every taggable resource.
aws cloudformation create-change-set --profile learn-sandbox --region us-east-1 \
--stack-name hl-m10-cfn-dev-audit --change-set-name first-deploy --change-set-type CREATE \
--template-body file://audit-bucket.yaml \
--parameters ParameterKey=Environment,ParameterValue=dev \
--tags Key=Project,Value=cea-lab Key=Lab,Value=m10-cfn Key=Environment,Value=learn Key=Owner,Value=<your-name>
aws cloudformation wait change-set-create-complete --profile learn-sandbox \
--stack-name hl-m10-cfn-dev-audit --change-set-name first-deploy
# 4. Read the diff
aws cloudformation describe-change-set --profile learn-sandbox \
--stack-name hl-m10-cfn-dev-audit --change-set-name first-deploy \
--query "Changes[].ResourceChange.[Action,LogicalResourceId,ResourceType,Replacement]" --output table
# 5. Execute and wait
aws cloudformation execute-change-set --profile learn-sandbox \
--stack-name hl-m10-cfn-dev-audit --change-set-name first-deploy
aws cloudformation wait stack-create-complete --profile learn-sandbox --stack-name hl-m10-cfn-dev-audit
# 6. Outputs, and the reason for any failure
aws cloudformation describe-stacks --profile learn-sandbox --stack-name hl-m10-cfn-dev-audit \
--query "Stacks[0].Outputs" --output table
aws cloudformation describe-stack-events --profile learn-sandbox --stack-name hl-m10-cfn-dev-audit \
--query "StackEvents[?ResourceStatus=='CREATE_FAILED'].[LogicalResourceId,ResourceStatusReason]" --output tableBackslashes continue lines in bash. In PowerShell 5.1 end each line with a backtick instead.
aws cloudformation deploy does steps 3 to 5 in one command (create or update, change set, execute). Use it in scripts; use the long form when you want to stop and read the change set. deploy --no-execute-changeset also stops after creating the change set.
Reading a change set
Each entry has an Action: Add, Modify, Remove, Import or Dynamic. For Modify, Replacement tells you the impact:
| Replacement | Meaning |
|---|---|
False | Updated in place |
True | A new resource is created and the old one is deleted. Data on the old one is gone unless a policy keeps it |
Conditional | Depends on which property changed. Read the Details |
Always look for Remove and Replacement: True on databases, buckets, keys and anything with data. That one habit prevents most production incidents.
Infrastructure as Code
CloudFormation is the engine, so this section shows how the other two tools relate to it.
The CDK produces templates like this one. You can also include an existing template in a CDK app and migrate it piece by piece. CfnInclude loads the YAML as L1 constructs (it lives in the Amazon.CDK.CloudFormation.Include namespace of the Amazon.CDK.Lib package; this snippet was compiled with Amazon.CDK.Lib 2.277.0):
using Amazon.CDK;
using Amazon.CDK.CloudFormation.Include;
using Constructs;
public sealed class LegacyStack : Stack
{
public LegacyStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
{
_ = new CfnInclude(this, "Legacy", new CfnIncludeProps
{
TemplateFile = "cfn/audit-bucket.yaml",
Parameters = new Dictionary<string, object> { ["Environment"] = "dev" },
});
}
}The next lessons rebuild this bucket as native CDK constructs. cdk synth then prints a template close to the one in this lesson.
Complete code
Save as audit-bucket.yaml. It creates a customer managed KMS key with an alias, a server-access-log bucket, the audit bucket and their bucket policies. The template passes cfn-lint 1.60.1 with no findings.
AWSTemplateFormatVersion: "2010-09-09"
Description: >-
Harbourline audit-evidence bucket: private, versioned, encrypted with a customer managed KMS key,
TLS only, with server access logs. Module 10, lesson 2.
Parameters:
Environment:
Type: String
Default: dev
AllowedValues: [dev, test, prod]
Description: Environment name. Used in resource names.
NoncurrentVersionDays:
Type: Number
Default: 90
MinValue: 30
MaxValue: 3650
Description: Days to keep old object versions before they expire.
Conditions:
IsProd: !Equals [!Ref Environment, prod]
Resources:
DataKey:
Type: AWS::KMS::Key
DeletionPolicy: Retain
UpdateReplacePolicy: Retain
Properties:
Description: !Sub "Harbourline ${Environment}: encrypts the audit-evidence bucket"
EnableKeyRotation: true
PendingWindowInDays: 7
KeyPolicy:
Version: "2012-10-17"
Statement:
- Sid: EnableIamPoliciesInThisAccount
Effect: Allow
Principal:
AWS: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:root"
Action: "kms:*"
Resource: "*"
DataKeyAlias:
Type: AWS::KMS::Alias
Properties:
AliasName: !Sub "alias/hl-m10-cfn-${Environment}-audit"
TargetKeyId: !Ref DataKey
AccessLogBucket:
Type: AWS::S3::Bucket
DeletionPolicy: Retain
UpdateReplacePolicy: Retain
Properties:
BucketName: !Sub "hl-m10-cfn-${Environment}-logs-${AWS::AccountId}-${AWS::Region}"
BucketEncryption:
ServerSideEncryptionConfiguration:
- ServerSideEncryptionByDefault:
SSEAlgorithm: AES256
PublicAccessBlockConfiguration:
BlockPublicAcls: true
BlockPublicPolicy: true
IgnorePublicAcls: true
RestrictPublicBuckets: true
OwnershipControls:
Rules:
- ObjectOwnership: BucketOwnerEnforced
LifecycleConfiguration:
Rules:
- Id: ExpireAccessLogs
Status: Enabled
ExpirationInDays: 90
AccessLogBucketPolicy:
Type: AWS::S3::BucketPolicy
Properties:
Bucket: !Ref AccessLogBucket
PolicyDocument:
Version: "2012-10-17"
Statement:
- Sid: DenyInsecureTransport
Effect: Deny
Principal: "*"
Action: "s3:*"
Resource:
- !GetAtt AccessLogBucket.Arn
- !Sub "${AccessLogBucket.Arn}/*"
Condition:
Bool:
"aws:SecureTransport": "false"
- Sid: AllowS3ServerAccessLogDelivery
Effect: Allow
Principal:
Service: logging.s3.amazonaws.com
Action: "s3:PutObject"
Resource: !Sub "${AccessLogBucket.Arn}/audit-bucket/*"
Condition:
StringEquals:
"aws:SourceAccount": !Ref "AWS::AccountId"
ArnLike:
# Built from the name, not with GetAtt, to avoid a circular dependency with AuditBucket.
"aws:SourceArn": !Sub "arn:${AWS::Partition}:s3:::hl-m10-cfn-${Environment}-audit-${AWS::AccountId}-${AWS::Region}"
AuditBucket:
Type: AWS::S3::Bucket
DeletionPolicy: Retain
UpdateReplacePolicy: Retain
DependsOn: AccessLogBucketPolicy
Properties:
BucketName: !Sub "hl-m10-cfn-${Environment}-audit-${AWS::AccountId}-${AWS::Region}"
BucketEncryption:
ServerSideEncryptionConfiguration:
- BucketKeyEnabled: true
ServerSideEncryptionByDefault:
SSEAlgorithm: aws:kms
KMSMasterKeyID: !GetAtt DataKey.Arn
PublicAccessBlockConfiguration:
BlockPublicAcls: true
BlockPublicPolicy: true
IgnorePublicAcls: true
RestrictPublicBuckets: true
OwnershipControls:
Rules:
- ObjectOwnership: BucketOwnerEnforced
VersioningConfiguration:
Status: Enabled
LoggingConfiguration:
DestinationBucketName: !Ref AccessLogBucket
LogFilePrefix: audit-bucket/
LifecycleConfiguration:
Rules:
- Id: ExpireOldVersions
Status: Enabled
NoncurrentVersionExpiration:
NoncurrentDays: !Ref NoncurrentVersionDays
- Id: AbortIncompleteUploads
Status: Enabled
AbortIncompleteMultipartUpload:
DaysAfterInitiation: 7
AuditBucketPolicy:
Type: AWS::S3::BucketPolicy
Properties:
Bucket: !Ref AuditBucket
PolicyDocument:
Version: "2012-10-17"
Statement:
- Sid: DenyInsecureTransport
Effect: Deny
Principal: "*"
Action: "s3:*"
Resource:
- !GetAtt AuditBucket.Arn
- !Sub "${AuditBucket.Arn}/*"
Condition:
Bool:
"aws:SecureTransport": "false"
# In prod, nobody may permanently delete an object version. (S3 Object Lock is the stronger control.)
- !If
- IsProd
- Sid: DenyPermanentDeletes
Effect: Deny
Principal: "*"
Action: "s3:DeleteObjectVersion"
Resource: !Sub "${AuditBucket.Arn}/*"
- !Ref AWS::NoValue
Outputs:
BucketName:
Description: Audit-evidence bucket name
Value: !Ref AuditBucket
LogBucketName:
Description: Server access log bucket name
Value: !Ref AccessLogBucket
KeyArn:
Description: Customer managed key that encrypts the audit bucket
Value: !GetAtt DataKey.Arn
Export:
Name: !Sub "${AWS::StackName}-KeyArn"Code explained line by line
Grouped by block.
Parameters.EnvironmenthasAllowedValues, so CloudFormation rejectsstagingbefore creating anything.NoncurrentVersionDayshasMinValueandMaxValue, which turns a typo such as3into a validation error instead of an accidental retention change.Conditions.IsProdis a named boolean built with!Equals. Conditions are evaluated at deploy time and can gate whole resources (Condition: IsProdon a resource) or single list items (as with!Ifin the bucket policy).DataKey.EnableKeyRotation: truerotates the key material yearly.PendingWindowInDays: 7is the shortest waiting period KMS allows before a key is really deleted. The key-policy statement witharn:${AWS::Partition}:iam::${AWS::AccountId}:rootmeans "IAM policies in this account decide who can use the key". Without a statement like it, nobody could use the key through IAM.DeletionPolicy: RetainandUpdateReplacePolicy: Retainkeep the key when the stack is deleted or an update would replace it, because data encrypted with a lost key is gone. cfn-lint rule W3011 warns when only one of the two is set (it did on this lesson's first draft).DataKeyAlias. An alias is a friendly name. It is a separate resource and is not retained, so deleting the stack frees the name.AccessLogBucketand its policy. S3 server access logs cannot use a KMS-encrypted destination, so this bucket usesAES256. The policy lets only the S3 logging service write into theaudit-bucket/prefix, and only for requests from this account and the audit bucket's ARN. The 90-day lifecycle rule stops logs piling up.AuditBucket.DependsOn: AccessLogBucketPolicymakes CloudFormation finish the log bucket's policy first, because S3 checks the permission when logging is switched on.BucketKeyEnabled: truemakes S3 use a bucket-level data key, which cuts the number of KMS calls (and the cost) a lot.OwnershipControlswithBucketOwnerEnforceddisables ACLs. Both policies areRetain: evidence must not vanish with a stack.- The circular-dependency trick. The log bucket policy needs the audit bucket's ARN, and the audit bucket depends on the log bucket policy. A
!GetAttwould create a cycle, so the ARN is rebuilt with!Subfrom the same name pattern. Whenever CloudFormation reports "Circular dependency between resources", look for a!Refor!GetAttpair like this. AuditBucketPolicyand the!If. The deny-insecure-transport statement applies everywhere. The second list item exists only in prod:!If [IsProd, {statement}, !Ref AWS::NoValue]drops the item when the condition is false.OutputsandExport. Outputs show values after deployment. An export makes a value importable by other stacks in the same Region and account with!ImportValue. Exports create a hard dependency: you cannot change or delete an exported value while another stack imports it. For loosely coupled stacks, publish values to Parameter Store instead.
Security considerations
⚠ Learning shortcut — not for production
The lab uses Retain and manual cleanup so that you see how deletion policies behave. In production the audit bucket would also use S3 Object Lock (compliance or governance mode) for WORM retention, a key policy that separates key administrators from key users, replication to a second Region, and a pipeline role as the only identity allowed to change the stack. The prod-only DenyPermanentDeletes statement is a simple guard rail, not a legal-hold control.
- Never put secret values in
Parameters. Parameter values are visible in the console and API unless you setNoEcho: true, andNoEchoonly masks the display. Use Secrets Manager references. - Stack policies restrict which resources an update may touch. Termination protection stops
DeleteStack. Turn it on for production stacks:aws cloudformation update-termination-protection --enable-termination-protection --stack-name <name>. - Capabilities. If a template creates IAM resources the CLI asks for
--capabilities CAPABILITY_IAM(orCAPABILITY_NAMED_IAMwhen you name them). That flag is a deliberate speed bump: a reviewer should look at every IAM change. - CloudFormation Hooks can block non-compliant resources at deployment (for example, unencrypted buckets). They are covered with the other scanners in Policy-as-code and secure deployment.
- The deploy identity needs permission to create every resource in the template. That is usually broad. Give it to a pipeline role (or a CloudFormation service role passed with
--role-arn) and let humans have read access only.
Deletion and update policies
| Policy | Applies to | Effect when the stack (or resource) is deleted |
|---|---|---|
Delete | Most resources (the default) | Resource is deleted. A non-empty S3 bucket fails to delete |
Retain | Any resource | Resource is kept and removed from the stack. You own it from then on |
RetainExceptOnCreate | Any resource | Retained on later deletes, but deleted if the creation rolled back (stops orphans from failed first deploys) |
Snapshot | Supported types such as AWS::RDS::DBInstance and AWS::EC2::Volume | A snapshot is taken, then the resource is deleted. The snapshot is billed until you delete it |
UpdateReplacePolicy takes Delete, Retain or Snapshot and applies when an update replaces the resource (a new one is created and the old one removed). A replacement can happen without any deletion of the stack, so the two policies are independent. For stateful resources set both.
⚠ VERIFY the list of resource types that support Snapshot and the exact behaviour of RetainExceptOnCreate in the CloudFormation documentation before you rely on them in a runbook.
Rollback behaviour
- Create fails. CloudFormation deletes what it created and leaves the stack in
ROLLBACK_COMPLETE. You cannot update it. Rundelete-stack, fix the template, create again. Resources withDeletionPolicy: Retaincreated before the failure stay behind, so a retried deployment can fail with "already exists".RetainExceptOnCreateexists for that reason. - Update fails. CloudFormation returns to the previous template:
UPDATE_ROLLBACK_COMPLETE. The stack works and can be updated again. - Rollback fails.
UPDATE_ROLLBACK_FAILED(for example a resource was changed by hand so that its old state cannot be restored). Fix the cause, thenaws cloudformation continue-update-rollback --stack-name <name>. If a resource cannot be fixed, add--resources-to-skip <LogicalId>, then bring the template in line afterwards. - Debugging.
aws cloudformation create-stack --on-failure DO_NOTHING(or--disable-rollback) keeps the failed resources so you can inspect them. Never use it in production pipelines; you pay for the leftovers. - Rollback triggers. A stack can name CloudWatch alarms. If one goes into alarm during the update window, CloudFormation rolls the update back. Useful for ECS and Lambda deployments.
Reuse: nested stacks, exports, modules, import
| Mechanism | What it is | When to use | Watch out for |
|---|---|---|---|
Nested stacks (AWS::CloudFormation::Stack) | A parent template that deploys child templates from S3 | Break a large template into parts, reuse a pattern | Updates happen through the parent; keep nesting shallow |
Exports and Fn::ImportValue | Share values across stacks in an account and Region | A shared network exporting subnet IDs | Hard dependency; an export in use cannot be changed |
| Cross-stack parameters | Pass values by hand or by pipeline | Looser coupling | Someone must wire it |
| CloudFormation modules | Registered, versioned resource bundles | A central team publishes an approved pattern | Registry limits and versioning discipline |
Transform: AWS::LanguageExtensions | Adds functions such as Fn::ForEach for loops | Repeated similar resources | Extra transform step in change sets ⚠ VERIFY current function list |
| Resource import | Bring an existing resource under a stack (--change-set-type IMPORT) | Adopt hand-built resources | The template must match the resource, and the resource needs a DeletionPolicy |
Resource import is the bridge from "built by hand" to "under code": write the template for the existing bucket with DeletionPolicy: Retain, create an IMPORT change set with --resources-to-import, review it and execute it.
Banking use case
Harbourline's audit-evidence bucket holds exported ledger extracts for regulators. The platform team keeps this template in the landing repository. Developers may change parameters through a pull request. A change to the KMS key policy needs a security-team approval enforced by a CODEOWNERS rule. Every deployment goes through a change set whose JSON is attached to the pull request, so the approver reads "Modify AuditBucket, Replacement False" and not a vague description. The two Retain policies mean even a mistaken stack deletion leaves the evidence intact.
Common mistakes
- Skipping the change set and updating directly. A direct update hides
Replacement: Trueuntil it is too late. - Renaming a logical ID. CloudFormation sees "delete old, create new". For stateful resources this destroys data. Avoid renaming, or protect the resource with
Retainand import it under the new name. - Hard-coding
BucketNameand then being unable to create a second copy of the stack. Use!Subwith the account and Region, as here. - Forgetting
UpdateReplacePolicy. A property change that forces replacement deletes the old bucket's data even thoughDeletionPolicyisRetain. - Cycles from
!GetAttpairs. Build ARNs from names with!Subwhere needed. - Using
NoEchoas a secret store. It only masks output. - Putting everything in one template. Hitting 500 resources is the symptom; slow updates and a huge blast radius are the cost.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
ValidationError: Template format error | YAML indentation or an unknown intrinsic function | Run cfn-lint; check that list items align |
ROLLBACK_COMPLETE, cannot update | First creation failed | delete-stack, fix, create again; read the failed event reason first |
AlreadyExists for the bucket | Name taken (a retained bucket from a previous run, or another account) | Delete the retained bucket or change the name pattern |
Circular dependency between resources | Two resources reference each other through !Ref or !GetAtt | Break the loop with a name built by !Sub |
Export ... cannot be deleted as it is in use by ... | Another stack imports the value | Remove the import first, or stop using exports |
UPDATE_ROLLBACK_FAILED | A resource changed outside CloudFormation blocks the rollback | Fix the resource, run continue-update-rollback, skip as a last resort |
AccessDenied creating the bucket policy | Account-level Block Public Access or an SCP blocks the action | Check Organization SCPs and the account's S3 settings |
| Template too large | Over 51,200 bytes in --template-body | Upload to S3 and use --template-url, or split the template |
Cost and cleanup
Cost: credits. CloudFormation is free. The customer managed KMS key costs about 1 US dollar per month, prorated hourly (⚠ VERIFY current KMS pricing), and S3 charges are cents for an empty bucket. Keep the key for under an hour and schedule its deletion. Everything else is free.
The stack deletion retains the key and both buckets by design, so cleanup has three steps. Read the key ID first, because the alias disappears with the stack.
# 1. Remember the key ID (the alias is deleted with the stack)
KEY_ID=$(aws kms describe-key --key-id alias/hl-m10-cfn-dev-audit --profile learn-sandbox \
--query KeyMetadata.KeyId --output text)
# 2. Delete the stack
aws cloudformation delete-stack --profile learn-sandbox --stack-name hl-m10-cfn-dev-audit
aws cloudformation wait stack-delete-complete --profile learn-sandbox --stack-name hl-m10-cfn-dev-audit
# 3. Schedule the retained key for deletion (7 days is the minimum)
aws kms schedule-key-deletion --key-id "$KEY_ID" --pending-window-in-days 7 --profile learn-sandboxEmpty and delete the two retained buckets (PowerShell; it removes object versions and delete markers):
$account = aws sts get-caller-identity --profile learn-sandbox --query Account --output text
foreach ($name in "hl-m10-cfn-dev-audit-$account-us-east-1", "hl-m10-cfn-dev-logs-$account-us-east-1") {
$v = aws s3api list-object-versions --bucket $name --profile learn-sandbox --output json | ConvertFrom-Json
foreach ($x in @($v.Versions) + @($v.DeleteMarkers)) {
if ($x) { aws s3api delete-object --bucket $name --key $x.Key --version-id $x.VersionId --profile learn-sandbox | Out-Null }
}
aws s3api delete-bucket --bucket $name --profile learn-sandbox
}Verify nothing is left:
aws resourcegroupstaggingapi get-resources --profile learn-sandbox --region us-east-1 \
--tag-filters Key=Lab,Values=m10-cfn --query "ResourceTagMappingList[].ResourceARN"The key may still be listed until its deletion date, in state PendingDeletion; that is expected, and a key pending deletion is not billed ⚠ VERIFY on the KMS pricing page.
Exercises
- 🟢 Guided: lint the template, create the stack through a change set, read every row of the change set, execute it, and print the outputs. Then change
NoncurrentVersionDaysto120with a second change set (--change-set-type UPDATE, same template,ParameterKey=NoncurrentVersionDays,ParameterValue=120) and confirmReplacementisFalse. - 🟡 Challenge: add a
DataClassparameter (allowed valuespublic,internal,confidential) and a bucket tag that uses it. Add a Rule so thatconfidentialis only accepted whenEnvironmentisprodortest. Lint, then show the change set. - 🔴 Live problem: the audit bucket was created by hand last year, and now an auditor wants it "under change control" without touching the data. You may not recreate it. Plan and perform the import into a new stack. List the risks and your rollback.
Assignment
Add the template and a short README.md to your portfolio repository under cfn/audit-bucket/. The README states the controls (encryption, TLS, public access block, logging, retention), the parameters, the deletion behaviour and the exact deploy and teardown commands.
Solutions
The first change set shows Add rows for DataKey, DataKeyAlias, AccessLogBucket, AccessLogBucketPolicy, AuditBucket and AuditBucketPolicy, each with Replacement empty (new resources have nothing to replace). The update from 90 to 120 days shows a single Modify on AuditBucket with Replacement: False, because lifecycle rules can be changed in place. The point of reading it is the habit: you check for Remove and Replacement: True before executing.
Add the parameter with AllowedValues. Add a Rules section: a rule named ConfidentialNeedsProdOrTest with RuleCondition: !Equals [!Ref DataClass, confidential] and Assertions containing Assert: !Contains [[prod, test], !Ref Environment] plus an AssertDescription. Add Tags with a DataClass key to the bucket. Rules run before any resource is touched, so a bad combination fails in seconds. A condition alone cannot reject a combination; it only chooses what to include.
Write a template that describes the existing bucket exactly: name, encryption, versioning, logging, policy, with DeletionPolicy: Retain. Run create-change-set --change-set-type IMPORT --resources-to-import ... with the bucket's physical name. Review: the only action should be Import. Execute, then run drift detection to confirm the stack and the bucket agree. Risks: a mismatching property makes the next update modify the live bucket (so describe what exists first, then change things in a second step); import supports particular resource types only; the bucket policy may be a separate resource you must import too. Rollback: because of Retain, deleting the new stack leaves the bucket untouched.
Knowledge check
Answer: Resources. Everything else is optional. AWSTemplateFormatVersion is optional and, if present, must be 2010-09-09.
Answer: CloudFormation will create a new database and delete the old one, so data is lost unless a policy keeps it. Stop, find which property forces replacement, and either avoid that change, take a backup and plan a migration, or make sure UpdateReplacePolicy: Snapshot (or Retain) is set.
Answer: No. Delete the stack, fix the template and create it again. A stack in ROLLBACK_COMPLETE only supports deletion.
Answer: DeletionPolicy acts when the resource or stack is deleted. UpdateReplacePolicy acts when an update replaces the resource (new one in, old one out). A replacement is not a stack deletion, so both are needed to protect data in both situations.
Answer: The template then works unchanged in other partitions such as aws-cn or aws-us-gov, and it avoids a hard-coded assumption that scanners flag.
Answer: When you expect to change the exported value often. An export in use cannot be modified or deleted, so it ties stacks together. Use Parameter Store or pass values through the pipeline for loose coupling.
Interview questions
- "A stack is stuck in UPDATE_ROLLBACK_FAILED. What do you do?" Read the stack events for the failed resource, fix the cause out of band if a manual change blocks the rollback, run
continue-update-rollback, and skip the resource only as a last resort. Then correct the template so it matches reality and add the missing guard rail. - "How do you stop a production database from being deleted by a stack update?"
DeletionPolicyandUpdateReplacePolicyset toSnapshotorRetain, termination protection, a stack policy that deniesUpdate:ReplaceandUpdate:Deleteon that resource, RDS deletion protection, and a mandatory change-set review. - "Change set or direct update?" A change set for anything shared. A direct update is acceptable only for disposable stacks.
- "How would you bring a hand-built resource under CloudFormation?" Write a matching template with
Retain, create an IMPORT change set, review and execute, then run drift detection.
Certification practice
A CloudFormation update is about to modify an Amazon RDS instance property that requires replacement. The team must avoid data loss and see the impact before anything changes. Which combination should they use?
A. Run update-stack directly and watch the events.
B. Create a change set to review Replacement, and set UpdateReplacePolicy: Snapshot on the instance.
C. Set DeletionPolicy: Delete and take a manual snapshot afterwards.
D. Disable rollback so the old instance stays.
Answer: B. The change set shows the replacement in advance, and UpdateReplacePolicy: Snapshot preserves the data of the replaced instance. A applies immediately. C uses the wrong policy and takes the snapshot too late. D keeps failed resources but does not protect a replaced instance.
A stack update fails and the stack shows UPDATE_ROLLBACK_FAILED because someone deleted a security group manually. The operator needs the stack usable again. What is the best first action?
A. Delete the stack and rebuild.
B. Recreate or fix the missing security group, then run continue-update-rollback.
C. Create a new stack with the same name.
D. Run update-stack with the original template.
Answer: B. Fix the cause, then continue the rollback. A destroys data and is rarely needed. C is not possible while the stack exists. D is not allowed in this state: only continue-update-rollback or deletion work.
A central team wants every application team to deploy an approved VPC pattern, versioned and centrally maintained, while hiding the implementation. Which CloudFormation capability fits best?
A. Copy the template into each team's repository. B. A registered CloudFormation module (or a Service Catalog product) published by the central team. C. Exports from a single shared stack for every property. D. Each team writes its own template from a wiki page.
Answer: B. A versioned module or a Service Catalog product gives controlled reuse. A and D drift apart. C couples all consumers to one stack, and exports cannot change while imported.
Completion checklist
- I linted the template and fixed every finding
- I created the stack through a change set and read it
- I can explain
Replacement: Trueand the two policies - I can describe recovering from
ROLLBACK_COMPLETEandUPDATE_ROLLBACK_FAILED - I deleted the stack, emptied and deleted the two buckets, scheduled the key for deletion, and confirmed nothing is billing
Key takeaways
- A template describes; a stack is the managed result; a change set is the safe preview.
Retainkeeps data and hands you the cleanup; pairDeletionPolicywithUpdateReplacePolicyfor stateful resources.- Read change sets for
RemoveandReplacement: True. - Lint locally with
cfn-lint; it is free, fast and catches real mistakes. - The CDK produces this same format, so everything here still applies when you stop writing YAML.
Related lessons and next steps
- Previous: Why infrastructure as code
- Next: Drift detection and StackSets
- Also see: AWS CDK in C#: first stack
Further reading
Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.
Why infrastructure as code
Explain why a bank builds AWS environments from reviewed code instead of console clicks, name the three tools you will use in this module, and run a read-only inventory that shows how much of an account is not under code.
Drift detection and StackSets
Find out when someone has changed a deployed resource outside code, report it with a tested C# tool, fix it safely with drift-aware change sets, and design a StackSet that rolls a security baseline out to every account and Region.