CloudFormation

AWS CloudFormation is Amazon Web Services's native infrastructure as code (Private) tool. Many user interfaces in the AWS Console use it as the basis for their provisioning operations.

Composition

CloudFormation Templates are YAML (Private) (preferred) or JSON (Private) files comprising Resources. The basic structure of the file is broken down into a number of sections:

AWSTemplateFormatVersion defines the version of the CloudFormation template.
Description is a brief description of the template's contents and behaviour.
Metadata is arbitrary YAML associated with the template.
Parameters is a name-indexed map of up to 60 inputs to the template, which can be validated.
- Description provides a human-readable explanation of the input's use.
- Type defines the related type, e.g. String, Number, List<T>, CommaDelimitedList (of strings) or a resource property for a pre-existing resource, such as AWS::EC2::KeyPair::KeyName.
- ConstraintDescription describes the input's format.
- Default is an optional default value.
- AllowedValues is an optional list of enum values.
- AllowedPattern is an optional Regular Expression (Private).
- MinLength and MaxLength constrain string lengths.
- MinValue and MaxValue constrain numbers.
Mappings serve as lookup tables. They can't contain references, as they're computed statically, but you can index into one using a parameter.
Conditions contains a Resource ID indexed map of conditions in which different resources will or will not be created, using intrinsic functions to express logic.
Transforms define one or more macros CloudFormation should apply when processing the template, e.g. to Include resources from external files hosted in an S3 bucket.
Resources is a map of defined resources, indexed by a name relevant only in the template:
- Type contains the CloudFormation resource type, e.g. AWS::EC2::Instance.
- Properties is optional for resources that have sensible defaults.
Outputs let a Stack emit up to 60 values post-creation or update, allowing other Stacks to reference them. They need a Name and Value.

Intrinsic functions

Intrinsic functions allow representing lightweight logical operations using the CloudFormation template syntax. Some common functions:

Fn::FindInMap [MyMap, !Ref "MyParam", MyProp] gets the attribute MyProp from the key in MyMap matching the value of the MyParam parameter.
Fn::GetAtt gets an attribute from a resource defined elsewhere in the template.
Fn::Join String List<String> concatenates strings.
Fn::Sub String Map substitutes map keys for their values.
Ref substitutes a resource's ID or property, a property from a parameter or another resource defined in the template.

Calling intrinsic functions

There are multiple syntaxes for calling intrinsic functions:

Resources:
  # Long syntax
  MyResource:
    Type: AWS::S3::Bucket
    Properties:
      Name:
          Fn::Join:
      - "x"
      - "y"
      - "z"

  # Short syntax
  MyResource:
    Type: AWS::S3::Bucket
    Properties:
      Name: !Join ["x", "y", "z"]

Stacks

CloudFormation deployments are called Stacks. Their content and status is managed in the CloudFormation service, allowing Stacks to be managed from the CloudFormation section of the Console.

Stack provisioning events have statuses:

CREATE_IN_PROGRESS
CREATE_COMPLETE

CloudFormation templates can either be stored outside of AWS and uploaded to the CloudFormation service just during updates, or stored in an S3 bucket where they can be freely fetched and versioned (generally preferred).

Updating

Stacks can be updated in one of two ways:

directly, good for rapid deployment of changes, but with poor visibility and higher risk of erroneous modifications to important resources; or
via change sets, allowing previewing in the form of JSON change summaries.

Exports

Exports allow one CloudFormation Stack to provide output values that may be sourced by other CloudFormation Stacks deployed to the same region and account.

StackSets

StackSets allow management of Stacks across multiple accounts and regions in a single operation.

Designer

The Designer provides a graphical representation of a template.

Custom resources

Custom resources can be defined in CloudFormation. Handlers must consume a request, validate that it's valid, perform a provisioning operation and write a result to a pre-signed S3 object for CloudFormation to pick up. Handlers are commonly hosted on AWS Lambda, using SNS notifications as triggers.

Requests are comprised of:

RequestType defines the action being taken, either CREATE, UPDATE or DELETE.
ResourceProperties is a map of values specific to the changing resource.
ResponseUrl is a pre-signed (what) S3 URL where CloudFormation will seek a response.

Responses are comprised of:

RequestId identifies the operation and must be included.
Stack identifies the Stack and must be included.
Status is SUCCESS or FAILURE depending upon the result.
Reason is a string describing the fault, required on failure.
LogicalResourceId is a developer-chosen name for the resource.
PhysicalResourceId lets us track a resource's lifetime over Stack provisioning operations: empty on CREATE, the value returned during CREATE during UPDATE unless the resource is replaced, the last known value during DELETE.
ResourceData optionally defines the outputs available as properties to other resources in the Stack.

A custom resource:

Resources:
  MyCustomResource:
    Type: AWS::CloudFormation::CustomResource
    Properties:
      # Where should the request be sent? Lambda function or SNS topic.
      ServiceToken: arn:aws:sns:us-east-1:XXX:XXX
      MyParam: XXX
      MyOtherParam: xxx

Backlinks