Parameters

Use the optional Parameters section to customize your templates. Parameters enable you to input custom values to your template each time you create or update a stack.

Defining a parameter in a template

The following example declares a parameter named InstanceTypeParameter. This parameter lets you specify the Amazon EC2 instance type for the stack to use when you create or update the stack.

Note that InstanceTypeParameter has a default value of t2.micro. This is the value that Amazon CloudFormation uses to provision the stack unless another value is provided.

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

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

Referencing a parameter within a template

You use the Ref intrinsic function to reference a parameter, and Amazon CloudFormation uses the parameter's value to provision the stack. You can reference parameters from the Resources and Outputs sections of the same template.

In the following example, the InstanceType property of the EC2 instance resource references the InstanceTypeParameter parameter value:

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

Ec2Instance:
  Type: AWS::EC2::Instance
  Properties:
    InstanceType:
      Ref: InstanceTypeParameter
    ImageId: ami-0ff8a91507f77f867

General requirements for parameters

The following requirements apply when using parameters:

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

Parameters:
  ParameterLogicalID:
    Type: DataType
    ParameterProperty: value

Properties

Amazon-specific parameter types

Amazon-specific parameter types are helpful in catching invalid values at the start of creating or updating a stack. To specify parameters with Amazon-specific types, a template user must enter existing Amazon values that are in their Amazon account. Amazon CloudFormation validates these input values against existing values in the account. For example, with the AWS::EC2::VPC::Id parameter type, a user must enter an existing VPC ID that is in the account and region in which they are creating the stack.

If you want to allow template users to enter input values from different Amazon accounts, don't define parameters with Amazon-specific types; instead, define parameters of type String or CommaDelimitedList.

Supported Amazon-specific parameter types

Amazon CloudFormation supports the following Amazon-specific types:

SSM parameter types

SSM parameter types correspond to existing parameters in Systems Manager Parameter Store. You specify a Systems Manager parameter key as the value of the SSM parameter, and Amazon CloudFormation fetches the latest value from Parameter Store to use for the stack. For SSM parameters stored in the same Amazon Web Services account, enter the parameter name. For SSM parameters shared by another Amazon Web Services account, enter the full parameter ARN. For more information about Systems Manager parameters, see Systems Manager Parameter Store and Working with shared parameters in the Amazon Systems Manager User Guide.

You can also use the ssm or ssm-secure dynamic parameter pattern to specify parameter values in your template. For more information, see Using dynamic references to specify template values.

When you create or update stacks and create change sets, Amazon CloudFormation uses whatever values exist in Parameter Store at the time the operation is run. If a specified parameter doesn't exist in Parameter Store under the caller's Amazon account, Amazon CloudFormation returns a validation error.

When you execute a change set, Amazon CloudFormation uses the values that are specified in the change set. You should review these values before executing the change set because they might change in Parameter Store between the time that you create the change set and run it.

Because the value of an SSM parameter is a Systems Manager parameter key, you should be aware of the following behavior:

See SSM Parameter Types for examples that use SSM parameter types.

Supported SSM parameter types

Amazon CloudFormation supports the following SSM parameter types:

Unsupported SSM parameter types

Amazon CloudFormation doesn't support the following SSM parameter type:

In addition, Amazon CloudFormation does not support defining template parameters as SecureString Systems Manager parameter types. However, you can specify Secure Strings as parameter values for certain resources by using dynamic parameter patterns. For more information, see Using dynamic references to specify template values.

Grouping and sorting parameters in the Amazon CloudFormation console

When you use the Amazon 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 Amazon 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 alphabetical 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]*$"
  }
}

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]*$

Amazon-specific parameter types

When you use Amazon-specific parameter types, a user who uses your template to create or update a stack must specify existing Amazon values that are in the user's account and in the region for the current stack. Amazon-specific parameter types help ensure that input values for these types exist and are correct before Amazon CloudFormation creates or updates any resources. For example, if you use the AWS::EC2::KeyPair::KeyName parameter type, Amazon 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 Amazon Web Services Management Console, Amazon CloudFormation prepopulates Amazon-specific parameter types with valid values. That way the user doesn't have to remember and correctly enter a specific name or ID. They would just select 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.

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

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

Amazon CLI and API support

Currently, users can't use the Amazon CLI or Amazon CloudFormation API to view a list of valid values for Amazon-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:

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

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:

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

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]

SSM parameter types

AWS::SSM::Parameter::Value<String> type

The following template declares an AWS::SSM::Parameter::Value<String> parameter type.

{
  "Parameters": {
    "InstanceType": {
      "Type": "AWS::SSM::Parameter::Value<String>"
    }
  },
  "Resources": {
    "Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "InstanceType": {
          "Ref": "InstanceType"
        }
      }
    }
  }
}

Parameters: 
  InstanceType: 
    Type: 'AWS::SSM::Parameter::Value<String>'
Resources: 
  Instance: 
    Type: 'AWS::EC2::Instance'
    Properties: 
      InstanceType: !Ref InstanceType

The following command creates a stack based on the example template. It provides the Systems Manager parameter key (myInstanceType) as the value for the InstanceType template parameter. This assumes that the myInstanceType parameter exists in Parameter Store under the caller's Amazon account.

aws cloudformation create-stack --stack-name S1 --template-body example template --parameters ParameterKey=InstanceType,ParameterValue=myInstanceType

AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> type

The following template declares an AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> parameter type.

{
  "Parameters": {
    "ImageId": {
      "Type": "AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>"
    }
  },
  "Resources": {
    "Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": {
          "Ref": "ImageId"
        }
      }
    }
  }
}

Parameters: 
  ImageId: 
    Type: 'AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>'
Resources: 
  Instance: 
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: !Ref ImageId

The following command creates a stack based on the example template. It provides the Systems Manager parameter key (myLatestAMI) as the value for the ImageId template parameter. This assumes that the myLatestAMI parameter exists in Parameter Store under the caller's Amazon account.

aws cloudformation create-stack --stack-name S2 --template-body example template --parameters ParameterKey=ImageId,ParameterValue=myLatestAMI