AWS CloudFormation Quick Reference

Note: examples are snippets intended for highlighting use and not ready to run.

What is AWS CloudFormation?

CloudFormation (CF) provides IT infrastructure provisioning, configurations and development through text based templates.

What is a CloudFormation Template?

A CloudFormation template is a JSON or YAML document describing your Cloud infrastructure and includes description, metadata, parameters, mappings, conditions, transformations, and outputs.

CloudFormation Template Anatomy:

{
  "AWSTemplateFormatVersion" : "version date",

  "Description" : "string",

  "Metadata" : {
    template metadata
  },

  "Parameters" : {
    parameters objects list
  },

  "Mappings" : {
    mappings objects list
  },

  "Conditions" : {
   conditions objects list
  },

  "Transform" : {
    transfrom objects list
  },

  "Resources" : {
    resources objects list
  },

  "Outputs" : {
    output objects list
  }
}

Metadata property:

Optional property for including detailed data about a resource or the stack. This includes these Metadata Keys:

  1. AWS::CloudFormation::Init
    Defines task to be performed by cfn-init helper script. This script is used to install packages, create files, setup users and groups, run commands, download and unpack a source (i.e. Git Repo) to a directory, start and stop services on EC2 instances.

Example install Apache HTTPD (2.4.34) on EC2 instance:

...
{
  "Resources": {
      "WebInstance": {
      "Type": "AWS::EC2::Instance",
      "MetaData":{
        "AWS::CloudFormation::Init":{
        "config":[
            "packages":{
               "yum": {
                  "httpd" : ["2.4.34"]
               }
            }
       "UserData": {"Fn::Base64": { fn::Join: ["", [
             "#!/bin/bash -xe\n",
             "yum install -y aws-cfn-bootstrap\n",
             "#Run cloud init\n",
             "/opt/aws/bin/cfn-init -v ",
             "--stack ", { "Ref" : "AWS::StackName" },",
        ]]}}
       
        }
        
        ]
...
List of properties can be found here:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html#aws-resource-cloudformation-init-syntax

Run CloudFormation helper script:

cfn-init is installed on Amazon Machine Images (AMIs) & reference in the UserData property of an EC2 property (AWS::EC2::Instance)

  1. AWS::CloudFormation::Interface
    Key is used to arrange and change labels for parameter inputs on AWS console.

  2. AWS::CloudFormation::Designer
    Key is used to determine layout for CloudFormation Designer. CloudFormation Designer is an AWS services for graphically creating CloudFormation templates.

CF Parameters:

Parameters define values that can be passed into CF templates. This could be an IP Address range, instance size, passwords or any other custom values need for a template.

Important notes about parameters:

  1. 60 parameter limit per CF Template (encourges nested templates).
  2. Parameters can have default.
  3. Must be a support Parameter Type.
  4. Often used in conjunction with mappings to select specific values.
  5. Apply constraints using a range (min\max value or length property), allowed values (list), allowed pattern (regular expression) or AWS type parameter to limit input values.
  6. Parameters are created and referenced within the resources or outputs properties of the same template. Important when using nested templates.

Example parameter for capturing the value of a security group with default of my-app-sg.

...
"Parameters": {
 
"MySecurityGroupParam":{
     "Type": "AWS::EC2::SecurityGroup::Id",
     "Default": "my-webapp-sg",
     "Description": "Select an existing security group"
   
 }
 
}
...

Parameter Referencing:

A parameter is referenced using the Ref intrinsic function within resource or out property of a template.

...

"Resources":{
      "WebInstance": {
      "Type": "AWS::EC2::Instance",
      "SecurityGroup": {"Ref": "MySecurityGroupParam"}
      }

}

...

Mappings:

Maps a Key to a set of values. Often used as a selector for a resources based on certain criteria. For example, providing and EC2 resource with list Amazon Machine Images (AMIs) for a particular region.

Important notes about mappings:

  1. Can not include intrinstic functions, parameters or pseudo parameters.
  2. Keys must be a string.
  3. Values can be a string or list.
  4. Use the Fn::FindInMap intrinstic function to get Map values in the template.

Example Mapping Region to AMI with FindInMap

...
 Mappings:{
    "RegionMap" : {
      "us-east-1"        : {"HVM64" : "ami-nnn", "HVMG2" : "ami-yyy"},
      "us-west-1"        : {"HVM64" : "ami-nnn", "HVMG2" : "ami-xxx"},
      "eu-west-1"        : {"HVM64" : "ami-aaa", "HVMG2" : "ami-bbb"},
      "ap-northeast-1"   : {"HVM64" : "ami-ccc", "HVMG2" : "ami-aaa"},
      "ap-southeast-1"   : {"HVM64" : "ami-yyy", "HVMG2" : "ami-xxx"}
    }
    }
...

    "Resource":{
     "WebInstance":{
        ...
          "Properties:{
          ...
            ImageId:{
            "Fn:FindInMap": 
               ["RegionMap", {"Ref": "AWS:Region"}, "HVM64"]
            }
          ...
          
          }
        
        ...
     }
    }

Note: AWS:Region is a psuedo parameter that select the region the CloudFormation stack (region is is being run in).

AWS Docs on Mappings can be found here:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html

Anatomy of the FindInMap intrinstic function:


{ "Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey"] }

Note Top and second level keys can be parameters or pseudo-parameters

Resource Property:

This property defines the core components of a stack and is the only mandatory property. Resources are usually AWS specific services (i.e. AWS::EC2::Instance) but CF does provide a custom resource type (AWS::CloudFormation::CustomResource or Custom::String).

Anatomy of a Resource:

...
"Resources" : {
    "Logical ID" : {
        "Type" : "Resource type",
        "Properties" : {
            Set of properties
        }
    }
}
...

  • Logical ID is a unique name used for referencing within a template.
  • Type defines the resource type which is usually a AWS service (i.e. EC2)
  • Properties are different depending on the resource type defined.

Example create VPC

...
"Resources": {

      "MyVPC": {
      
       "Type": "AWS::EC2::VPC", 
       "Properties":{
         "Cidr":"10.0.0.0/16",
         "EnableDnsSupport":"false",
         "EnableDnsHostNames":"false",
         "InstanceTenancy": "default",
         "Tags": [{"key": "type", "value": "app_vpc"}]
         
       }
      
      }

}

...

Condition Property

Provides a set of condition under which resources or other components are created or configured in CF. Often used to configure evironments differently based on the condition (i.e. Prod vs Dev).

Important notes about Conditions:

  1. Use input or pseudo parameters.
  2. Are evaluated before any resources are created or updated.
  3. Can only be updated when updating, changing or deleting resources.
  4. Uses intrinstic condition functions to evaluate the condition.

Example Using Condtions in CF templates.

Create the volume and mount point if the environment type is production.

...
 
Parameters: {
    "EnvironmentType": {
         "Type": "String", 
         "AllowedValues": ["test", "prod"],
         "ConstraintDescription: "Is this a test or prod environment?"
    }

},

 "Conditions": {
      "ProdResources": {"Fn:Equals":[{"Ref": "EnvironmentType"}, "prod"]}
 },
 
 "Resources" : {
    "EC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "ImageId" : {AMI-XXXXXXX}
      }
    },
    
    "MountPoint" : {
      "Type" : "AWS::EC2::VolumeAttachment",
      "Condition" : "ProdResources",
      "Properties" : {
        "InstanceId" : { "Ref" : "EC2Instance" },
        "VolumeId"  : { "Ref" : "ProdVolume" },
        "Device" : "/dev/sdh"
      }
    },

    "ProdVolume" : {
      "Type" : "AWS::EC2::Volume",
      "Condition" : "ProdResources",
      "Properties" : {
        "Size" : "200",
        "AvailabilityZone" : { "Fn::GetAtt" : [ "EC2Instance", "AvailabilityZone" ]}
      }
    }
  },
 
