Skip to Content
Cloud Engineering Academy
10. Infrastructure as Code

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.

intermediate⏱ 2 h 30 min🟡 Low costDOP-C02SOA-C03

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: True means.
  • Explain what happens on a failed create, a failed update and a failed rollback, and recover from each.
  • Choose between Delete, Retain and Snapshot deletion policies, and say why UpdateReplacePolicy is a separate setting.
  • Describe the alternatives to a single template: nested stacks, exports and imports, modules, and importing existing resources.

Prerequisites

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):

LimitValue
Resources per template500
Parameters per template200
Outputs per template200
Mappings per template200
Template body in a request51,200 bytes (upload to S3 for up to 1 MB)
Stack name length128 characters
Stacks per account per Region2,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 equivalentWhat's different
ARM templateCloudFormation templateYAML is idiomatic; intrinsic functions such as !Ref and !Sub replace ARM expressions
Deployment (incremental mode)Stack updateThe stack owns its resources: removing a resource from the template deletes it
Resource groupStackA stack is a deployment unit with its own history, tags and permissions
what-ifChange setA change set is a stored object you can inspect and then execute
dependsOnDependsOnMost dependencies are implied by !Ref and !GetAtt
Template parametersParametersTypes include AWS::SSM::Parameter::Value<String> to read a Parameter Store value
Deployment stacks (deny settings)Stack policy, termination protectionNarrower: 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

SectionRequired?Purpose
AWSTemplateFormatVersionNoAlways "2010-09-09" (the only valid value)
DescriptionNoText shown in the console. Up to 1,024 bytes
MetadataNoExtra data, for example console parameter grouping
ParametersNoInputs given at deploy time
RulesNoValidate parameter combinations
MappingsNoStatic lookup tables (for example per-Region values)
ConditionsNoBooleans from parameters, used to include or skip resources and properties
TransformNoMacros such as AWS::Serverless-2016-10-31 (SAM) or AWS::LanguageExtensions
ResourcesYesThe things to create
OutputsNoValues to show or export

Intrinsic functions you will use every day

FunctionShort formMeaning
Ref!Ref XA parameter's value, or a resource's main ID (bucket name, key ID)
Fn::GetAtt!GetAtt X.ArnA 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 NameRead 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 table

Backslashes 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:

ReplacementMeaning
FalseUpdated in place
TrueA new resource is created and the old one is deleted. Data on the old one is gone unless a policy keeps it
ConditionalDepends 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.

