AWSTemplateFormatVersion

AWSTemplateFormatVersion corresponds to the template version to which this template adheres. Do not confuse this with an API version or the version of the developer’s template draft. Currently, AWS CloudFormation only supports the value "2010-09-09", which you must provide as a literal string.

Description

The Description section allows you to provide a text explanation of the template’s purpose or other arbitrary information. The maximum length of the Description field is 1,024 bytes. Similar to the AWSTemplateFormatVersion section, Description supports only literal text.

Metadata

The Metadata section of a template allows you to provide structured details about the template. For example, you can provide Metadata about the overall infrastructure to deploy and which sections correspond to certain environments, functional groups, and so on. The Metadata you provide is made available to AWS CloudFormation for reference in other sections of a template or on Amazon EC2 instances being provisioned by AWS CloudFormation.

"Metadata": {
  "ApplicationLayer": {
    "Description": "Information about resources in the app layer."
  },
  "DatabaseLayer": {
    "Description": "Information about resources in the DB layer."
  }
}

In the Metadata section of the template, you have the ability to specify properties that affect the behavior of different components of the AWS CloudFormation service, such as how template parameters display in the AWS CloudFormation console.

Parameters

You can use Parameters to provide inputs into your template, which allows for more flexibility in how this template behaves when you deploy it. Parameter values can be set either when you create the stack or when you perform updates.

The Parameters section must include a unique logical ID (in the next example, InstanceTypeParameter). A parameter must include a value, either a default or one that you provide. Lastly, you cannot reference parameters outside a single template.

"Parameters": {
  "InstanceTypeParam": {
    "Type": "String",
    "Default": "t2.micro",
    "AllowedValues": [ "t2.micro", "m1.small", "m1.large" ],
    "Description": "Enter t2.micro, m1.small, or m1.large. Default is t2.micro."
  }
}

"EC2Instance": {
  "Type": "AWS::EC2::Instance”,
  "Properties": {
    "InstanceType": { "Ref": "InstanceTypeParam" },
    "ImageId": "ami-12345678"
  }
}

AWS CloudFormation supports the following parameter types:

• String
• Number
• List of numbers
• Comma-delimited list
• AWS parameter types
• AWS Systems Manager Parameter Store (Systems Manager) parameter types

If a parameter value is sensitive, you can add the NoEcho property. When this is set, the parameter value displays as asterisks (***) for any cloudformation:Describe* calls. Within the template itself, the value will resolve to the actual input when making Ref calls.

AWS parameter types When you use AWS parameter types, AWS CloudFormation automatically queries existing properties and values within your AWS account. This can include information such as Amazon EC2 key pair names, IDs of resources, AWS regions/availability zones, or other properties of your account. These input values must exist in your account and are validated to ensure that they are correct. For example, you can use the AWS::EC2::KeyPair::KeyName parameter type to require a valid Amazon EC2 key pair. This way, there is reduced risk that a user will input an incorrect value that results in improper stack behavior.

AWS System Manager parameter types AWS Systems Manager parameter types can reference parameters that exist in the AWS Systems Manager Parameter Store. If you specify a parameter key, AWS CloudFormation will search your Systems Manager Parameter Store for the correct value and input this into the stack. When you perform stack updates, AWS CloudFormation queries the same key again and could result in a new value for the AWS CloudFormation parameter.

Mappings

You can use the Mappings section of a template to create a rudimentary lookup tables that you can reference in other sections of your template when you create the stack.

A common example of mappings usage is to look up Amazon EC2 instance AMI IDs based on the region and architecture type. Note in the following example that mappings entries may contain only string values. (Mappings does not support parameters, conditions, or intrinsic functions.)

"Mappings" : {
  "RegionMap" : {
    "us-east-1"      : { "32" : "ami-6411e20d", "64" : "ami-7a11e213" },
    "us-west-1"      : { "32" : "ami-c9c7978c", "64" : "ami-cfc7978a" },
    "eu-west-1"      : { "32" : "ami-37c2f643", "64" : "ami-31c2f645" },
    "ap-southeast-1" : { "32" : "ami-66f28c34", "64" : "ami-60f28c32" },
    "ap-northeast-1" : { "32" : "ami-9c03a89d", "64" : "ami-a003a8a1" }
  }
}

After you declare the Mappings section, you can query the values within the mapping with the Fn::FindInMap intrinsic function. The example shows an Fn::FindInMap call that queries the AMI ID based on region and architecture type (32- or 64-bit). If the region was us-east-1, for example, the previous template snippet would resolve to ami-6411e20d.

"Resources" : {
  "myEC2Instance" : {
    "Type" : "AWS::EC2::Instance",
    "Properties" : {
      "ImageId" : { "Fn::FindInMap" : [ "RegionMap", { "Ref" : "AWS::Region" }, "32"]},
      "InstanceType" : "m1.small"
    }
  }
}

Conditions

You can use Conditions in AWS CloudFormation templates to determine when to create a resource or when a property of a resource is defined (either in the Resources or Outputs section of the stack). Conditional statements make use of intrinsic functions to evaluate multiple inputs against one other.

A common use case for this would be to conditionally set an Amazon EC2 instance to use a larger instance type if the environment to which you deploy is prod versus dev. The environment type is input as a template parameter, EnvType, which the conditional statement, CreateProdResources, uses. The conditional statement decides whether to create an additional Amazon Elastic Block Store (Amazon EBS) volume and mount it to the instance with the Condition property of the resource.

