Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

Parameters

You can use the optional Parameters section to pass values into your template when you create a stack. With parameters, you can create templates that are customized each time you create a stack. Each parameter must contain a value when you create a stack. You can specify a default value to make the parameter optional so that you don't need to pass in a value when creating a stack. AWS CloudFormation will use the default value. For more information about creating stacks, see Working with Stacks.

EC2 Instance Type Parameter

The following example creates a parameter for Amazon EC2 instance types. When you create a stack, you can specify the value for the InstanceTypeParameter parameter. That way, you can choose what instance type you want when you create a stack. By default, the template uses t1.micro.

JSON

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

YAML

Parameters: 
  InstanceTypeParameter: 
    Type: String
    Default: t1.micro
    AllowedValues: 
      - t1.micro
      - m1.small
      - m1.large
    Description: Enter t1.micro, m1.small, or m1.large. Default is t1.micro.

Using the EC2 Instance Type Parameter

Within the same template, you can use the Ref intrinsic function to specify the parameter value in other parts of the template. The following snippet uses the InstanceTypeParameter parameter to specify the instance type for an EC2 instance resource:

JSON

"Ec2Instance" : {
  "Type" : "AWS::EC2::Instance",
  "Properties" : {
    "InstanceType" : { "Ref" : "InstanceTypeParameter" },
    "ImageId" : "ami-2f726546"
  }
}

YAML

Parameters: 
  InstanceTypeParameter: 
    Type: String
    Default: t1.micro
    AllowedValues: 
      - t1.micro
      - m1.small
      - m1.large
    Description: Enter t1.micro, m1.small, or m1.large. Default is t1.micro.

Syntax

The Parameters section consists of the key name Parameters. You can have a maximum of 60 parameters in an AWS CloudFormation template.

For each parameter, you must declare a logical name, which must be alphanumeric and unique among all logical names within the template. After you declare the parameter's logical name, you can specify the parameter's properties. You must declare parameters as one of following types: String, Number, CommaDelimitedList, or an AWS-specific type. For String, Number, and AWS-specific parameter types, you can define constraints that AWS CloudFormation uses to validate the value of the parameter.

AWS-specific parameter types are AWS values such as Amazon EC2 key pair names and VPC IDs. AWS CloudFormation validates these parameter values against existing values in users' AWS accounts. AWS-specific parameter types are helpful in catching invalid values at the start of creating or updating a stack.

Important

For sensitive parameter values (such as passwords), set the NoEcho property to true. That way, whenever anyone describes your stack, the parameter value is shown as asterisks (*****).

JSON

"Parameters" : {
  "ParameterLogicalID" : {
    "Type" : "DataType",
    "ParameterProperty" : "value"
  }
}

YAML

Parameters:
  ParameterLogicalID:
    Type: DataType
    ParameterProperty: value

Properties

AllowedPattern

A regular expression that represents the patterns you want to allow for String types.

Required: No

AllowedValues

An array containing the list of values allowed for the parameter.

Required: No

ConstraintDescription

A string that explains the constraint when the constraint is violated. For example, without a constraint description, a parameter that has an allowed pattern of [A-Za-z0-9]+ displays the following error message when the user specifies an invalid value:

Malformed input-Parameter MyParameter must match pattern [A-Za-z0-9]+

By adding a constraint description, such as must only contain upper- and lowercase letters, and numbers, you can display a customized error message:

Malformed input-Parameter MyParameter must only contain upper and lower case letters and numbers

Required: No

Default

A value of the appropriate type for the template to use if no value is specified when a stack is created. If you define constraints for the parameter, you must specify a value that adheres to those constraints.

Required: No

Description

A string of up to 4000 characters that describes the parameter.

Required: No

MaxLength

An integer value that determines the largest number of characters you want to allow for String types.

Required: No

MaxValue

A numeric value that determines the largest numeric value you want to allow for Number types.

Required: No

MinLength

An integer value that determines the smallest number of characters you want to allow for String types.

Required: No

MinValue

A numeric value that determines the smallest numeric value you want to allow for Number types.

Required: No

NoEcho

Whether to mask the parameter value whenever anyone makes a call that describes the stack. If you set the value to true, the parameter value is masked with asterisks (*****).

Required: No

Type

The data type for the parameter (DataType).

Required: Yes

You can specify the following values for the Type property:

String

A literal string.

For example, users could specify "MyUserName".

Number

An integer or float. AWS CloudFormation validates the parameter value as a number; however, when you use the parameter elsewhere in your template (for example, by using the Ref intrinsic function), the parameter value becomes a string.

For example, users could specify "8888".

List<Number>

An array of integers or floats that are separated by commas. AWS CloudFormation validates the parameter value as numbers; however, when you use the parameter elsewhere in your template (for example, by using the Ref intrinsic function), the parameter value becomes a list of strings.

For example, users could specify "80,20", and a Ref will result in ["80","20"].

CommaDelimitedList

An array of literal strings that are separated by commas. The total number of strings should be one more than the total number of commas. Also, each member string is space trimmed.

For example, users could specify "test,dev,prod", and a Ref will result in ["test","dev","prod"].

