Systems Manager parameter types

Systems Manager parameter types correspond to existing parameters in Systems Manager Parameter Store. You specify a Systems Manager parameter key as the value of the Systems Manager parameter type, and CloudFormation fetches the latest value from Parameter Store to use for the stack. This can be useful, for example, when you need to frequently update your application resources with changing values, such as Amazon Machine Image (AMI) IDs.

You can see the resolved values for Systems Manager parameters on the stack's Parameters tab in the console, or by running describe-stacks or describe-change-set. These are the values that are currently used in the stack definition for the corresponding Systems Manager parameter keys. Note that these values are set when the stack is created or updated, so they might differ from the latest values in Parameter Store.

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

• For stack updates, the Use existing value option in the console and the UsePreviousValue attribute for update-stack tell CloudFormation to use the existing Systems Manager parameter key—not its value. CloudFormation always fetches the latest values from Parameter Store when it updates stacks.

• CloudFormation can perform validation on Systems Manager parameter keys, but not on their corresponding values. For validation purposes, you can treat parameter keys as strings. You should do any validation for Systems Manager parameter values in Parameter Store.

When you create or update stacks and create change sets, 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 AWS account, CloudFormation returns a validation error.

When you execute a change set, 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.

For information about the Parameter Store, see Systems Manager Parameter Store.

Note

For Parameter Store parameters stored in the same AWS account, you must provide the parameter name. For Parameter Store parameters shared by another AWS account, you must provide the full parameter ARN.

Supported Systems Manager parameter types

CloudFormation supports the following Systems Manager parameter types:

AWS::SSM::Parameter::Name

The name of a Systems Manager parameter key.

Use this parameter when you want to pass the parameter key. For example, you can use this type to validate that the parameter exists.

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

A Systems Manager parameter whose value is a string. This corresponds to the String parameter type in Parameter Store.

AWS::SSM::Parameter::Value<List<String>> or AWS::SSM::Parameter::Value<CommaDelimitedList>

A Systems Manager parameter whose value is a list of strings. This corresponds to the StringList parameter type in Parameter Store.

AWS::SSM::Parameter::Value<AWS-specific parameter type>

A Systems Manager parameter whose value is an AWS-specific parameter type. For example, the following specifies the AWS::EC2::KeyPair::KeyName type:

AWS::SSM::Parameter::Value<AWS::EC2::KeyPair::KeyName>

AWS::SSM::Parameter::Value<List<AWS-specific parameter type>>

A Systems Manager parameter whose value is a list of AWS-specific parameter types. For example, the following specifies a list of AWS::EC2::KeyPair::KeyName types:

AWS::SSM::Parameter::Value<List<AWS::EC2::KeyPair::KeyName>>

Unsupported Systems Manager parameter types

CloudFormation doesn't support the following Systems Manager parameter type:

• Lists of Systems Manager parameter types—for example: List<AWS::SSM::Parameter::Value<String>>

In addition, CloudFormation doesn't support defining template parameters as SecureString Systems Manager parameter types. However, you can specify secure strings as parameter values for certain resources. For more information, see Specify values stored in other services with dynamic references.

Examples

AMI ID that references a Systems Manager public parameter as a default value

The <AWS::EC2::Image::Id> type is specifically for AMI ID parameters and supports public parameters provided by AWS.

The following example declares a parameter named LatestAmiId of type AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>. By default, the ImageId property of the EC2 instance references /aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2. This public parameter is an alias for the regional AMI ID value for the latest Amazon Linux 2 AMI. For more information about public parameters, see Finding public parameters in the AWS Systems Manager User Guide.

JSON

{
  "Parameters": {
    "LatestAmiId": {
      "Description": "Region specific image from the Parameter Store",
      "Type": "AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>",
      "Default": "/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2"
    }
  },
  "Resources": {
    "Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": {
          "Ref": "LatestAmiId"
        }
      }
    }
  }
}

YAML

Parameters: 
  LatestAmiId:
    Description: Region specific image from the Parameter Store
    Type: 'AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>'
    Default: '/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2'
Resources: 
  Instance: 
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: !Ref LatestAmiId

AMI ID that references a Systems Manager parameter and no default value

The following example declares a parameter named ImageId of type AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> with no default value. This means that you must provide the Systems Manager parameter key that references the desired AMI ID when creating the stack.

JSON

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

YAML

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 AWS account.

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

Referencing a Systems Manager string parameter

The following example declares a parameter named InstanceType of type AWS::SSM::Parameter::Value<String>. Because there's no default value, you must provide the Systems Manager parameter key that references the desired instance type when creating the stack.

JSON

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

YAML

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 AWS account.

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