audit-bucket.yaml
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.

  1. Parameters. Environment has AllowedValues, so CloudFormation rejects staging before creating anything. NoncurrentVersionDays has MinValue and MaxValue, which turns a typo such as 3 into a validation error instead of an accidental retention change.
  2. Conditions. IsProd is a named boolean built with !Equals. Conditions are evaluated at deploy time and can gate whole resources (Condition: IsProd on a resource) or single list items (as with !If in the bucket policy).
  3. DataKey. EnableKeyRotation: true rotates the key material yearly. PendingWindowInDays: 7 is the shortest waiting period KMS allows before a key is really deleted. The key-policy statement with arn:${AWS::Partition}:iam::${AWS::AccountId}:root means "IAM policies in this account decide who can use the key". Without a statement like it, nobody could use the key through IAM. DeletionPolicy: Retain and UpdateReplacePolicy: Retain keep 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).
  4. DataKeyAlias. An alias is a friendly name. It is a separate resource and is not retained, so deleting the stack frees the name.
  5. AccessLogBucket and its policy. S3 server access logs cannot use a KMS-encrypted destination, so this bucket uses AES256. The policy lets only the S3 logging service write into the audit-bucket/ prefix, and only for requests from this account and the audit bucket's ARN. The 90-day lifecycle rule stops logs piling up.
  6. AuditBucket. DependsOn: AccessLogBucketPolicy makes CloudFormation finish the log bucket's policy first, because S3 checks the permission when logging is switched on. BucketKeyEnabled: true makes S3 use a bucket-level data key, which cuts the number of KMS calls (and the cost) a lot. OwnershipControls with BucketOwnerEnforced disables ACLs. Both policies are Retain: evidence must not vanish with a stack.
  7. 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 !GetAtt would create a cycle, so the ARN is rebuilt with !Sub from the same name pattern. Whenever CloudFormation reports "Circular dependency between resources", look for a !Ref or !GetAtt pair like this.
  8. AuditBucketPolicy and 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.
  9. Outputs and Export. 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 set NoEcho: true, and NoEcho only 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 (or CAPABILITY_NAMED_IAM when 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

PolicyApplies toEffect when the stack (or resource) is deleted
DeleteMost resources (the default)Resource is deleted. A non-empty S3 bucket fails to delete
RetainAny resourceResource is kept and removed from the stack. You own it from then on
RetainExceptOnCreateAny resourceRetained on later deletes, but deleted if the creation rolled back (stops orphans from failed first deploys)
SnapshotSupported types such as AWS::RDS::DBInstance and AWS::EC2::VolumeA 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. Run delete-stack, fix the template, create again. Resources with DeletionPolicy: Retain created before the failure stay behind, so a retried deployment can fail with "already exists". RetainExceptOnCreate exists 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, then aws 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

MechanismWhat it isWhen to useWatch out for
Nested stacks (AWS::CloudFormation::Stack)A parent template that deploys child templates from S3Break a large template into parts, reuse a patternUpdates happen through the parent; keep nesting shallow
Exports and Fn::ImportValueShare values across stacks in an account and RegionA shared network exporting subnet IDsHard dependency; an export in use cannot be changed
Cross-stack parametersPass values by hand or by pipelineLooser couplingSomeone must wire it
CloudFormation modulesRegistered, versioned resource bundlesA central team publishes an approved patternRegistry limits and versioning discipline
Transform: AWS::LanguageExtensionsAdds functions such as Fn::ForEach for loopsRepeated similar resourcesExtra transform step in change sets ⚠ VERIFY current function list
Resource importBring an existing resource under a stack (--change-set-type IMPORT)Adopt hand-built resourcesThe 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: True until 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 Retain and import it under the new name.
  • Hard-coding BucketName and then being unable to create a second copy of the stack. Use !Sub with the account and Region, as here.
  • Forgetting UpdateReplacePolicy. A property change that forces replacement deletes the old bucket's data even though DeletionPolicy is Retain.
  • Cycles from !GetAtt pairs. Build ARNs from names with !Sub where needed.
  • Using NoEcho as 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

SymptomLikely causeFix
ValidationError: Template format errorYAML indentation or an unknown intrinsic functionRun cfn-lint; check that list items align
ROLLBACK_COMPLETE, cannot updateFirst creation faileddelete-stack, fix, create again; read the failed event reason first
AlreadyExists for the bucketName taken (a retained bucket from a previous run, or another account)Delete the retained bucket or change the name pattern
Circular dependency between resourcesTwo resources reference each other through !Ref or !GetAttBreak the loop with a name built by !Sub
Export ... cannot be deleted as it is in use by ...Another stack imports the valueRemove the import first, or stop using exports
UPDATE_ROLLBACK_FAILEDA resource changed outside CloudFormation blocks the rollbackFix the resource, run continue-update-rollback, skip as a last resort
AccessDenied creating the bucket policyAccount-level Block Public Access or an SCP blocks the actionCheck Organization SCPs and the account's S3 settings
Template too largeOver 51,200 bytes in --template-bodyUpload 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-sandbox

Empty 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 NoncurrentVersionDays to 120 with a second change set (--change-set-type UPDATE, same template, ParameterKey=NoncurrentVersionDays,ParameterValue=120) and confirm Replacement is False.
  • 🟡 Challenge: add a DataClass parameter (allowed values public, internal, confidential) and a bucket tag that uses it. Add a Rule so that confidential is only accepted when Environment is prod or test. 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

Knowledge check

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?" DeletionPolicy and UpdateReplacePolicy set to Snapshot or Retain, termination protection, a stack policy that denies Update:Replace and Update:Delete on 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

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: True and the two policies
  • I can describe recovering from ROLLBACK_COMPLETE and UPDATE_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.
  • Retain keeps data and hands you the cleanup; pair DeletionPolicy with UpdateReplacePolicy for stateful resources.
  • Read change sets for Remove and Replacement: 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.

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.

On this page