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 Declaration

The optional Parameters section enables you to pass values into your template at stack creation time. Parameters let you create templates that can be customized for each stack deployment. When you create a stack from a template containing parameters, you can specify values for those parameters. Within the template, you can use the "Ref" intrinsic function to specify those parameter values in properties values for resources. For example, you can define a string parameter with the following Parameters section:

"Parameters" : {
    "URL" : {
      "Type" : "String"
    }
}

Note

If present, the Parameters section must declare at least one parameter. There can be a maximum of 60 parameters in an AWS CloudFormation template.

At runtime, you can use the --parameters option of aws cloudformation create-stack to set the URL parameter to a specific value:

aws cloudformation create-stack --stack-name MyStack --template-body file:///mytemplate.json --parameters ParameterKey=URL,ParameterValue=127.0.0.1

Multiple parameter assignments are separated with a space.

Note

By default, aws cloudformation describe-stacks returns parameter values. To prevent sensitive parameter values such as passwords from being returned, include a NoEcho property set to TRUE in your AWS CloudFormation template.

Parameters can have rules, called constraints, that determine valid values for a parameter. These constraints allow you to validate users' inputs before any resources are created. For example, you can have a constraint that a parameter string value must include only alphanumeric characters or that a numeric parameter value must be between 1 and 10.

Parameter Syntax and Properties

The Parameters section is composed of the key name Parameters, followed by a single colon. Braces enclose all parameter declarations. Parameters declared within the Parameters section are delimited by a comma.

Each parameter must declare a double-quoted name, followed by a colon. Parameter names must be alphanumeric and unique among all logical names within a template.

A parameter can be declared as one of following types: String, Number, or CommaDelimitedList. For a parameter that has a String or Number type, you can define constraints that AWS CloudFormation uses to validate the value of the parameter.

Parameters have the following properties:

PropertyRequiredDescription

Type

Yes

String, Number, or CommaDelimitedList.

A parameter of type String is simply a literal string.

A parameter of type Number can be an integer or float. Note that AWS CloudFormation validates the parameter as a number but uses the parameter value within the template as a string.

A parameter of type CommaDelimitedList is an array of literal strings separated by commas. The member strings are space trimmed and there is one more string than there are commas in the specified value.

Default

No

A value of the appropriate type for the template to use if no value is specified at stack creation. If the parameter has constraints defined, this value must adhere to those constraints.

NoEcho

No

If TRUE, the value of the parameter is masked with asterisks (*****) with aws cloudformation describe-stacks.

AllowedValues

No

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

AllowedPattern

No

String constraint. A regular expression that represents the patterns allowed in the parameter's string value.

MaxLength

No

String constraint. A integer value that determines the largest number of characters in the parameter's string value.

MinLength

No

String constraint. A integer value that determines the smallest number of characters in the parameter's string value.

MaxValue

No

Number constraint. A numeric value that determines the largest numeric value allowed for the parameter.

MinValue

No

Number constraint. A numeric value that determines the smallest numeric value allowed for the parameter.

Description

No

A String type up to 4000 characters describing the parameter.

ConstraintDescription

No

A String type explaining the constraint requirements that appears when the constraint is violated. For example, a parameter that has an AllowedPattern of "[A-Za-z0-9]+" would display this error message when the user specified an invalid value:

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

By adding a ConstraintDescription with a value "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

Parameter Examples

The following example Parameters section declares two parameters. The DBPort parameter is of type Number with a default of 3306 and a minimum value of 1150 and maximum value 65535. The DBPwd parameter is of type String with no default value, NoEcho is set to true to prevent aws cloudformation describe-stacks from returning the parameter value, minimum length of 1, maximum length of 41, and pattern that 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

To specify multiple values in a single parameter, use the CommaDelimitedList parameter type. 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"} ] }
    }
}