CloudFormation Templates

A template declares what should exist; CloudFormation works out how to get there. This page is about writing ones that are still readable a year later. The mechanics of operating stacks are covered separately.

Use YAML. It supports comments, the short-form functions (!Ref, !Sub) are far more readable than their JSON equivalents, and multi-line strings work properly.

Structure

AWSTemplateFormatVersion: '2010-09-09'
Description: Orders API infrastructure

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, prod]
    Description: Deployment environment

  DbPassword:
    Type: AWS::SSM::Parameter::Value<String>
    Default: /orders/db-password
    NoEcho: true

  VpcId:
    Type: AWS::EC2::VPC::Id

Mappings:
  EnvConfig:
    dev:      { InstanceType: t3.small,  MinSize: 1, MultiAZ: false }
    staging:  { InstanceType: t3.medium, MinSize: 2, MultiAZ: false }
    prod:     { InstanceType: m6i.large, MinSize: 3, MultiAZ: true }

Conditions:
  IsProd: !Equals [!Ref Environment, prod]

Resources:
  Database:
    Type: AWS::RDS::DBInstance
    DeletionPolicy: Snapshot
    UpdateReplacePolicy: Snapshot
    Properties:
      DBInstanceClass: !FindInMap [EnvConfig, !Ref Environment, InstanceType]
      MultiAZ: !FindInMap [EnvConfig, !Ref Environment, MultiAZ]
      MasterUserPassword: !Ref DbPassword
      BackupRetentionPeriod: !If [IsProd, 30, 1]
      DeletionProtection: !If [IsProd, true, false]

Outputs:
  DatabaseEndpoint:
    Value: !GetAtt Database.Endpoint.Address
    Export:
      Name: !Sub '${AWS::StackName}-DbEndpoint'

Only Resources is mandatory. Everything else earns its place.

Parameter types do validation for you

The most under-used feature in CloudFormation. A typed parameter is validated before the stack starts changing anything, rather than failing halfway through:

Typing a subnet as String means a typo fails during creation, after other resources exist. Typing it as AWS::EC2::Subnet::Id means it fails immediately with a clear message, and the console gives a dropdown.

AWS::SSM::Parameter::Value<String> is the one worth adopting as a habit: the template references a parameter path, and the value is fetched at deploy time, so secrets and environment-specific values never appear in the template or in version control.

Add NoEcho: true to anything sensitive so it is masked in the console, events and API responses.

  AllowedCidr:
    Type: String
    AllowedPattern: '^(\d{1,3}\.){3}\d{1,3}/\d{1,2}$'
    ConstraintDescription: Must be a valid CIDR block

Intrinsic functions

!Ref returns the "main" value. For a parameter its value, for most resources the physical ID, though what exactly that means varies by type. Check the documentation rather than assuming.

!GetAtt returns a specific attribute:

!GetAtt Database.Endpoint.Address
!GetAtt LambdaRole.Arn

!Sub substitutes variables into a string, and should be your default over !Join:

# Readable
BucketName: !Sub '${AWS::StackName}-artifacts-${AWS::AccountId}'

# The same thing, unreadable
BucketName: !Join ['-', [!Ref 'AWS::StackName', 'artifacts', !Ref 'AWS::AccountId']]