{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Mappings" : {
    "RegionMap" : {
      "us-east-1"      : { "AMI" : "ami-7f418316", "TestAz" : "us-east-1a" },
      "us-west-1"      : { "AMI" : "ami-951945d0", "TestAz" : "us-west-1a" },
      "us-west-2"      : { "AMI" : "ami-16fd7026", "TestAz" : "us-west-2a" }
    }
  },
  "Parameters" : {
    "EnvType" : {
      "Description" : "Environment type.",
      "Default" : "test",
      "Type" : "String",
      "AllowedValues" : ["prod", "test"]
    }
  },
  "Conditions" : {
    "CreateProdResources" : {"Fn::Equals" : [{"Ref" : "EnvType"}, "prod"]}
  },
  "Resources" : {
    "EC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "ImageId" : { "Fn::FindInMap" : [ "RegionMap", { "Ref" : "AWS::Region" }, "AMI" ]}
      }
    },
    "MountPoint" : {
      "Type" : "AWS::EC2::VolumeAttachment",
      "Condition" : "CreateProdResources",
      "Properties" : {
        "InstanceId" : { "Ref" : "EC2Instance" },
        "VolumeId"  : { "Ref" : "NewVolume" },
        "Device" : "/dev/sdh"
      }
    },
    "NewVolume" : {
      "Type" : "AWS::EC2::Volume",
      "Condition" : "CreateProdResources",
      "Properties" : {
        "Size" : "100",
        "AvailabilityZone" : { "Fn::GetAtt" : [ "EC2Instance", "AvailabilityZone" ]}
      }
    }
  }
}

You can also use Conditions to declare different resource properties based on whether the condition evaluates to true with the Fn::If intrinsic function. The following example uses the UseDBSnapshot condition to determine whether to pass a value to the DBSnapshotIdentifier property of an AWS::RDS::DBInstance resource. You use the AWS::NoValue pseudoparameter in place of a null value in AWS CloudFormation templates. When you provide it as a value to a resource property, AWS::NoValue removes that property declaration.

"MyDB" : {
  "Type" : "AWS::RDS::DBInstance",
  "Properties" : {
    "AllocatedStorage" : "5",
    "DBInstanceClass" : "db.m1.small",
    "Engine" : "MySQL",
    "EngineVersion" : "5.5",
    "MasterUsername" : { "Ref" : "DBUser" },
    "MasterUserPassword" : { "Ref" : "DBPassword" },
    "DBParameterGroupName" : { "Ref" : "MyRDSParamGroup" },
    "DBSnapshotIdentifier" : {
      "Fn::If" : [
        "UseDBSnapshot",
        {"Ref" : "DBSnapshotName"},
        {"Ref" : "AWS::NoValue"}
      ]
    }
  }
}

Transforms

As templates grow in size and complexity, there may be situations where you use certain components repeatedly across multiple templates, such as common resources or mappings. Transforms allow you to simplify the template authoring process through a powerful set of macros you use to reduce the amount of time spent in the authoring process. AWS CloudFormation transforms first create a change set for the stack. Transforms are applied to the template during the change set creation process.

There are two types of supported transforms.

AWS::Include Transform AWS::Include Transform acts as a tool to import template snippets from Amazon S3 buckets into the template being developed. When the template is evaluated, a change set is created, and the template snippet is copied from its location and is added to the overall template structure. You can use this transform anywhere in a template, except the Parameters and AWSTemplateFormatVersion sections.

When you use the AWS::Include Transform at the top level of a template, the syntax must match the example. (Note that the transform is declared as Transform.) This is especially useful if there is a set of common mappings that you use across multiple teams or template authors, as they can share this set and update it in one location.

{
  "Transform" : {
    "Name" : "AWS::Include",
    "Parameters" : {
      "Location" : "s3://MyAmazonS3BucketName/MyFileName.json"
    }
  }
}

When you use a transform in nested sections of a template, such as the Properties section of an AWS::EC2::Instance resource, use the following syntax. (Note that this is now an intrinsic function call.)

{
  "Fn::Transform" : {
    "Name" : "AWS::Include",
    "Parameters" : {
      "Location" : "s3://MyAmazonS3BucketName/MyFileName.json"
    }
  }
}

When you process stack updates, the template snippets you reference in any transforms pull from their Amazon S3 locations. This means that if a snippet updates without your knowledge, the updated snippet will import into the template. We recommend that you create change sets first so that any accidental updates can be caught before you deploy.

AWS::Serverless Transform You can use the AWS::Serverless Transform to convert AWS Serverless Application Model (AWS SAM) templates to valid AWS CloudFormation templates for deployment. AWS SAM uses an abbreviated template syntax to deploy serverless applications with AWS Lambda, Amazon API Gateway, and Amazon DynamoDB.

The following example creates a function that uses the serverless transform. When AWS CloudFormation evaluates the transform, the transform expands the template to include an AWS Lambda function and its IAM execution role.

Transform: AWS::Serverless-2016-10-31
Resources:
  MyServerlessFunctionLogicalID:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs4.3
      CodeUri: 's3://testBucket/mySourceCode.zip'

Resources

The Resources section of an AWS CloudFormation template declares the actual AWS resources to be provisioned and their properties. AWS CloudFormation requires this template section when you create stacks. The Resources section follows a standard syntax, where a logical ID acts as the resource key and type/properties subkeys define the actual type of resource to deploy and what properties it should have.

The logical ID of the resource allows it to be referenced in other parts of a template. You can refer to Resources in other sections of a template, build relationships between interdependent resources, output property values of the resources, perform other useful functions. The Resource Type defines the actual type of resource being managed. For example, an Amazon S3 bucket type is AWS::S3::Bucket. There are too many resource types available to list in this book, and they are updated regularly. Check the AWS CloudFormation documentation for available resource types.

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html

The resource properties section defines what configuration a resource should have. In the same example, the AWS::S3::Bucket resource has an optional property called BucketName, which defines the name of the bucket to create.

{
  "Resources": {
    "MyBucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "MyBucketName1234"
      }
    }
  }
}

Resource properties are either optional or required and may be any of the following types:

• String
• List of strings
• Boolean
• References to parameters or pseudoparameters
• Intrinsic functions

Outputs

Outputs are values that can be made available to use outside a single stack. You can reference these values in a number of different ways, such as cross-stack references, nested stacks, describe-stack API calls, or in the AWS CloudFormation console. Outputs are useful in providing meaningful information after a stack has been created or updated successfully. For example, it would be helpful to output an Elastic Load Balancing load balancer URL to the user when a web application stack deploys successfully.

The basic structure for AWS CloudFormation outputs follows. Similar to resources, outputs must have a logical ID so that AWS CloudFormation can reference them. The Description field provides a friendly explanation of the purpose of the output, which can be useful to users of your template. The value being returned can be produced using intrinsic functions, or it can be a static string value. Lastly, the Export key (optional) creates cross-stack references.

Here is an example of outputting the ELB load balancer URL:

"Outputs" : {
  "BackupLoadBalancerDNSName" : {
    "Description": "The DNSName of the backup load balancer",
    "Value" : { "Fn::GetAtt" : [ "BackupLoadBalancer", "DNSName" ]}
  }
}

Fn::Base64

The Fn::Base64 intrinsic function converts an input string into its Base64 equivalent. The primary purpose of this function is to pass instructions written in string format to an Amazon EC2 instance’s UserData property.

{ "Fn::Base64": valueToEncode }

Fn::Cidr

When you create Amazon VPCs and subnets, you must provide Classless Inter-Domain Routing (CIDR) blocks to map a group of IP addresses to the resource being created. The Fn::Cidr intrinsic function allows you to convert an IP address block, subnet count, and size mask (optional) into valid CIDR notation.

{ "Fn::Cidr": [ ipBlock, count, sizeMask ] }

Fn::FindInMap

After you create mappings in AWS CloudFormation, you use the Fn::FindInMap intrinsic function to query information stored within the mapping table. Note that mappings have two key levels, and thus top-level and second-level keys must be supplied as inputs, along with the mapping name itself.

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

Consider the following Mappings section. The Fn::FindInMap call would return ami-c9c7978c.

"Mappings" : {
  "RegionMap" : {
    "us-east-1" : { "32" : "ami-6411e20d", "64" : "ami-7a11e213" },
    "us-west-1" : { "32" : "ami-c9c7978c", "64" : "ami-cfc7978a" },
    "eu-west-1" : { "32" : "ami-37c2f643", "64" : "ami-31c2f645" }
  }
}
 
. . .
 
{ "Fn::FindInMap" : [ "RegionMap", { "Ref" : "AWS::Region" }, "32" ] }

Fn::GetAtt

Resources you create in AWS CloudFormation contain information that you can query in other parts of the same template. For example, if you create an IAM role to use when log in to AWS CloudTrail events to Amazon CloudWatch Logs, you must provide the Amazon Resource Name (ARN) of the AWS role to the trail configuration. Since the ARN is not returned when you use the Ref intrinsic function (this returns the role name), you can use Fn::GetAtt to query additional resource properties. In this case, you would be able to use this intrinsic function to determine the ARN of the role.

{ "Fn::GetAtt" : [ "logicalIDOfResource", "attributeName" ] }

Fn::GetAZs

For each AWS region, different availability zones (with different names) are available. The specific availability zones will not always match between different accounts (in fact, two accounts with the same availability zone by name may not use the same physical location). Because of this, it is not easy to determine which availability zones are usable when you create a stack. The Fn::GetAZs intrinsic function returns a list of availability zones for the account in which the stack is being created.

{ "Fn::GetAZs" : "region" }

To increase flexibility further and remove the need to hard-code a region in the template, you can use the AWS::Region pseudoparameter to return the list of availability zones for the region in which the stack is being created.

{ "Fn::GetAZs" : { "Ref": "AWS::Region" } }

Fn::Join

In some situations, string values must be concatenated from multiple input strings, as is the case when building Java Database Connectivity (JDBC) connection strings. AWS CloudFormation supports string concatenation with the Fn::Join intrinsic function. You can join string values with a predefined delimiter, which you supply to the function along with a list of strings to join.

When you define the UserData for an AWS::EC2::Instance resource, it may be required that you add various parameters to commands being run on the instance.

"Resources" : {
    "Ec2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "ImageId" : "ami-12345678",
        "Tags" : [ {"Key" : "Role", "Value" : "Test Instance"}],
        "UserData" : { "Fn::Base64" : { "Fn::Join" : [ "", [
          "#!/bin/bash -ex", "
",
          "echo deploying into region: ", { "Ref": "AWS::Region" }, "
",
          "
", "yum install ec2-net-utils -y", "
",
          "ec2ifup eth1", "
",
          "service httpd start" ] ] }
      }
    }
  }
}

Fn::Select

If you pass a list of values into your template, there needs to be a way to select an item from the list based on what position (index) it is in the list. Fn::Select allows you to choose an item in a list based on the zero-based index.

{ "Fn::Select" : [ index, listOfObjects ] }

Fn::Split

Counter to the Fn::Join intrinsic function, you use Fn::Split to create a list of strings by separating a single string by a known delimiter. You can use Fn::Select to access the output list of strings and pass them to an index to select from different substrings.

{ "Fn::Split" : [ "delimiter", "source string" ] }

Fn::Sub

If you need to build an input string with multiple variables determined at runtime, use the Fn::Sub function to populate a template string with input variables from a variable map.

This intrinsic function can also use parameters, resources, and resource attributes already present in your template. Note in the following example that two template values are present in the string, but only one mapping value is provided. This is because the AWS::AccountId pseudoparameter will automatically resolve to the account ID where the stack is being created, and AWS::Region automatically resolves to the region ID.

