CloudFormation Pseudo parameters are used in CloudFormation templates.
These parameters are predefined in AWS and their values are automatically set when a stack is created. You do not have to declare or initialize them. All you do is use it.
But why use Pseudo parameters in CloudFormation? What if any is the actual benefit?
What are Pseudo Parameters in CloudFormation?
Pseudo parameters are named variables in a CloudFormation template, whose values are automatically set by AWS. In other words, you do not have to provide an input value. It gets derived from your environmental attributes.
There are a total of 8 CloudFormation Pseudo parameters as shown in the mind map diagram below. Of them, AWS::Region and AWS:: StackID are the most frequently used Pseudo Parameters.
Let’s visualize an example on Pseudo Parameters. Picture the breakfast items at a fast-food restaurant. They are preset items and limited in options. You pick from the available options. They do not change on an hourly basis or daily basis.
An important point about Pseudo parameters – they are not the same as dynamic references in CloudFormation. This can get confusing, so let me clarify.
Dynamic references are limited to parameters in the AWS Systems Manager Parameter Store (ssn, ssm-secure) and AWS Secrets Manager(secretsmanager). Yes, they are dynamically populated, but are not the same as Pseudo parameters.
1. AWS:: AccountID
An AWS Account ID is a 12-digit number that uniquely identifies a user’s AWS account. When you create a stack using CloudFormation, the Account ID is part of Amazon Resource Name (ARN).
ARN’s uniquely identifies every resource deployed in AWS. You use this pseudo parameter when you have multiple AWS accounts or want to deploy a stack in a specific account.
JSON Format: { "Ref" : "AWS::AccountID" }
YAML Format: !Ref "AWS::AccountID"
2. AWS::NotificationARNs
The pseudo parameter AWS::NotificationARNs returns the list of Amazon Simple Notification Service(SNS) ARNs to which your stack related events are published.
Ideally, you use AWS:NotifictionARN’s with the Fn::Select intrinsic function.
JSON Format: { "Ref" : "AWS::NotificationARNs" }
YAML Format: !Ref "AWS::NotificationARNs"
3. AWS::NoValue
The CloudFormation pseudo parameter AWS:NoValue is used to tell CloudFormation to “do nothing”. The pseudo parameter does not return a value, thus ending the execution of that branch of logic.
AWS::NoValue is used in combination with the Fn::If condition function. Fn::If is basically the same as an if else statement.
JSON Format: {"Ref" : "AWS::NoValue"}
YAML Format: !Ref "AWS::NoValue"
4. AWS::Region
An AWS Region represents data centers that are physically isolated in different geographic areas.
Currently Amazon has 26 geographic Regions across North America, South America, Asia Pacific, China, Europe, Middle East and South Africa.
JSON Format: { "Ref" : "AWS::Region" }
YAML Format: !Ref "AWS::Region"
5. AWS::Partition
An AWS Partition is made up of one or more Regions. This is an important distinction to keep in mind.
You can use the AWS:Partition pseudo parameter to determine the Regions and the Services available within these regions. AWS Currently has 3 valid partitions.
- Public Partition: Identified as “aws“.
- AWS GovCoud : Limited to US Regions, this partition is meant for secure Cloud Solutions. Is is identified as “aws-us-gov“.
- AWS China: Identified as “aws-cn“.
JSON Format: { "Ref" : "AWS::Partition" }
YAML Format: !Ref "AWS::Partition"
6. AWS::StackName
A Stack is a grouping of AWS resources, treated as a single unit and deployed for a specific purpose. Creating a LAMP stack on an EC2 instance with a database or deploying SharePoint on a Microsoft Windows Server are some examples of stacks.
When you create a stack in CloudFormation, you have to assign it a unique name within the Region you are creating it. Once you assign the stack a name, any future references can use the AWS:StackName pseudo parameter.
JSON Format: { "Ref" : "AWS::StackName" }
YAML Format: !Ref "AWS::StackName"
7. AWS::StackID
A Stack ID is a unique identifier assigned to a stack. This is not the same as a Stack Name.
A Stack Name if you recall from above, is the name you assign to a stack on creation. Confused? Think of a Stack ID as an employee id, and Stack Name as an Employee Name.
Need a second example? A Stack ID is similar to the unique numeric code you find on an apple at a grocery store. While a Stack Name is the name of the fruit ( Fuji apple).
So, when should Stack ID’s be used vs Stack Names ?
You can use Stack ID’s or Stack Names when you run a stack. However, you absolutely have to use the Stack ID pseudo parameter when you delete a stack.
Best practice – Stick with the AWS::StackID.
JSON Format: { "Ref" : "AWS::StackID" }
YAML Format: !Ref "AWS::StackID"
8. AWS::URLSuffix
The CloudFormation pseudo parameter AWS:URLSuffix returns the region-specific domain for your environment. Currently, there are 2 region specific URL Suffixes.
- amazonaws.com – for all regions excluding China and AWS GovCloud (US).
- amazonaws.com.cn – for China.
JSON Format: { "Ref" : "AWS::URLSuffix" }
YAML Format: !Ref "AWS::URLSuffix"
Related post: CloudFormation Parameters:Make your life simple
1. Example for CloudFormation Pseudo Parameter AWS::NoValue
The below example is on Creating a basic Amazon Redshift Cluster.
The AWS::NoValue pseudo parameter is used in the Resources section of the CloudFormation template. It returns a NULL or “do nothing” if the Cluster Type is a single-node.
For the complete Redshift Cluster sample template, click here.
"Resources": {
"RedshiftCluster": {
"Type": "AWS::Redshift::Cluster",
"Properties": {
"ClusterType": { "Ref": "ClusterType" },
"NumberOfNodes": { "Fn::If": [ "IsMultiNodeCluster", { "Ref": "NumberOfNodes" },
{ "Ref": "AWS::NoValue" } ] },
"NodeType": { "Ref": "NodeType" },
"DBName": { "Ref": "DatabaseName" },
"MasterUsername": { "Ref": "MasterUsername" },
"MasterUserPassword": { "Ref": "MasterUserPassword" },
"ClusterParameterGroupName": { "Ref": "RedshiftClusterParameterGroup" }
}2. Example for CloudFormation Pseudo Parameter AWS::Region
The second example is on creating an Amazon EC2 instance with an Elastic IP address.
Again, the AWS::Region pseudo parameter is used in the Resources section to determine the Image ID for the EC2 instance. Image ID, short for Amazon Machine Image (AMI) ID is a package of Operating System, Software and Configuration details used to launch your instance.
For the complete Amazon EC2 sample template, click here.
"Resources" : {
"EC2Instance" : {
"Type" : "AWS::EC2::Instance",
"Properties" : {
"UserData" : { "Fn::Base64" : { "Fn::Join" : [ "", [ "IPAddress=", {"Ref" : "IPAddress"}]]}},
"InstanceType" : { "Ref" : "InstanceType" },
"SecurityGroups" : [ { "Ref" : "InstanceSecurityGroup" } ],
"KeyName" : { "Ref" : "KeyName" },
"ImageId" : { "Fn::FindInMap" : [ "AWSRegionArch2AMI", { "Ref" : "AWS::Region" },
{ "Fn::FindInMap" : [ "AWSInstanceType2Arch", { "Ref" : "InstanceType" }, "Arch" ] } ] } }
}
}
}
3. Example using Pseudo Parameters AccountID, StackName
This 3rd example is on Creating a website hosted on Amazon S3.
Pseudo parameters AWS::AccountID, AWS:StackName and AWS::Region are concatenated using the intrinsic function Fn:Join to create a domain name string for the Name parameter.
For the full sample template in JSON format, click here.
"Resources" : {
"WebsiteDNSName" : {
"Type" : "AWS::Route53::RecordSet",
"Properties" : {
"HostedZoneName" : { "Fn::Join" : [ "", [{ "Ref" : "HostedZone" }, "."]]},
"Comment" : "CNAME redirect custom name to CloudFront distribution",
"Name" : { "Fn::Join" : [ "", [{"Ref" : "AWS::StackName"}, {"Ref" : "AWS::AccountId"}, ".",
{"Ref" : "AWS::Region"}, ".", { "Ref" : "HostedZone" }]]},
"Type" : "CNAME",
"TTL" : "900",
"ResourceRecords" : [{ "Fn::Join" : [ "", ["http://", {"Fn::GetAtt" :
["WebsiteCDN", "DomainName"]} ]]}]
}
}
}
4. Example using CloudFormation Pseudo Parameters StackID
In this 4th and final example, we will look at creating a Virtual Private Cloud (VPC) with a single instance of EC2. The AWS::StackID pseudo parameter is used to tag the VPC.
As usual, our focus will be on the Resources section of the CloudFormation template.
A complete copy of the sample template can be found here.
"Resources" : {
"VPC" : {
"Type" : "AWS::EC2::VPC",
"Properties" : {
"CidrBlock" : "10.0.0.0/16",
"Tags" : [ {"Key" : "Application", "Value" : { "Ref" : "AWS::StackId"} } ]
}
}
}
Wrapping things up
CloudFormation Pseudo Parameters are not complicated. From personal experience, I highly recommend using them instead of hard coding values. Make it a best practice! Your peers will love you for it.
Keep the below key points in mind when using Pseudo Parameters.
- AWS Parameters are not the same as AWS Pseudo Parameters.
- Pseudo Parameters are not the same as dynamic References.
- AWS:Region, AWS:StackID and AWS::StackName are the most frequently used CloudFormation Pseudo Parameters.
- 90% of the time, the Resources section in your CloudFormation template is where you will end up using pseudo parameters.
