AWS CloudFormation
User Guide (API 版本 2010-05-15)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

参数

使用可选的 Parameters 部分来自定义模板。利用参数,您能够在每次创建或更新堆栈时将自定义值输入模板。

在模板中定义参数

以下示例声明名为 InstanceTypeParameter 的参数。利用此参数,您可以为堆栈指定 Amazon EC2 实例类型以在创建或更新堆栈时使用。

请注意,InstanceTypeParameter 具有默认值 t2.micro。除非提供有其他值,否则这是 AWS CloudFormation 用于预置堆栈的值。

JSON

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

YAML

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.

在模板中引用参数

您使用 Ref 内部函数来引用某个参数,AWS CloudFormation 使用该参数的值来预置堆栈。您可以引用同一模板的 ResourcesOutputs 部分中的参数。

在以下示例中,EC2 实例资源的 InstanceType 属性引用了 InstanceTypeParameter 参数值:

JSON

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

YAML

Ec2Instance: Type: AWS::EC2::Instance Properties: InstanceType: Ref: InstanceTypeParameter ImageId: ami-2f726546

参数的一般要求

使用参数时存在以下要求:

  • 一个 AWS CloudFormation 模板中最多可包含 60 个参数。

  • 必须为每个参数提供一个逻辑名称 (也称为逻辑 ID),该名称必须是字母数字,并且在模板内的所有逻辑名称中必须是唯一的。

  • 必须向每个参数分配一个受 AWS CloudFormation 支持的参数类型。有关更多信息,请参阅类型

  • 必须向每个参数分配一个运行时的值,使 AWS CloudFormation 能够成功预置堆栈。您可以选择为要使用的 AWS CloudFormation 指定默认值,除非提供有其他值。

  • 必须在同一模板内声明和引用参数。您可以引用模板的 ResourcesOutputs 部分中的参数。

语法

Parameters 部分包括键名称 Parameters。对于此部分中的每个参数,您必须声明一个逻辑名称和类型。您可以选择指定其他属性。

AWS CloudFormation 支持以下参数类型:StringNumberList<Number>CommaDelimitedList、特定于 AWS 的类型或 SSM 参数类型。有关更多信息,请参阅类型

重要

对于敏感参数值(如密码),请将 NoEcho 属性设置为 true。这样一来,当有人描述您的堆栈时,参数值将显示为星号 (*****)。

JSON

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

YAML

Parameters: ParameterLogicalID: Type: DataType ParameterProperty: value

属性

AllowedPattern

一个正则表达式,表示要允许 String 类型使用的模式。

Required: No

AllowedValues

包含参数允许值列表的阵列。

Required: No

ConstraintDescription

用于在违反约束时说明该约束的字符串。例如,在没有约束条件描述的情况下,具有允许的 [A-Za-z0-9]+ 模式的参数会在用户指定无效值时显示以下错误消息:

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

通过添加约束描述 (如 must only contain upper and lowercase letters, and numbers),您可以显示以下自定义的错误消息:

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

Required: No

Default

模板适当类型的值,用于在创建堆栈时未指定值的情况下。如果您定义参数的约束条件,则必须指定一个符合这些约束条件的值。

Required: No

Description

用于描述参数的长度最多为 4000 个字符的字符串。

Required: No

MaxLength

一个整数值,确定要允许 String 类型使用的字符的最大数目。

Required: No

MaxValue

一个数字值,确定要允许 Number 类型使用的最大数字值。

Required: No

MinLength

一个整数值,确定要允许 String 类型使用的字符的最小数目。

Required: No

MinValue

一个数字值,确定要允许 Number 类型使用的最小数字值。

Required: No

NoEcho

在有人发出描述堆栈的调用时是否掩蔽参数值。如果将值设置为 true,则使用星号 (*****) 掩蔽参数值。

Required: No

Type

参数 (DataType) 的数据类型。

Required: Yes

AWS CloudFormation 支持以下参数类型:

String

一个文字字符串。

例如,用户可指定 "MyUserName"

Number

整数或浮点数。AWS CloudFormation 将参数值验证为数字;但当您在模板中的其他位置使用该参数时(例如,通过使用 Ref 内部函数),该参数值将变成字符串。

例如,用户可指定 "8888"

List<Number>

一组用逗号分隔的整数或浮点数。AWS CloudFormation 将参数值验证为数字,但当您在模板中的其他位置使用该参数时(例如,通过使用 Ref 内部函数),该参数值将变成字符串列表。

例如,用户可指定 "80,20",并且 Ref 将生成 ["80","20"]

CommaDelimitedList

一组用逗号分隔的文本字符串。字符串的总数应比逗号总数多 1。此外,会对每个成员字符串进行空间修剪。

例如,用户可指定 "test,dev,prod",并且 Ref 将生成 ["test","dev","prod"]

AWS 特定的参数类型

AWS 值,例如 Amazon EC2 密钥对名称和 VPC ID。有关更多信息,请参阅 AWS 特定的参数类型

SSM 参数类型

与 Systems Manager Parameter Store 中的现有参数对应的参数。您指定 Systems Manager 参数键作为 SSM 参数的值,并且 AWS CloudFormation 从 Parameter Store 提取最新值来用于堆栈。有关更多信息,请参阅 SSM 参数类型