{
  "Fn::Sub": [ "arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}", {
    "vpc": { "Ref": "MyVPC" }
  }
}

Ref

You will use the Ref intrinsic function a lot within your template, especially when multiple resources have dependencies and relationships between one another (such as if you create an AWS::EC2::VPC resource with two AWS::EC2::Subnet resources). The behavior of the Ref function can differ slightly depending on the resource type being referenced. In some cases, such as with AWS::S3::Bucket or AWS::AutoScaling::AutoScalingGroup resources, you use Ref to return the resource name (in this situation, either the bucket or AWS Auto Scaling group name). In other cases, different properties such as the resource ARN or physical ID returns. Make sure to check the documentation for the resource type being referenced to verify what data returns.

{ "Ref" : "logicalName" }

Condition Functions

Condition functions are special intrinsic functions for which you can optionally create resources or set resource properties, depending on whether the condition evaluates to true or false. Other than Fn::If, you must use all other condition functions within the Conditions section of a template. The Fn::If intrinsic function allows you to pass different data to resource properties depending on the state of the referenced condition.

"Fn::And": [{condition}, {...}]

"Fn::Equals" : ["value_1", "value_2"]

"Fn::If": [condition_name, value_if_true, value_if_false]

"Fn::Not": [{condition}]

"Fn::Or": [{condition}, {...}]

AWS::CloudFormation::Init

This section defines what operations the cfn-init helper script performs on Amazon EC2 instances being provisioned by AWS CloudFormation (either as stand-alone instances or in AWS Auto Scaling groups). This metadata key allows you to develop a more declarative infrastructure configuration, instead of having to procedurally script every individual action (such as installing packages, which can vary based on the instance’s operating system).

This Metadata section is organized by config keys, which contain a list of configurations to apply.

"Resources": {
  "MyInstance": {
    "Type": "AWS::EC2::Instance",
    "Metadata" : {
      "AWS::CloudFormation::Init" : {
        "config" : {
          "packages" : { },
          "groups" :   { },
          "users" :    { },
          "sources" :  { },
          "files" :    { },
          "commands" : { },
          "services" : { }
        }
      }
    },
    "Properties": { }
  }
}

"packages": {
  "rpm" : {
    "epel" : "http://download.fedoraproject.org/pub/epel/5/i386/ epel-release-5-4.noarch.rpm"
              
  },
  "yum" : {
    "httpd" : [],
    "php" : [],
    "wordpress" : []
  }
}

"groups" : {
    "groupOne" : {},
    "groupTwo" : { "gid" : "45" }
}

"users" : {
    "myUser" : {
        "groups" : ["groupOne", "groupTwo"],
        "uid" : "50",
        "homeDir" : "/tmp"
    }
}

"sources" : {
  "/etc/myapp" : "https://s3.amazonaws.com/mybucket/myapp.tar.gz"
              
}

"files" : {
  "/tmp/setup.mysql" : {
    "content" : { "Fn::Join" : [ "", [
      "CREATE DATABASE ", { "Ref" : "DBName" }, ";
",
      "CREATE USER '", { "Ref" : "DBUsername" }, "'@'localhost' IDENTIFIED BY '",
      { "Ref" : "DBPassword" }, "';
",
      "GRANT ALL ON ", { "Ref" : "DBName" }, ".* TO '", { "Ref" : "DBUsername" },
      "'@'localhost';
",
      "FLUSH PRIVILEGES;
"
    ]]},
    "mode"  : "000644",
    "owner" : "root",
    "group" : "root"
  }
}

"commands" : {
  "test" : {
    "command" : "echo "$MAGIC" > test.txt",
    "env" : { "MAGIC" : "I come from the environment!" },
    "cwd" : "~",
    "test" : "test ! -e ~/test.txt",
    "ignoreErrors" : "false"
  },
  "test2" : {
    "command" : "echo "$MAGIC2" > test2.txt",
    "env" : { "MAGIC2" : "I come from the environment!" },
    "cwd" : "~",
    "test" : "test ! -e ~/test2.txt",
    "ignoreErrors" : "false"
  }
}

"services" : {
  "sysvinit" : {
    "nginx" : {
      "enabled" : "true",
      "ensureRunning" : "true",
      "files" : ["/etc/nginx/nginx.conf"],
      "sources" : ["/var/www/html"]
    }
  }
}

"AWS::CloudFormation::Init" : {
    "configSets" : {
        "ascending" : [ "config1" , "config2" ],
        "descending" : [ "config2" , "config1" ]
    },
    "config1" : {
        "commands" : {
            "test" : {
                "command" : "echo "$CFNTEST" > test.txt",
                "env" : { "CFNTEST" : "I come from config1." },
                "cwd" : "~"
            }
        }
    },
    "config2" : {
        "commands" : {
            "test" : {
                "command" : "echo "$CFNTEST" > test.txt",
                "env" : { "CFNTEST" : "I come from config2" },
                "cwd" : "~"
            }
        }
    }
}

"UserData" : { "Fn::Base64" :
  { "Fn::Join" : ["", [
     "#!/bin/bash -xe
",
     "# Install the files and packages from the metadata
",
     "/opt/aws/bin/cfn-init -v ",
     "         --stack ", { "Ref" : "AWS::StackName" },
     "         --resource WebServerInstance ",
     "         --configsets InstallAndRun ",
     "         --region ", { "Ref" : "AWS::Region" }, "
"
  ]]}
}

AWS::CloudFormation::Interface

This section details how to modify the ordering and presentation of parameters in the AWS CloudFormation console. Without this section, parameters display alphabetically without any additional clarification. This is especially useful when providing templates to other groups who are not familiar with the purpose of each input parameter.

The AWS::CloudFormation::Interface metadata key uses two child keys, ParameterGroups and ParameterLabels.

"Metadata" : {
  "AWS::CloudFormation::Interface" : {
    "ParameterGroups" : [ ParameterGroup, ... ],
    "ParameterLabels" : ParameterLabel
  }
}

"ParameterGroups" : [
    {
        "Label" : { "default" : "Network Configuration" },
        "Parameters" : [ "VPCID", "SubnetId", "SecurityGroupID" ]
    },
    {
        "Label" : { "default":"Amazon EC2 Configuration" },
        "Parameters" : [ "InstanceType", "KeyName" ]
    }
]

PARAMETERLABELS

The ParameterLabels section lets you define friendly names for parameters in the console. A logical ID such as BastionSecurityGroupName may be confusing to consumers of your template, especially if the template is shared outside your organization or team. By providing a more human-readable name, template portability is increased. The ParameterLabels key takes a list of parameter logical IDs, each of which has a friendly description as a subkey.

"ParameterLabels" : {
    "VPCID" : { "default" : "Which VPC should this be deployed to?" }
}

The inclusion of the AWS::CloudFormation::Interface definition results in an easy-to-understand list of parameters that you can complete, as shown in Figure 8.1.

AWS::CloudFormation::Designer

This Metadata section specifies the visual layout and representation of resources when you design templates in the AWS CloudFormation Designer. Since it is used by Designer, we do not recommend that you manually modify this section.

AWS Lambda Backed Custom Resources

Custom resources that are backed by AWS Lambda invoke functions whenever create, update, or delete actions are sent to the resource provider. This resource type is incredibly useful to reference other AWS services and resources that may not support AWS CloudFormation. Also, you can use them to look up data from other resources, such as Amazon EC2 instance IDs or entries in an Amazon DynamoDB table.

You can include the AWS Lambda function, which acts as a resource provider in the same AWS CloudFormation template that creates the custom resource and adds additional flexibility for stack update events. In this case, you can define the code for the AWS Lambda function itself inline in the template or store it in a separate location such as Amazon S3. The following example demonstrates a custom resource, AMIInfo, which makes use of an AWS Lambda function, AMIInfoFunction, as the resource provider. Two additional properties, Region and OSName, provide inputs to the resource provider.

"AMIInfo": {
  "Type": "Custom::AMIInfo",
  "Properties": {
    "ServiceToken": { "Fn::GetAtt" : ["AMIInfoFunction", "Arn"] },
    "Region": { "Ref": "AWS::Region" },
    "OSName": { "Ref": "WindowsVersion" }
  }
}

For the AWS Lambda function to execute successfully, you must supply it with an IAM role. If the function will interact with other AWS services, you need the following permissions at minimum:

• logs:CreateLogGroup
• logs:CreateLogStream
• logs:PutLogEvents

Custom Resources Associated with Amazon SNS

Although AWS Lambda functions are incredibly powerful and versatile, they have a limit of 5 minutes of execution time, at which point the function will exit prematurely. This may not be desirable, especially when custom resources take a long time to provision or update. In these situations, use custom resources associated with Amazon SNS.

With this resource type, notifications are sent to an Amazon SNS topic any time the custom resource triggers. As the developer you are responsible for managing the system that receives notifications and performs processing. For instance, transcoding of long video files may take a longer time than AWS Lambda allows. In these situations, you subscribe an Amazon EC2 instance to the Amazon SNS topic to listen for requests, consume the input request object, perform the transcoding work, and place an appropriate response.

Custom Resource Success/Failure

For a custom resource to be successful in AWS CloudFormation, the resource provider must return a success response to the presigned Amazon S3 URL that you provide in the request. If you do not provide a response, the custom resource will eventually time out. This is especially important with regard to update and delete actions. The custom resource provider will need to respond appropriately to every action type (create, update, and delete) for both successful and unsuccessful attempts. If you do not provide a response to an update action, for example, the entire stack update will fail after the custom resource times out, and this results in a stack rollback.

Creation Policies

There may be situations where a dependency is not enough, such as when you install and configure applications on an instance before you attach it to an elastic load balancer. In this case, you can use a CreationPolicy. A CreationPolicy instructs AWS CloudFormation not to mark a resource as CREATE_COMPLETE until the resource itself signals back to the service. You can configure the creation policy to require a specific number of signals in a certain amount of time; otherwise, the resource will show CREATE_FAILED. Signals sent to a resource are visible events in the AWS CloudFormation stack logs.

You can define creation policies with this syntax. When you configure creation policies for AWS Auto Scaling groups, you must specify the MinSuccessfulInstancesPercent property so that a certain percentage of instances in the group setup successfully complete before the group itself shows CREATE_COMPLETE. You can also configure creation policies to require a certain number of signals (Count) in a certain amount of time (Timeout). The following code example displays an AWS Auto Scaling group resource with a creation policy. This policy specifies that at least three signals must be received in 15 minutes for the group to create successfully.

"AutoScalingGroup": {
  "Type": "AWS::AutoScaling::AutoScalingGroup",
  "Properties": {
    "AvailabilityZones": { "Fn::GetAZs": "" },
    "LaunchConfigurationName": { "Ref": "LaunchConfig" },
    "DesiredCapacity": "3",
    "MinSize": "1",
    "MaxSize": "4"
  },
  "CreationPolicy": {
    "ResourceSignal": {
      "Count": "3",
      "Timeout": "PT15M"
    }
  }
}

Wait Conditions

You can use the WaitCondition property to insert arbitrary pauses until resources complete. If you require additional tracking of stack creation, you can use the WaitCondition property to add pauses to wait for external configuration tasks. An example of this would be if you create an Amazon DynamoDB table with a custom resource associated with AWS Lambda to load data into the table and then install software on an Amazon EC2 instance that reads data from the table. You can insert a WaitCondition into this template to prevent the creation of the instance until the custom resource function signals that data has been successfully loaded.

Wait conditions consist of two resources in a template, an AWS::CloudFormation:: WaitCondition (wait condition) and an AWS::CloudFormation::WaitConditionHandle (wait condition handle).

The first resource, the wait condition, is similar to a creation policy. It requires a signal count and timeout value. However, it also requires a reference to a wait condition handle. The wait condition handle acts as a reference to a presigned URL where signals are sent to AWS CloudFormation, which it monitors.

In the following example, the WebServerGroup resource creates an AWS Auto Scaling group with a count equal to the WebServerCapacity parameter. The example also creates a wait condition and wait condition handle, where the wait condition handle expects a number of signals equal to the WebServerCapacity parameter.

"WebServerGroup" : {
   "Type" : "AWS::AutoScaling::AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : { "Fn::GetAZs" : "" },
      "LaunchConfigurationName" : { "Ref" : "LaunchConfig" },
      "MinSize" : "1",
      "MaxSize" : "5",
      "DesiredCapacity" : { "Ref" : "WebServerCapacity" },
      "LoadBalancerNames" : [ { "Ref" : "ElasticLoadBalancer" } ]
   }
},
"WaitHandle" : {
   "Type" : "AWS::CloudFormation::WaitConditionHandle"
},
"WaitCondition" : {
   "Type" : "AWS::CloudFormation::WaitCondition",
   "DependsOn" : "WebServerGroup",
   "Properties" : {
      "Handle"  : { "Ref" : "WaitHandle" },
      "Timeout" : "300",
      "Count"   : { "Ref" : "WebServerCapacity" }
   }
}