AWS-specific parameter types

For AWS-specific parameter types, template users must specify existing AWS values that are in their account. AWS CloudFormation supports the following AWS-specific types:

AWS::EC2::AvailabilityZone::Name

An Availability Zone, such as us-west-2a.

AWS::EC2::Image::Id

An Amazon EC2 image ID, such as ami-ff527ecf. Note that the AWS CloudFormation console won't show a drop-down list of values for this parameter type.

AWS::EC2::Instance::Id

An Amazon EC2 instance ID, such as i-1e731a32.

AWS::EC2::KeyPair::KeyName

An Amazon EC2 key pair name.

AWS::EC2::SecurityGroup::GroupName

An EC2-Classic or default VPC security group name, such as my-sg-abc.

AWS::EC2::SecurityGroup::Id

A security group ID, such as sg-a123fd85.

AWS::EC2::Subnet::Id

A subnet ID, such as subnet-123a351e.

AWS::EC2::Volume::Id

An Amazon EBS volume ID, such as vol-3cdd3f56.

AWS::EC2::VPC::Id

A VPC ID, such as vpc-a123baa3.

AWS::Route53::HostedZone::Id

An Amazon Route 53 hosted zone ID, such as Z23YXV4OVPL04A.

List<AWS::EC2::AvailabilityZone::Name>

An array of Availability Zones for a region, such as us-west-2a, us-west-2b.

List<AWS::EC2::Image::Id>

An array of Amazon EC2 image IDs, such as ami-ff527ecf, ami-e7527ed7. Note that the AWS CloudFormation console won't show a drop-down list of values for this parameter type.

List<AWS::EC2::Instance::Id>

An array of Amazon EC2 instance IDs, such as i-1e731a32, i-1e731a34.

List<AWS::EC2::SecurityGroup::GroupName>

An array of EC2-Classic or default VPC security group names, such as my-sg-abc, my-sg-def.

List<AWS::EC2::SecurityGroup::Id>

An array of security group IDs, such as sg-a123fd85, sg-b456fd85.

List<AWS::EC2::Subnet::Id>

An array of subnet IDs, such as subnet-123a351e, subnet-456b351e.

List<AWS::EC2::Volume::Id>

An array of Amazon EBS volume IDs, such as vol-3cdd3f56, vol-4cdd3f56.

List<AWS::EC2::VPC::Id>

An array of VPC IDs, such as vpc-a123baa3, vpc-b456baa3.

List<AWS::Route53::HostedZone::Id>

An array of Amazon Route 53 hosted zone IDs, such as Z23YXV4OVPL04A, Z23YXV4OVPL04B.

AWS CloudFormation validates input values for these types against existing values in a user's account. For example, with the AWS::EC2::VPC::Id type, a user must enter an existing VPC ID that is in her account and in the region in which she is creating the stack.

Group and Sort Parameters in the AWS CloudFormation Console

When you use the AWS CloudFormation console to create or update a stack, the console alphabetically lists input parameters by their logical ID. To override the default ordering, you can use the AWS::CloudFormation::Interface metadata key. By grouping and ordering parameters, you make it easier for users to specify parameter values. For example, you could group all VPC-related parameters so that they aren't scattered throughout an alphabetical list.

In the metadata key, you can specify the groups to create, the parameters to include in each group, and the order in which the console shows each parameter within its group. You can also define friendly parameter names so that the console shows descriptive names instead of logical IDs. All parameters that you reference in the metadata key must be declared in the Parameters section of the template.

For more information and an example of the AWS::CloudFormation::Interface metadata key, see AWS::CloudFormation::Interface.

Examples

Basic Input Parameters

The following example Parameters section declares two parameters. The DBPort parameter is of type Number with a default of 3306. The minimum value that can be specified is 1150, and the maximum value that can be specified is 65535. The DBPwd parameter is of type String with no default value. The NoEcho property is set to true to prevent describe stack calls, such as the aws cloudformation describe-stacks AWS CLI command, from returning the parameter value. The minimum length that can be specified is 1, and the maximum length that can be specified is 41. The pattern allows lowercase and uppercase alphabetic characters and numerals.

JSON

"Parameters" : {
  "DBPort" : {
    "Default" : "3306",
    "Description" : "TCP/IP port for the database",
    "Type" : "Number",
    "MinValue" : "1150",
    "MaxValue" : "65535"
  },
  "DBPwd" : {
    "NoEcho" : "true",
    "Description" : "The database admin account password",
    "Type" : "String",
    "MinLength" : "1",
    "MaxLength" : "41",
    "AllowedPattern" : "[a-zA-Z0-9]*"
  }
}

YAML

Parameters: 
  DBPort: 
    Default: 3306
    Description: TCP/IP port for the database
    Type: Number
    MinValue: 1150
    MaxValue: 65535
  DBPwd: 
    NoEcho: true
    Description: The database admin account password
    Type: String
    MinLength: 1
    MaxLength: 41
    AllowedPattern: "[a-zA-Z0-9]*"

AWS-Specific Parameter Types

