AWS DevOps Blog

Using the New CloudFormation Parameter Types

Invalid input for parameter values is the number one reason for stack creation failures. To make it easier to enter the correct parameter values and to improve parameter validation, the AWS CloudFormation team recently added the ability to set additional data types for parameters.

Parameter types enable CloudFormation to validate inputs earlier in the stack creation process. For example in the past if you entered an invalid key pair, you would have to wait until CloudFormation attempted to create the Amazon EC2 instance to see the problem. But now CloudFormation validates the value much earlier into the stack creation process. 

CloudFormation - Validation before parameter types

This benefit is highlighted with complex infrastructure, which takes longer to deploy. A good example would be a 2-tier application with a load-balanced web application backed by an RDS database. 

CloudFormation - Validation after parameter types

Parameter types also make it possible to show more intuitive user interfaces, such as a dropdown of VPC IDs, to users who use the console to create stacks. 

CloudFormation - Specify Parameters with Parameter Types

To set parameter types in your template, add a Type element to your parameter: 

"Parameters" : {
  "NameOfTheParameter" : {
    "Type" : "<Type Name>"
  }
}

CloudFormation currently supports the following parameter types:

  • String – A literal string
  • Number – An integer or float
  • List<Number> – An array of integers or floats
  • CommaDelimitedList – An array of literal strings that are separated by commas
  • AWS::EC2::KeyPair::KeyName – An Amazon EC2 key pair name
  • AWS::EC2::SecurityGroup::Id – A security group ID
  • AWS::EC2::Subnet::Id – A subnet ID
  • AWS::EC2::VPC::Id – A VPC ID
  • List<AWS::EC2::VPC::Id> – An array of VPC IDs
  • List<AWS::EC2::SecurityGroup::Id> – An array of security group IDs
  • List<AWS::EC2::Subnet::Id> – An array of subnet IDs

Let’s go through an example of how you can use an EC2 key pair and a list of EC2 security group IDs to deploy an EC2 instance.

EC2 Key Pair Parameter

Using an AWS-specific type, we add the EC2 key pair parameter. The type for EC2 key pair is “AWS::EC2::KeyPair::KeyName”.

"Parameters" : {
  "KeyName": {
    "Description": "Name of an existing EC2 KeyPair to enable SSH access to the instance",
    "Type": "AWS::EC2::KeyPair::KeyName",
    "ConstraintDescription": "must be the name of an existing EC2 KeyPair."
  }
}

Using the AWS custom type for the EC2 key pair validates any entered value against the existing EC2 key pairs in your account. The AWS console also displays a dropdown on the Specify Parameters form of the Create Stack wizard. 

CloudFormation - EC2 Key Pair Parameters with Parameter Types

EC2 Security Group IDs

Using another AWS-specific type, let’s add a parameter that contains a list of EC2 security groups IDs. The type for adding a list of EC2 Security Group IDs is “List<AWS::EC2::SecurityGroup::Id>”. 
"Parameters" : {
  "SecurityGroupIds": {
      "Description": "Security groups that can be used to access the EC2 instances",
      "Type": "List<AWS::EC2::SecurityGroup::Id>",
      "ConstraintDescription": "must be list of EC2 security group ids"
    }
}

Using the AWS Custom Type for the EC2 security group IDs validates any entered value against the existing EC2 security groups in your account. The AWS console also displays a multiselect box on the Specify Parameters form of the Create Stack wizard. 

CloudFormation - EC2 Security Group Ids with Parameter Types

Using the Parameters

You can now use the parameter types created above in the template and access them with the built-in intrinsic functions such as “Ref”. For example, the snippet below uses the EC2 key pair and EC2 security group ID parameters set up above to instantiate an EC2 instance. 

"Resources" : {
  "EC2Instance" : {
    "Type" : "AWS::EC2::Instance",
    "Properties" : {
      "InstanceType" : { "Ref" : "InstanceType" },
      "ImageId" : { "Ref" : "AMIImageId" },
      "SecurityGroupIds" : { "Ref" : "SecurityGroupIds" },
      "KeyName" : { "Ref" : "KeyName" }
    }
  }
}

More Information 

For more information please see the Parameters topic in the AWS CloudFormation User Guide.