AWS CloudFormation Template Anatomy

Template is a JSON or YAML formatted text file that describes your AWS infrastructure. The following examples show an AWS CloudFormation template structure and its sections. A CloudFormation template is structured into ten parts:

1. Format version (optional): The latest template format version is 2010-09-09, and this is currently the only valid value. Specify this version; the default is to use the latest version, which will cause problems if new versions are introduced in the future. 

2. Description (optional): What is this template about? 

3. Metadata (optional): Objects that provide additional information about the template. 

4. Parameters (optional): Parameters are used to customize a template with values: for example, domain name, customer ID, and database password. 

5. Rules: Validates a parameter or a combination of parameters passed to a template during a stack creation or stack update. 

6. Mappings (optional): A mapping of keys and associated values that you can use to specify conditional parameter values, similar to a lookup table. You can match a key to a corresponding value by using the Fn::FindInMap intrinsic function in the Resources and Outputs sections. 

7. Conditions (optional): Conditions that control whether certain resources are created or whether certain resource properties are assigned a value during stack creation or update. For example, you could conditionally create a resource that depends on whether the stack is for a production or test environment. 

8. Transform (optional): For serverless applications (also referred to as Lambda-based applications), specifies the version of the AWS Serverless Application Model (AWS SAM) to use. 

9. Resources (required): A resource is the smallest block you can describe. Examples are a virtual machine, a load balancer, or an Elastic IP address. 

10. Outputs(optional): An output is comparable to a parameter, but the other way around. An output returns something from your template, such as the public name of an EC2 instance. 

Format version (optional)

The AWSTemplateFormatVersion section identifies the capabilities of the template. The latest template format version is 2010-09-09 and is currently the only valid value. The AWSTemplateFormatVersion is an optional section, if you don’t, CloudFormation will use whatever version is the latest one. If you don’t specify it takes new format version is if introduced in the future, you’ll end up using the wrong format and get into serious trouble.

Description (optional)

Description is optional section; it is recommended to add description defining what the template is about. A meaningful description will help you in the future to remember what the template is for. It will also help your coworkers.

Metadata (optional)

Metadata is optional. This can be used to add data about data that provide details about the template. For example, you can include template implementation details about specific resources, as shown in the following snippet:

You can use any keys for Metadata. Also there are some predefined keys to retrieve settings or configuration information that you define in the Metadata section.

AWS::CloudFormation::Init

Defines configuration tasks for the cfn-init helper script. This script is useful for configuring and installing applications on EC2 instances.

AWS::CloudFormation::Interface

Defines the grouping and ordering of input parameters when they are displayed in the AWS CloudFormation console. By default, the AWS CloudFormation console alphabetically sorts parameters by their logical ID.

AWS::CloudFormation::Designer

Describes how your resources are laid out in AWS CloudFormation Designer (Designer). Designer automatically adds this information when you use it to create and update templates.

Parameters (optional)

Use the optional Parameters section to customize your templates. Parameters enable you to input custom values to your template each time you create or update a stack. A parameter has at least a name and a type. We encourage you to add a description as well.

Below table list out the allowed valid Types:

In addition to using the Type and Description properties, you can enhance a parameter with the properties listed in below table:

Rules (optional)

Rules are used to validate parameter values before creating or updating resources.  Rule is formed using two elements:

1. RuleCondition: This is optional and if specified it decides whether to apply rule or not 

2. Assertions: This is mandatory in rules and describes what values users can specify for a particular parameter. 

Rules Syntax

Rule-specific intrinsic functions

RuleConditions and Assertions are formed using rule-specific intrinsic functions. You can nest functions, but the final result of a rule condition or assertion must be either true or false. You can use the following rule-specific intrinsic functions to define rule conditions and assertions:

Functions

• Fn::And 

• Fn::Contains 

• Fn::EachMemberEquals 

• Fn::EachMemberIn 

• Fn::Equals 

• Fn::Not 

• Fn::Or 

• Fn::RefAll 

• Fn::ValueOf 

• Fn::ValueOfAll 

• Supported Functions 

• Supported Attributes 

Examples

In the following example, the two rules check the value of the InstanceType parameter. Depending on the value of the environment parameter (test or prod), the user must specify a1.medium or a1.large for the InstanceType parameter. The InstanceType and Environment parameters must be declared in the Parameters section of the same template. If you see !Ref NameOfSomething, think of it as a placeholder for what is referenced by the name.

Yaml hints:

- (Hyphen) is used to add array element

! (exclamation mark)  is used to add non-specific tag

Resources (required)

The resources section is mandatory to declare the AWS resources that you want to include in the stack, such as an Amazon EC2 instance or an Amazon S3 bucket.

Resources syntax

When defining resources, you need to know about the type and that type’s properties. An example of a single EC2 instance follows. If you see !Ref NameOfSomething, think of it as a placeholder for what is referenced by the name. You can reference parameters and resources to create dependencies.