...

CF Transform property:

Provides a method for applying macros to perform custom processing of an entire CF templates.

Important notes about Transform:

  1. CloudFormation has two hosted types AWS::Includes and AWS:Serverless.
  2. AWS:Includes provides a method for inserting generic snippets into a templates.
  3. AWS:Serverless transforms a template developed in SAM (Serverless Application Model) into a working CF templates.

CF Outputs Property:

This section of a CF template can be used to output parameters, resource attributes or other custom information about the processing of the template that can be used for input into another CF template.

Example CF outputs:

.....
"Outputs": {
    "InstanceID" : {
        "Description": "The Instance ID",  
        "Value" : { "Ref" : "EC2Instance" }
      }
  }
....

Intrinstic Functions:

These are convenient function to help manage CF template values at runtime.

List, description and example of available intrinstic functions:

  1. Fn::base64
    Used to encode user data for EC2 instances (i.e. commands to run on EC2.
  2. Fn::FindInMap
    Used to find a value in a mapping key\value pair.
  3. Fn::Ref
    Used to retrived a resource id (references a resource).
  4. Fn:GetAtt
    Used to get an attribute or property value of a resource.
  5. Fn::GetAz
    Used to get an Availablity Zone of a resource.
  6. Fn::Join
    Used to Join strings or parameter values together
  7. Fn::Select
    Used to return an object from a list of objects.
  8. Fn::If
    Condition function used to return one value when true and another when false
  9. Fn::And
    Condition function that acts as an "And" operator for a list of conditions. True if all conditions are true. Can use up to 10 conditions.
  10. Fn::Or
    Condition function that acts as an "Or" operator. True if any condition is true.
  11. Fn::Not
    Condition that acts as a negation or Not operator.
  12. Fn:Equals
    Condition to compare two value. True if both values are equal.
  13. Fn:Transform
    Applies a Macros (lambda function) to a section of CF template.
  14. Fn::ImportValue
    Returns the value of output form another CF template.

Joe Bennett

Read more posts by this author.