注意

AWS CloudFormation 目前不支持 SecureString Systems Manager 参数类型。

AWS 特定的参数类型

对于 AWS 特定参数类型,模板用户必须指定其账户中的现有 AWS 值。AWS CloudFormation 对照用户 AWS 账户中的现有值来验证这些参数值。要在开始创建或更新堆栈时捕获无效值,特定于 AWS 的参数类型很有帮助。

AWS CloudFormation 针对用户账户中的现有值验证这些类型的输入值。例如,利用 AWS::EC2::VPC::Id 类型,用户必须输入位于其账户和要从中创建堆栈的区域中的现有 VPC ID

支持的特定于 AWS 的参数类型

AWS CloudFormation 支持以下 AWS 特定类型:

AWS::EC2::AvailabilityZone::Name

可用区,如 us-west-2a

AWS::EC2::Image::Id

Amazon EC2 映像 ID,如 ami-ff527ecf。请注意,AWS CloudFormation 控制台不会显示此参数类型的值的下拉列表。

AWS::EC2::Instance::Id

Amazon EC2 实例 ID,如 i-1e731a32

AWS::EC2::KeyPair::KeyName

Amazon EC2 密钥对名称。

AWS::EC2::SecurityGroup::GroupName

EC2-Classic 或默认 VPC 安全组名称,如 my-sg-abc

AWS::EC2::SecurityGroup::Id

安全组 ID,如 sg-a123fd85

AWS::EC2::Subnet::Id

子网 ID,如 subnet-123a351e

AWS::EC2::Volume::Id

Amazon EBS 卷 ID,如 vol-3cdd3f56

AWS::EC2::VPC::Id

VPC ID,如 vpc-a123baa3

AWS::Route53::HostedZone::Id

Route 53 托管区域 ID,如 Z23YXV4OVPL04A

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

针对某个区域的一组可用区,如 us-west-2a, us-west-2b

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

一组 Amazon EC2 映像 ID,如 ami-ff527ecf, ami-e7527ed7。请注意,AWS CloudFormation 控制台不会显示此参数类型的值的下拉列表。

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

一组 Amazon EC2 实例 ID,如 i-1e731a32, i-1e731a34

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

一组 EC2-Classic 或默认 VPC 安全组名称,如 my-sg-abc, my-sg-def

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

一组安全组 ID,如 sg-a123fd85, sg-b456fd85

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

一组子网 ID,如 subnet-123a351e, subnet-456b351e

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

一组 Amazon EBS 卷 ID,如 vol-3cdd3f56, vol-4cdd3f56

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

一组 VPC ID,如 vpc-a123baa3, vpc-b456baa3

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

一组 Route 53 托管区域 ID,如 Z23YXV4OVPL04A, Z23YXV4OVPL04B

SSM 参数类型

SSM 参数类型与 Systems Manager Parameter Store 中的现有参数对应。您指定 Systems Manager 参数键作为 SSM 参数的值,并且 AWS CloudFormation 从 Parameter Store 提取最新值来用于堆栈。有关 Systems Manager 参数的更多信息,请参阅 Systems Manager 用户指南 中的 Systems Manager Parameter Store

当您创建或更新堆栈并创建更改集时,AWS CloudFormation 会在此操作运行时使用 Parameter Store 中存在的任何值。如果某个指定的参数在调用方的 AWS 账户下的 Parameter Store 中不存在,AWS CloudFormation 会返回验证错误。

当您执行更改集时,AWS CloudFormation 将使用在更改集中指定的值。您应在执行更改集前检查这些值,因为在您创建更改集和执行更改集之间的时间内,它们可能会在 Parameter Store 中发生更改。

提示

您可以在控制台中或通过运行 describe-stacksdescribe-change-set 来查看堆栈的 Parameters 选项卡上 SSM 参数的解析值。这些是目前在堆栈定义中用于相应的 Systems Manager 参数键的值。请注意,这些值是在创建或更新堆栈时设置的,因此它们可能与 Parameter Store 中的最新值不同。

由于 SSM 参数的值是 Systems Manager 参数键,因此您应了解以下行为:

  • 对于堆栈更新,控制台中的 Use existing value 选项以及 update-stackUsePreviousValue 属性将告知 AWS CloudFormation 使用现有 Systems Manager 参数键而不是其值。AWS CloudFormation 在更新堆栈时始终从 Parameter Store 提取最新值。

  • AWS CloudFormation 可以对 Systems Manager 参数键执行验证,但不能对其对应的值执行验证。为了进行验证,您可以将参数键视为字符串。您应为 Parameter Store 中的 Systems Manager 参数值执行任何验证。

有关使用 SSM 参数类型的示例,请参阅 SSM 参数类型

支持的 SSM 参数类型

AWS CloudFormation 支持以下 SSM 参数类型:

AWS::SSM::Parameter::Name

Systems Manager 参数键的名称。

请在您要传递参数键时使用此参数。例如,您可以使用此类型验证此参数是否存在。

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

