AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

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. For example, you can create a parameter for Amazon EC2 instance types, as shown in the following snippet:

"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."
  }
}

When you create a stack, you can specify the value for the InstanceTypeParameter. That way, you can choose what instance type you want when you create a stack. By default, the template uses t1.micro. Within the same template, you can use the Ref intrinsic function to specify the parameter value in other parts of the template, as shown in the following snippet:

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

Syntax and Properties

The Parameters section consists of the key name Parameters, followed by a single colon. Braces enclose all parameter declarations. If you declare multiple parameters, they are delimited by commas. You have a maximum of 60 parameters in an AWS CloudFormation template.

For each parameter, you must declare a logical name in quotation marks followed by a colon. The logical name 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, or CommaDelimitedList. For String or Number parameter types, you can define constraints that AWS CloudFormation uses to validate the value of the parameter.

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 (*****).

The following table describes all the properties for a parameter and whether a property is required:

PropertyRequiredDescription

Type

Yes

The data type for the parameter: String, Number, or CommaDelimitedList.

The String type is a literal string.

The Number type can be 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.

The CommaDelimitedList type is 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.

Default

No

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.

NoEcho

No

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 (*****).

AllowedValues

No

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

AllowedPattern

No

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

MaxLength

No

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

MinLength

No

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

MaxValue

No

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

MinValue

No

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

Description

No

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

ConstraintDescription

No

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

Examples

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.

"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]*"
  }
}

Comma-delimited Lists

You can use the CommaDelimitedList parameter type to specify multiple 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 comma-separated list of three CIDR blocks, as shown in the following snippet:

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

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:

"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"} ] }
  }
}