Resource fields

Logical ID

The logical ID must be alphanumeric (A-Za-z0-9) and unique within the template. Use the logical name to reference the resource in other parts of the template. For example, if you want to map an Amazon Elastic Block Store volume to an Amazon EC2 instance, you reference the logical IDs to associate the block stores with the instance.

In addition to the logical ID, certain resources also have a physical ID, which is the actual assigned name for that resource, such as an EC2 instance ID or an S3 bucket name. Use the physical IDs to identify resources outside of AWS CloudFormation templates, but only after the resources have been created. For example, suppose you give an EC2 instance resource a logical ID of MyEC2Instance. When AWS CloudFormation creates the instance, AWS CloudFormation automatically generates and assigns a physical ID (such as i-28f9ba55) to the instance. You can use this physical ID to identify the instance and view its properties (such as the DNS name) by using the Amazon EC2 console. For resources that support custom names, you can assign your own names (physical IDs) to help you quickly identify resources. For example, you can name an S3 bucket that stores logs as MyPerformanceLogs. For more information, see Name type.

Resource type

The resource type identifies the type of resource that you are declaring. For example, AWS::EC2::Instance declares an EC2 instance. For a list of all resource types, see AWS resource and property types reference.

Resource properties

Resource properties are additional options that you can specify for a resource. For example, for each EC2 instance, you must specify an Amazon Machine Image (AMI) ID for that instance. You declare the AMI ID as a property of the instance, as shown in the following example:

Each resource type will be having its own set of properties, example AWS::EC2::Instance type has properties which you can refer from AWS documents here AWS::EC2::Instance Properties.

Resource Examples

The following example shows a resource declaration. It defines two resources. The MyInstance resource includes the MyQueue resource as part of its UserData property:

Outputs (optional)

A CloudFormation template’s output includes at least a name (like parameters and resources) and a value, but we encourage you to add a description as well. You can use outputs to pass data from within your template to the outside.

Resources syntax

Outputs fields

The Outputs section can include the following fields.

Logical ID

An identifier for the current output. The logical ID must be alphanumeric (a–z, A–Z, 0–9) and unique within the template.

Description (optional)

A String type that describes the output value. The value for the description declaration must be a literal string that's between 0 and 1024 bytes in length. You can't use a parameter or function to specify the description. The description can be a maximum of 4 K in length.

Value (required)

The value of the property returned by the aws cloudformation describe-stacks command. The value of an output can include literals, parameter references, pseudo-parameters, a mapping value, or intrinsic functions.

Export (optional)

The name of the resource output to be exported for a cross-stack reference.

You can use intrinsic functions to customize the Name value of an export. The following examples use the Fn::Join function.

Outputs Example

Mappings (optional)

The optional Mappings section matches a mapping Key to a corresponding array of key values.

You use the Fn::FindInMap intrinsic function to retrieve values in a map. For example, if you want to set values based on a region, you can create a mapping that uses the region name as a key and contains the values you want to specify for each specific region. You can't include parameters, pseudo parameters, or intrinsic functions in the Mappings section.

Mappings Example

The following example template contains an Amazon EC2 resource whose ImageId property is assigned by the FindInMap function. The FindInMap function specifies key as the region where the stack is created (using the AWS::Region pseudo parameter) and HVM64 as the name of the value to map to.

Conditions (optional)

The optional Conditions section is used to conditionally create resource or output in cloud formation.  After you define all your conditions, you can associate them with resources and resource properties in the Resources and Outputs sections of a template. At stack creation or stack update, AWS CloudFormation evaluates all the conditions in your template before creating any resources. Resources that are associated with a true condition are created. Resources that are associated with a false condition are ignored. AWS CloudFormation also re-evaluates these conditions at each stack update before updating any resources. Resources that are still associated with a true condition are updated. Resources that are now associated with a false condition are deleted.

Condition intrinsic functions

You can use the following intrinsic functions to define conditions:

1. Fn::And 

2. Fn::Equals 

3. Fn::If 

4. Fn::Not 

5. Fn::Or 

For the syntax and information about each function, see Condition functions.

Conditions Example

Transform (optional)

Transform section is used to define macro with set of processable content. A macro is a single instruction that expands automatically into a set of instructions to perform a particular task. AWS CloudFormation executes macros in the order that they're specified. When you create a change set, AWS CloudFormation generates a change set that includes the processed template content. You can then review the changes and execute the change set. For more information, see Using AWS CloudFormation macros to perform custom processing on templates.

AWS CloudFormation also supports transforms, which are macros hosted by AWS CloudFormation. AWS CloudFormation treats these transforms the same as any macros you create in terms of execution order and scope. For detailed information regarding specific transforms, see Transform reference.

To declare multiple macros, use a list format and specify one or more macros.

For example, in the template sample below, AWS CloudFormation evaluates MyMacro and then AWS::Serverless, both of which can process the contents of the entire template because of their inclusion in the Transform section.