AWS CloudFormation

Templates and stacks

A template is a YAML or JSON file that describes AWS resources. YAML is easier to read, so most people use it. When you deploy a template, CloudFormation creates a stack: a named group of resources that are created, updated and deleted together. You can deploy the same template many times as different stacks, for example results-bucket-dev and results-bucket-prod.

The sections of a template

A full example: a versioned S3 bucket

AWSTemplateFormatVersion: '2010-09-09'
Description: Versioned S3 bucket for exam result PDFs

Parameters:
  EnvName:
    Type: String
    AllowedValues: [dev, prod]
    Default: dev
    Description: Which environment this stack is for

Resources:
  ResultsBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub 'results-${EnvName}-${AWS::AccountId}'
      VersioningConfiguration:
        Status: Enabled
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      Tags:
        - Key: env
          Value: !Ref EnvName

Outputs:
  BucketName:
    Description: Name of the results bucket
    Value: !Ref ResultsBucket
  BucketArn:
    Description: ARN of the results bucket
    Value: !GetAtt ResultsBucket.Arn

Intrinsic functions

Intrinsic functions are small built-in helpers that compute values when the stack is deployed. In YAML they start with an exclamation mark.

• !Ref Name: the value of a parameter, or the main identifier of a resource. For an S3 bucket, !Ref gives the bucket name.
• !GetAtt Resource.Attribute: another attribute of a resource, such as ResultsBucket.Arn. An ARN (Amazon Resource Name) is the full unique ID of a resource.
• !Sub 'text ${Name}': puts parameter values, resource values or pseudo parameters (built-in values such as AWS::AccountId, AWS::Region and AWS::StackName) into a string.
• !Join ['-', [a, b, c]]: joins a list of values with a separator, giving a-b-c.

Mappings and Conditions are used less often but are useful. A Mappings table can say "dev uses t3.micro, prod uses t3.large", read with !FindInMap. A condition such as IsProd: !Equals [!Ref EnvName, prod] can be attached to a resource so it is only created in production.

Deploying with the AWS CLI

# Check the template for syntax errors
aws cloudformation validate-template --template-body file://bucket.yaml

# Create the stack, or update it if it exists (uses a change set behind the scenes)
aws cloudformation deploy \
  --template-file bucket.yaml \
  --stack-name results-bucket-dev \
  --parameter-overrides EnvName=dev

# Read the outputs
aws cloudformation describe-stacks --stack-name results-bucket-dev \
  --query "Stacks[0].Outputs"

# Only create the change set, so you can review it before running it
aws cloudformation deploy --template-file bucket.yaml \
  --stack-name results-bucket-prod --parameter-overrides EnvName=prod \
  --no-execute-changeset

Change sets, rollback and drift detection

A change set is a preview: "these resources will be added, these modified, and this one replaced". Replacement matters. Some property changes, such as BucketName, cannot be made in place, so CloudFormation creates a new resource and deletes the old one. Always read the change set before running it in production.

Rollback: if any resource fails during create or update, CloudFormation undoes the changes and returns the stack to its last good state. Your stack is never left half-built without you knowing. Drift detection compares each resource with the template and reports properties changed outside CloudFormation (aws cloudformation detect-stack-drift).

Nested stacks and StackSets

A nested stack is a stack created from inside another template (resource type AWS::CloudFormation::Stack). It lets you reuse a standard piece, such as a VPC, in many templates. A StackSet deploys the same template to many AWS accounts and regions at once, for example a security baseline in every account of an organisation.