When you use AWS-specific parameter types, anyone who uses your template to create or update a stack must specify existing AWS values that are in his account and in the region for the current stack. AWS-specific parameter types help ensure that input values for these types exist and are correct before AWS CloudFormation creates or updates any resources. For example, if you use the AWS::EC2::KeyPair::KeyName parameter type, AWS CloudFormation validates the input value against users' existing key pair names before it creates any resources, such as Amazon EC2 instances.

If a user uses the AWS Management Console, AWS CloudFormation prepopulates AWS-specific parameter types with valid values. That way the user doesn't have to remember and correctly enter a specific name or ID. She just selects one or more values from a drop-down list. Also, depending on the parameter type, users can search for values by ID, name, or Name tag value. For more information, see Specifying Stack Name and Parameters.

The following example declares two parameters with the types AWS::EC2::KeyPair::KeyName and AWS::EC2::Subnet::Id. These types limit valid values to existing key pair names and subnet IDs. Because the mySubnetIDs parameter is specified as a list, a user can specify one or more subnet IDs.

JSON

"Parameters" : {
  "myKeyPair" : {
    "Description" : "Amazon EC2 Key Pair",
    "Type" : "AWS::EC2::KeyPair::KeyName"
  },
  "mySubnetIDs" : {
    "Description" : "Subnet IDs",
    "Type" : "List<AWS::EC2::Subnet::Id>"
  }
}

YAML

Parameters: 
  myKeyPair: 
    Description: Amazon EC2 Key Pair
    Type: "AWS::EC2::KeyPair::KeyName"
  mySubnetIDs: 
    Description: Subnet IDs
    Type: "List<AWS::EC2::Subnet::Id>"

AWS CLI and API Support

Currently, users can't use the AWS CLI or AWS CloudFormation API to view a list of valid values for AWS-specific parameters. However, they can view information about each parameter, such as the parameter type, by using the aws cloudformation get-template-summary command or GetTemplateSummary API.

Comma-delimited List Parameter Type

You can use the CommaDelimitedList parameter type to specify multiple string values in a single parameter. That way, you can use a single parameter instead of many different parameters to specify multiple values. For example, if you create three different subnets with their own CIDR blocks, you could use three different parameters to specify three different CIDR blocks. But it's simpler just to use a single parameter that takes a list of three CIDR blocks, as shown in the following snippet:

JSON

"Parameters" : {
  "DbSubnetIpBlocks": {
    "Description": "Comma-delimited list of three CIDR blocks",
    "Type": "CommaDelimitedList",
    "Default": "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24"
  }
}

YAML

Parameters: 
  DbSubnetIpBlocks: 
    Description: "Comma-delimited list of three CIDR blocks"
    Type: CommaDelimitedList
    Default: "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24"

Return a Value from a Comma-delimited List Parameter

To refer to a specific value in a list, use the Fn::Select intrinsic function in the Resources section of your template. You pass the index value of the object that you want and a list of objects, as shown in the following snippet:

JSON
"DbSubnet1" : {
  "Type" : "AWS::EC2::Subnet",
  "Properties" : {
    "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "0", {"Ref" : "VpcAzs"} ] } ] ]} ,
    "VpcId" :  { "Ref" : "VPC" },
    "CidrBlock" : { "Fn::Select" : [ "0", {"Ref" : "DbSubnetIpBlocks"} ] }
  }
},
"DbSubnet2" : {
  "Type" : "AWS::EC2::Subnet",
  "Properties" : {
    "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "1", {"Ref" : "VpcAzs"} ] } ] ]} ,
    "VpcId" : { "Ref" : "VPC" },
    "CidrBlock" : { "Fn::Select" : [ "1", {"Ref" : "DbSubnetIpBlocks"} ] }
  }
},
"DbSubnet3" : {
  "Type" : "AWS::EC2::Subnet",
  "Properties" : {
    "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "2", {"Ref" : "VpcAzs"} ] } ] ]} ,
    "VpcId" : { "Ref" : "VPC" },
    "CidrBlock" : { "Fn::Select" : [ "2", {"Ref" : "DbSubnetIpBlocks"} ] }
  }
}
YAML
DbSubnet1:
  Type: AWS::EC2::Subnet
  Properties:
    AvailabilityZone: !Sub
      - "${AWS::Region}${AZ}"
      - AZ: !Select [0, !Ref VpcAzs]
    VpcId: !Ref VPC
    CidrBlock: !Select [0, !Ref DbSubnetIpBlocks]
DbSubnet2: 
  Type: AWS::EC2::Subnet
  Properties:
    AvailabilityZone: !Sub
      - "${AWS::Region}${AZ}"
      - AZ: !Select [1, !Ref VpcAzs]
    VpcId: !Ref VPC
    CidrBlock: !Select [1, !Ref DbSubnetIpBlocks]
DbSubnet3: 
  Type: AWS::EC2::Subnet
  Properties:
    AvailabilityZone: !Sub
      - "${AWS::Region}${AZ}"
      - AZ: !Select [2, !Ref VpcAzs]
    VpcId: !Ref VPC
    CidrBlock: !Select [2, !Ref DbSubnetIpBlocks]