With this approach, you need to ensure that the signal is sent to the wait condition handle. This is done in the Amazon EC2 instance’s user data, which you define in the launch configuration for AWS Auto Scaling groups. In this case, the LaunchConfig resource must include a signal to the wait condition handle. To do this, you reference the wait condition handle within the launch configuration’s UserData script.

"UserData" : {
   "Fn::Base64" : {
       "Fn::Join" : [ "", ["SignalURL=", { "Ref" : "myWaitHandle" } ] ]
   }
}

Within UserData, you can use a curl command to send the success signal back to AWS CloudFormation.

curl -T /tmp/a "WAIT_CONDITION_HANDLE_URL"

The file /tmp/a must be in the following format:

{
   "Status" : "SUCCESS",
   "Reason" : "Configuration Complete",
   "UniqueId" : "ID1234",
   "Data" : "Application has completed configuration."
}

The Data section of the JSON response can include arbitrary data about the signal. You can make it accessible in the AWS CloudFormation template with the Fn::GetAtt intrinsic function.

"Outputs": {
    "WaitConditionData" : {
        "Value" : { "Fn::GetAtt" : [ "mywaitcondition", "Data" ]},
        "Description" : "The data passed back as part of signalling the WaitCondition"
    }
}

CREATE_COMPLETE