其值是字符串的 Systems Manager 参数。这与 Parameter Store 中的 String 参数对应。

AWS::SSM::Parameter::Value<List<String>> 或者 AWS::SSM::Parameter::Value<CommaDelimitedList>

其值是字符串列表的 Systems Manager 参数。这与 Parameter Store 中的 StringList 参数对应。

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

其值是特定于 AWS 的参数类型的 Systems Manager 参数。例如,下面指定了 AWS::EC2::KeyPair::KeyName 类型:

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

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

其值是特定于 AWS 的参数类型列表的 Systems Manager 参数。例如,下面指定了 AWS::EC2::KeyPair::KeyName 类型的列表:

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

不支持的 SSM 参数类型

AWS CloudFormation 不支持以下 SSM 参数类型:

  • SecureString Systems Manager 参数类型

  • SSM 参数类型的列表,例如:List<AWS::SSM::Parameter::Value<String>>

在 AWS CloudFormation 控制台中对参数进行分组和排序

使用 AWS CloudFormation 控制台创建或更新堆栈时,控制台根据输入参数的逻辑 ID 按照字母顺序列出输入参数。要覆盖默认排序方式,您可以使用 AWS::CloudFormation::Interface 元数据键。通过对参数进行分组和排序,用户可更轻松地指定参数值。例如,您可以将所有 VPC 相关参数放到一个组中,免得它们散落在按字母排序的列表中而难以查找。

在元数据键中,您可以指定要创建的组、每个组包含的参数以及控制台在其分组中显示各个参数时的顺序。此外,您还可以定义易记参数名称,以便控制台显示描述性名称而不是逻辑 ID。在元数据键中引用的所有参数都必须在模板的 Parameters 部分中声明。

有关更多信息和 AWS::CloudFormation::Interface 元数据键的示例,请参阅 AWS::CloudFormation::Interface

示例

基本输入参数

以下示例 Parameters 部分声明有两个参数。DBPort 参数属于 Number 类型,默认值为 3306。可指定的最小值为 1150,可指定的最大值为 65535DBPwd 参数属于 String 类型,无默认值。将 NoEcho 属性设置为 true 可阻止描述堆栈调用(如 AWS CLI 命令)返回参数值。aws cloudformation describe-stacks可指定的最小长度为 1,可指定的最大长度为 41。该模式允许小写和大写字母字符和数字。

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 特定的参数类型

当您使用 AWS 特定的参数类型时,使用您的模板创建或更新堆栈的任何人都必须指定其账户中和当前堆栈所在的区域中的现有 AWS 值。AWS 特定的参数类型可帮助确保在 AWS CloudFormation 创建或更新任何资源之前,这些类型的输入值存在且正确。例如,如果使用 AWS::EC2::KeyPair::KeyName 参数类型,AWS CloudFormation 在创建任何资源(如 Amazon EC2 实例)之前,将针对用户的现有密钥对名称验证输入值。

如果用户使用 AWS 管理控制台,则 AWS CloudFormation 向 AWS 特定的参数类型预填充有效值。这样一来,用户便无需记住和正确输入特定的名称或 ID,而只需从下拉列表中选择一个或多个值。此外,根据参数类型,用户还可以按 ID、名称或名称标签值来搜索值。有关更多信息,请参阅 指定堆栈名称和参数

以下示例声明类型 AWS::EC2::KeyPair::KeyNameAWS::EC2::Subnet::Id 的两个参数。这些类型限制现有密钥对名称和子网 ID 的有效值。因为将 mySubnetIDs 参数指定为列表,所以用户可指定一个或多个子网 ID。

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 和 API 支持

目前,用户无法使用 AWS CLI 或 AWS CloudFormation API 查看 AWS 特定的参数的有效值列表。但用户可通过使用 aws cloudformation get-template-summary 命令或 GetTemplateSummary API 来查看有关每个参数的信息,如参数类型。

逗号分隔列表参数类型

您可使用 CommaDelimitedList 参数类型在一个参数中指定多个字符串值。这样一来,您可使用一个参数而不是许多不同的参数来指定多个值。例如,如果您使用各自不同的 CIDR 块分别创建三个不同子网,则可以使用三个不同参数指定三个不同 CIDR 块。不过更简单的方法是使用包括三个 CIDR 块的列表的单个参数,如以下代码段所示:

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"

从逗号分隔列表参数返回值

要引用列表中的特定值,请在模板的 Resources 部分中使用 Fn::Select 内部函数。可传递所需对象的索引值和对象列表,如以下代码段所示:

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]

SSM 参数类型

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

以下模板声明 AWS::SSM::Parameter::Value<String> 参数类型。

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

以下命令基于示例模板创建堆栈。它提供 Systems Manager 参数键 (myInstanceType) 作为 InstanceType 模板参数的值。这假定 myInstanceType 参数在调用方的 AWS 账户下的 Parameter Store 中存在。

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

以下模板声明 AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> 参数类型。

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

以下命令基于示例模板创建堆栈。它提供 Systems Manager 参数键 (myLatestAMI) 作为 ImageId 模板参数的值。这假定 myLatestAMI 参数在调用方的 AWS 账户下的 Parameter Store 中存在。

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