!Sub also reaches attributes directly with ${Resource.Attribute}, and a literal ${ is escaped as ${!.

Pseudo-parameters are always available: AWS::Region, AWS::AccountId, AWS::StackName, AWS::Partition, AWS::NoValue. Use AWS::Partition rather than hardcoding aws in ARNs if anything might run in GovCloud or China.

!Ref AWS::NoValue removes a property entirely, which is how you make one conditional:

      KmsKeyId: !If [UseCustomKey, !Ref EncryptionKey, !Ref 'AWS::NoValue']

Conditions

Conditions:
  IsProd: !Equals [!Ref Environment, prod]
  IsNotDev: !Not [!Equals [!Ref Environment, dev]]
  NeedsBackup: !Or [!Condition IsProd, !Condition IsNotDev]

Resources:
  ReadReplica:
    Type: AWS::RDS::DBInstance
    Condition: IsProd
    Properties:
      SourceDBInstanceIdentifier: !Ref Database

A resource with a false Condition is not created at all. This keeps one template serving every environment, which is much better than three templates that drift apart.

Beyond a handful of conditions, though, readability collapses. That is usually the point at which CDK or a templating layer is the better answer, because real conditionals in a programming language beat nested !If expressions.

Dependencies

CloudFormation infers ordering from !Ref and !GetAtt, if resource A references B, B is created first. Most of the time you need nothing else.

DependsOn is for ordering CloudFormation cannot see:

  Instance:
    Type: AWS::EC2::Instance
    DependsOn: GatewayAttachment      # needs internet access to bootstrap

An EC2 instance downloading packages depends on the internet gateway being attached, but nothing in its properties references it, so without DependsOn the instance may launch first and its user data fails silently.

Overusing DependsOn is its own problem: it serialises creation that could have run in parallel and makes the dependency graph harder to reason about. Add it when you have a real ordering requirement, not defensively.

Custom resources

For anything CloudFormation does not support natively:

  DnsValidation:
    Type: Custom::DnsValidator
    Properties:
      ServiceToken: !GetAtt ValidatorFunction.Arn
      DomainName: !Ref DomainName

The Lambda receives Create, Update and Delete events and must signal back to a presigned URL. If it does not, because it timed out, crashed, or returned without responding, CloudFormation waits the full hour before failing.

Two rules make them survivable: always respond, including from your exception handler, and handle Delete as a no-op rather than an error if the thing is already gone, or stack deletion hangs forever.

Where possible, prefer a module or an AWS-provided resource type over writing one.

Lint before you deploy

cfn-lint template.yaml

cfn-lint catches misspelled properties, invalid values, missing required fields and unreachable conditions. The things that otherwise fail ten minutes into a deploy. Run it in CI.

aws cloudformation validate-template only checks that the template parses, which is much weaker.

cfn-guard validate --rules rules.guard --data template.yaml

cfn-guard enforces policy, "every S3 bucket must have encryption", "no security group may allow 0.0.0.0/0 on port 22", as a check rather than a review comment.

Common errors

A !Ref to something that does not exist. Usually a typo in a logical ID, which are case-sensitive.

!Condition is required when referencing one condition from another. A plain !Ref does not work there.

A typed parameter doing its job before anything was created.

The Lambda did not signal back. Check its logs and make sure every path responds.

Quick reference

Key takeaways

• Use YAML: comments, short functions, readable multi-line strings.
• Use specific parameter types. They validate before anything is created.
• AWS::SSM::Parameter::Value<String> keeps secrets and per-environment values out of the template.
• Prefer !Sub to !Join. Same result, far more readable.
• !Ref AWS::NoValue is how you omit a property conditionally.
• Conditions let one template serve every environment: until there are too many to follow.
• DependsOn only for ordering CloudFormation cannot infer. It serialises otherwise.
• Custom resources must always signal back, including on failure and on delete.
• Run cfn-lint in CI. validate-template only checks syntax.

Check your understanding

<MCQExercise exercise={{ id: 'aws-cfn-tmpl-quiz1', title: 'An instance whose bootstrap silently fails', description: 'A template creates a VPC, an internet gateway, a gateway attachment and an EC2 instance whose user data installs packages. The stack succeeds but the instance has no packages. Nothing references the attachment. What is missing?', options: [ { id: 'a', text: 'DependsOn: GatewayAttachment on the instance. CloudFormation cannot infer an ordering that no property expresses, so the instance can boot before internet access exists' }, { id: 'b', text: 'A !Ref to the VPC in the instance properties, which would create the dependency automatically' }, { id: 'c', text: 'A WaitCondition, which is mandatory for any instance running user data' }, { id: 'd', text: 'The user data must be base64 encoded, which CloudFormation does not do automatically' }, ], correctId: 'a', explanation: 'CloudFormation builds its dependency graph from !Ref and !GetAtt, so resources that are genuinely ordered but never reference each other can be created in parallel. An instance can therefore launch and run its user data before the internet gateway is attached, leaving package installs failing while the stack reports success. A silent failure, since user data errors do not fail the stack. DependsOn expresses that ordering explicitly. Use it where a real requirement exists and nowhere else, since it serialises work that could otherwise run concurrently.', wrongExplanations: { b: 'Referencing the VPC orders against the VPC, not against the gateway attachment, which is a separate resource.', c: 'WaitConditions signal bootstrap completion back to CloudFormation. Useful, but not what causes this ordering problem.', d: 'CloudFormation accepts plain-text user data in templates and encodes it itself.', }, }} />

<MCQExercise exercise={{ id: 'aws-cfn-tmpl-quiz2', title: 'Catching a typo before it costs ten minutes', description: 'A template has BackupRetension instead of BackupRetentionPeriod. aws cloudformation validate-template reports no problems. Where would this be caught before deploying?', options: [ { id: 'a', text: 'cfn-lint, which validates property names against the resource specification, validate-template only checks that the template parses' }, { id: 'b', text: 'A change set, which rejects unknown properties before execution' }, { id: 'c', text: 'Drift detection run against the existing stack' }, { id: 'd', text: 'Nowhere. Unknown properties are silently ignored by CloudFormation' }, ], correctId: 'a', explanation: 'validate-template is a syntax check: it confirms the document is well-formed JSON or YAML with a plausible structure, and knows nothing about which properties a resource type actually accepts. cfn-lint validates against the published resource specification, so a misspelled property is reported with a line number in about a second. It also catches invalid enum values, missing required properties, unused parameters and unreachable conditions. Run it in CI alongside cfn-guard for policy rules such as mandatory encryption.', wrongExplanations: { b: 'A change set surfaces the error only when created against the real service, which is slower and happens after you have committed to the attempt.', c: 'Drift detection compares deployed resources against the template and does not validate the template itself.', d: 'Unknown properties are rejected, not ignored: the deploy fails, just later than it needed to.', }, }} />