The stack has created successfully.

CREATE_IN_PROGRESS

The stack is currently undergoing creation. No error has been detected.

CREATE_FAILED

One or more resources has failed to create successfully, causing the entire stack creation to fail. Review the stack failure messages to determine which resource(s) failed to create.

DELETE_COMPLETE

The stack has deleted successfully and will remain visible for 90 days.

DELETE_IN_PROGRESS

The stack is currently deleting.

DELETE_FAILED

The stack delete action has failed because of one or more underlying resources failing to delete. Review the stack output events to determine which resource(s) failed to delete. There you can manually delete the resource to prevent the stack delete from failing again.

ROLLBACK_COMPLETE

If a stack creation action fails to complete, AWS CloudFormation will automatically attempt to roll the stack back and delete any created resources. This status is achieved when the resources have been removed.

ROLLBACK_IN_PROGRESS

The stack has failed to create and is currently rolling back.

ROLLBACK_FAILED

If AWS CloudFormation is not able to delete resources that were provisioned during a failed stack create action, the stack will enter ROLLBACK_FAILED. The remaining resources will not be deleted until the error condition is corrected. Other than attempting to continue deleting the stack, no other actions can be performed on the stack itself. To resolve this, review the stack events to determine which resource(s) failed to delete.

UPDATE_COMPLETE

The stack has updated successfully.

UPDATE_IN_PROGRESS

The stack is currently performing an update.

UPDATE_COMPLETE_CLEANUP_IN_PROGRESS

When AWS CloudFormation updates certain resources, the type of update may require a replacement of the original physical resource. In these situations, AWS CloudFormation will first create the replacement resource and verify that the provision was successful. After all resources update, the stack will enter this phase and remove any previous resources. For example, when you update the Name property of an AWS::S3::Bucket resource, AWS CloudFormation will create a bucket with the new name value and then delete the previous bucket during the cleanup phase.

UPDATE_ROLLBACK_COMPLETE

If a stack update fails, AWS CloudFormation will attempt to roll the stack back to the last working state. Once complete, the stack will enter the UPDATE_ROLLBACK_COMPLETE state.

UPDATE_ROLLBACK_IN_PROGRESS

After a stack update fails, AWS CloudFormation begins to roll back any changes to bring the stack back to the last working state.

UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS

A failed rollback will require a cleanup of any newly created resources that would have originally replaced existing ones. During this phase, replacement resources are deleted in place of the originals.

UPDATE_ROLLBACK_FAILED

If the stack update fails and the rollback is unable to return it to a working state, it will enter UPDATE_ROLLBACK_FAILED. You can delete the entire stack. Otherwise, you can review to determine what failed to roll back and continue the update rollback again.

Update Policies

You use the AWS CloudFormation UpdatePolicy to determine how to respond to changes to AWS::AutoScaling::AutoScalingGroup and AWS::Lambda::Alias resources.

For AWS Auto Scaling group update policies, there are policies that you can enforce. These depend on the type of change you make and whether you configure the AWS Auto Scaling scheduled actions. Table 8.2 displays the types of policies that take effect under each scenario.

The AutoScalingReplacingUpdate policy defines how to replace updates. You can replace the entire AWS Auto Scaling group or only instances inside.

"UpdatePolicy" : {
  "AutoScalingReplacingUpdate" : {
    "WillReplace" : Boolean
  }
}

The AutoScalingRollingUpdate policy allows you to define the update process for instances in an AWS Auto Scaling group. This lets you configure the group to update instances all at once, in batches, or with an additional batch.

"UpdatePolicy" : {
  "AutoScalingRollingUpdate" : {
    "MaxBatchSize" : Integer,
    "MinInstancesInService" : Integer,
    "MinSuccessfulInstancesPercent" : Integer
    "PauseTime" : String,
    "SuspendProcesses" : [ List of processes ],
    "WaitOnResourceSignals" : Boolean
  }
}

Lastly, for AWS Auto Scaling groups, the AutoScalingScheduledAction property defines whether to adhere to the group sizes (minimum, maximum, and desired counts) you define in your template. If your AWS Auto Scaling group has enabled scheduled actions, there is a possibility that the actual group sizes no longer reflect those in the template. If you run an update without this policy set, it can cause the group to be reverted to its original size. If you configure the IgnoreUnmodifiedGroupSizeProperties property to true, it will cause AWS CloudFormation to ignore different group sizes when it compares the template to the actual AWS Auto Scaling group.

"UpdatePolicy" : {
  "AutoScalingScheduledAction" : {
    "IgnoreUnmodifiedGroupSizeProperties" : Boolean
  }
}

For changes to an AWS::Lambda::Alias resource, you can define the CodeDeployLambdaAliasUpdate policy. This controls whether a deployment is made with AWS CodeDeploy whenever it detects version changes.

"UpdatePolicy" : {
  "CodeDeployLambdaAliasUpdate" : {
    "AfterAllowTrafficHook" : String,
    "ApplicationName" : String,
    "BeforeAllowTrafficHook" : String,
    "DeploymentGroupName" : String
  }
}

In the previous examples, you only require the ApplicationName and DeploymentGroupName properties. These refer to the AWS CodeDeploy application and deployment group, which should update when the alias changes.

Deletion Policies

When you delete a stack, by default all underlying stack resources are also deleted. If this behavior is not desirable, apply the DeletionPolicy to resources in the stack to modify their behavior when the stack is deleted. You use deletion policies to preserve resources when you delete a stack (set DeletionPolicy to Retain). Some resources can instead have a snapshot or backup taken before you delete the resource (set DeletionPolicy to Snapshot). The following resource types support snapshots:

• AWS::EC2::Volume
• AWS::ElastiCache::CacheCluster
• AWS::ElastiCache::ReplicationGroup
• AWS::RDS::DBInstance
• AWS::RDS::DBCluster
• AWS::Redshift::Cluster

The following template example creates an Amazon S3 bucket with a deletion policy set to retain the bucket when you delete the stack.

{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Resources" : {
    "myS3Bucket" : {
      "Type" : "AWS::S3::Bucket",
      "DeletionPolicy" : "Retain"
    }
  }
}

Export and Import Stack Outputs

You can export stack output values to import them into other stacks in the same account and region. This allows you to share data that generates in one stack out to other stacks in your account. If, for example, you create a networking infrastructure such as an Amazon VPC in one stack, you can export the IDs of such resources from this stack and import them into others at a later date.

To export a stack value, update the Outputs section to include an Export declaration for every output you want to share.

"Outputs" : {
  "Logical ID" : {
    "Description" : "Information about the value",
    "Value" : "Value to return",
    "Export" : {
      "Name" : "Value to export"
    }
  }
}

After you declare the export and the stack creates or updates, it displays in the AWS CloudFormation console on the Exports tab, as shown in Figure 8.2.

To import this value into another stack, you use the Fn::ImportValue intrinsic function. This intrinsic function requires only the export name as an input parameter (the name present in the AWS CloudFormation console).

https://cloudformation.us-east-1.amazonaws.com/
 ?Action=ListImports
 &ExportName=SampleStack-MyExportedValue
 &Version=2010-05-15
 &X-Amz-Algorithm=AWS4-HMAC-SHA256
 &X-Amz-Credential=[Access key ID and scope]
 &X-Amz-Date=20160316T233349Z
 &X-Amz-SignedHeaders=content-type;host
 &X-Amz-Signature=[Signature]

Nesting with the AWS::CloudFormation::Stack Resource

You can manage stacks as resources within the service in AWS CloudFormation. A single parent stack can create one or more AWS::CloudFormation::Stack resources, which act as child stacks that the parent manages. The direct benefits of this are as follows:

• You can work around template limits that AWS CloudFormation imposes.
• It provides the ability to separate resources into logical groups, such as network, database, and web application.
• It lets you separate duties. (Each team is responsible only for maintaining their respective child stack.)

You can increase the nesting levels, as shown in Figure 8.3, with the AWS::CloudFormation::Stack resources.

You can share data from each nested stack if you use a combination of stack outputs and the Fn::GetAtt function calls. If there is an output value from a nested stack that you would like to access from its parent, the following syntax will let you access stack outputs.

{ "Fn::GetAtt" : [ "logicalNameOfChildStack", "Outputs.attributeName" ] }

Packaging Local Dependencies

When you develop templates locally, you may require additional files for your infrastructure that you do not want to define inline as part of the template syntax. For example, you may need to place configuration files on Amazon EC2 instances or AWS Lambda function code. You can use the aws cloudformation package command to upload local files and convert local references in your template to Amazon S3 URIs. Consider the following example:

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources:
  MyFunction:
    Type: 'AWS::Serverless::Function'
    Properties:
      Handler: index.handler
      Runtime: nodejs4.3
      CodeUri: /home/user/code/lambdafunction

The CodeUri property refers to a local path on the user’s workstation (/home/user/code/lambdafunction). To prepare this for deployment, you can run the following command:

aws cloudformation package --template /path_to_template/template.json --s3-bucket mybucket --output json > packaged-template.json

When you execute this command, the AWS CLI will package the contents of /home/user/code/lambdafunction into a .zip archive and upload it to the Amazon S3 bucket you specify in the --s3-bucket parameter. After doing so, the template updates to refer to the Amazon S3 URI for the archive file and generates the following:

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources:
  MyFunction:
    Type: 'AWS::Serverless::Function'
    Properties:
      Handler: index.handler
      Runtime: nodejs4.3
      CodeUri: s3://mybucket/lambdafunction.zip

Deploy Templates with Transforms

Any time that you want to deploy an AWS CloudFormation template that contains transforms, you must first create a change set. The change set is responsible for executing the transform to generate a final template that you can deploy. If you would like to reduce this to a one-step process, the aws cloudformation deploy command will generate and execute the change set on your behalf. This is especially useful for rapid testing, as it eliminates the need to approve change sets manually.

When you use this command, you can override default parameters with the --parameter-overrides property.

aws cloudformation deploy --template /path_to_template/my-template.json --stack-name my-new-stack --parameter-overrides Key1=Value1 Key2=Value2

cfn-init

You use this helper script to read AWS::CloudFormation::Init metadata from the AWS::EC2::LaunchConfiguration or AWS::EC2::Instance resource being declared. It is responsible for installing packages, adding files, creating users and groups, and any other configuration you specify in your AWS::CloudFormation::Init metadata.

AWS::CloudFormation::Init metadata is not enforced automatically. You must call the cfn-init helper script in your instances’ UserData. The following example demonstrates a cfn-init call on an instance in an AWS CloudFormation stack. In this case, the InstallAndRun configuration set executes on the instance.

"UserData" : { "Fn::Base64" :
  { "Fn::Join" : ["", [
     "#!/bin/bash -xe
",
     "# Install the files and packages from the metadata
",
     "/opt/aws/bin/cfn-init -v ",
     "         --stack ", { "Ref" : "AWS::StackName" },
     "         --resource WebServerInstance ",
     "         --configsets InstallAndRun ",
     "         --region ", { "Ref" : "AWS::Region" }, "
"
  ]]}
}

cfn-signal

After cfn-init has been called and the AWS::CloudFormation::Init metadata has been enforced successfully (or unsuccessfully), you can use cfn-signal to notify AWS CloudFormation that the instance has completed its configuration. For example, if your template contains a CreationPolicy or WaitCondition to prevent the setup of an AWS::ElasticLoadBalancing:: LoadBalancer resource until instances in your AWS::AutoScaling::AutoScalingGroup have configured a custom application, cfn-signal performs the notification. The following UserData example demonstrates how to pass the result of cfn-init to cfn-signal:

"UserData": {
  "Fn::Base64": {
    "Fn::Join": [
      "",
      [
        "#!/bin/bash -x
",
        "# Install the files and packages from the metadata
",
        "/opt/aws/bin/cfn-init -v ",
        "         --stack ", { "Ref": "AWS::StackName" },
        "         --resource MyInstance ",
        "         --region ", { "Ref": "AWS::Region" },
        "
",
        "# Signal the status from cfn-init
",
        "/opt/aws/bin/cfn-signal -e $? ",
        "         --stack ", { "Ref": "AWS::StackName" },
        "         --resource MyInstance ",
        "         --region ", { "Ref": "AWS::Region" },
        "
"
      ]
    ]
  }
}

cfn-get-metadata

If your template contains arbitrary metadata, use cfn-get-metadata to fetch this information for use on your instance(s). You can use this helper script to query either an entire metadata block or a subtree. AWS CloudFormation supports only top-level keys.

cfn-hup

Since AWS CloudFormation executes UserData only on resource creation, instances will not detect changes to AWS::CloudFormation::Init metadata automatically. Unlike other helper scripts, you can configure cfn-hup to run as a daemon on instances. This script checks for changes to resource metadata, can execute custom scripts whenever they are detected, and allows you to perform configuration updates on instances in a stack.

The cfn-hup helper script requires you to perform several configuration steps before it detects updates.

[main]
stack=<stack-name-or-id>

[hookname]
triggers=post.add or post.update or post.remove
path=Resources.<logicalResourceId> (.Metadata or  .PhysicalResourceId)(.<optionalMetadatapath>)
action=<arbitrary shell command>
runas=<runas user>

[hookname]
triggers=post.add or post.update or post.remove
path=Resources.<logicalResourceId> (.Metadata or  .PhysicalResourceId)(.<optionalMetadatapath>)
action=<arbitrary shell command>
runas=<runas user>
"LaunchConfig": {
  "Type" : "AWS::AutoScaling::LaunchConfiguration",
  "Metadata" : {
    "AWS::CloudFormation::Init" : {
      ...
      "/etc/cfn/hooks.d/cfn-auto-reloader.conf": {
        "content": { "Fn::Join": [ "", [
          "[cfn-auto-reloader-hook]
",
            "triggers=post.update
",
            "path=Resources.LaunchConfig.Metadata.AWS::CloudFormation::Init
",
            "action=/opt/aws/bin/cfn-init -v ",
            "         --stack ", { "Ref" : "AWS::StackName" },
            "         --resource LaunchConfig ",
            "         --configsets wordpress_install ",
            "         --region ", { "Ref" : "AWS::Region" }, "
",
            "runas=root
"
          ]]},
          "mode"  : "000400",
          "owner" : "root",
          "group" : "root"
}

Stack Set

A stack set acts as a logical container for stack information in an administrator account. Each stack set will contain information about the stacks you deploy to a single target account in one or more regions. You can configure stack sets to deploy to regions in a specific order and how many unsuccessful deployments are required to fail the entire deployment.

Stack Instance

Stack instances allow you to manage stacks in a target account, as shown in Figure 8.6. For example, if a stack set deploys to four regions in a target account, you create four stack instances. An update to a stack set propagates to all stack instances in all accounts and regions.

Stack Set Operations

When you perform operations on stack sets, you can configure how to control the flow of updates across accounts and regions. You can specify a maximum number or percentage of target accounts for concurrent deployment. Additionally, you can specify a maximum number of percentage of failures (per region). Lastly, you can configure delete operations to remove only the stack instances and stack set and leave the stack itself present in the target account. This option is useful when removing control from an administrator account for resources that need to remain operational in the target account.

Stack Set Permissions

For an administrator account to deploy to any target accounts, you must create a trust relationship between the accounts. To do this, you create an IAM role in each account.

The administrator account requires an IAM service role with permissions to execute stack set operations and assume an execution role in any target accounts. This service role must have a trust policy that allows cloudformation.amazonaws.com.

Any target accounts will require an execution role that you create in the administrator account, which the service role can assume. This execution role will require AWS CloudFormation permissions and permissions to manage any resources you define in the template being deployed by the stack set, as shown in Figure 8.7.

Target Account Gate

Before you create or update a stack set, evaluate potential blockers in target accounts. If a certain resource type is not available in different regions, for example, this can cause the stack set operation to fail. You can use a target account gate to perform evaluation tasks with AWS Lambda functions in the target account. Depending on the return value of the function, the stack set operation will either continue or stop. You can configure this so that account gate failures count toward the stack set’s configured tolerance settings.

Action Mode

You can use change sets in a pipeline to include a manual review step to ensure that the changes you deploy are valid and desired before they actually execute. AWS CodePipeline supports the following AWS CloudFormation actions:

• Create or replace a change set
• Create or update a stack
• Delete a stack
• Execute a change set
• Replace a failed stack

Stack or Change Set Name

These refer to the new or existing stack or change set to be created, updated, or deleted.

Template

This is the location of the template file to submit. Since AWS CodePipeline uses artifacts to pass files between stages, you must define this file within the artifact with the following:

ArtifactName::TemplateFileName

Template Configuration

The template configuration is where you specify properties such as template parameters and the stack policy.

Capabilities

You must specify any templates which create, update, or delete IAM resources with either the CAPABILITY_IAM or CAPABILITY_NAMED_IAM within this property.

Role Name

Unlike manually provisioned stacks, AWS CodePipeline requires a service role to assume when you perform actions in AWS CloudFormation.

Output File Name

This is an optional output that you can add to the output artifact after the deploy action completes. This will add any stack outputs to the pipeline output artifact.

Parameter Overrides

Though you can define parameters in the template configuration file, the parameter overrides section lets you specify a JSON input file to override any already-specified parameters. You can retrieve data from pipeline artifacts with the Fn::GetParam intrinsic function. The following example demonstrates how to specify a parameter override for ParameterName.

{
  "ParameterName" : {
    "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]
  }
}

Parameter overrides can leverage two intrinsic functions specific to AWS CodePipeline. These functions allow you to specify dynamic pipeline values and data from artifacts being passed through the pipeline.

{ "Fn::GetArtifactAtt" : [ "artifactName", "attributeName" ] }

{ "Fn::GetParam" : [ "artifactName", "JSONFileName", "keyName" ] }