AWS CloudFormation
User Guide (API Version 2010-05-15)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

参数

您可使用可选的 Parameters 部分来在创建堆栈时将值传入模板。利用参数,您可创建每当创建堆栈时自定义的模板。创建堆栈时,每个参数都必须包含值。您可以指定默认值以使参数可选,这样在创建堆栈时就无需传入值。AWS CloudFormation 将使用默认值。有关创建堆栈的更多信息,请参阅使用堆栈

EC2 实例类型参数

下面的示例为 Amazon EC2 实例类型创建一个参数。在创建堆栈时,您可以为 InstanceTypeParameter 参数指定值。这样一来,您可在创建堆栈时选择所需的实例类型。默认情况下,模板使用 t2.micro

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.

使用 EC2 实例类型参数

在相同的模板中,您可以使用 Ref 内部函数指定模板的其他部分中的参数值。下面的代码段使用 InstanceTypeParameter 参数为 EC2 实例资源指定实例类型:

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

语法

Parameters 部分包括键名称 Parameters。一个 AWS CloudFormation 模板中最多可包含 60 个参数。

对于每个参数,您必须声明一个逻辑名称,该名称必须是字母数字,并且在模板内的所有逻辑名称中必须是唯一的。在声明参数的逻辑名称后,您可指定该参数的属性。您必须将参数声明为下列类型之一:StringNumberCommaDelimitedList 或 AWS 特定的类型。对于 StringNumber 和 AWS 特定的参数类型,您可定义 AWS CloudFormation 用于验证参数值的约束条件。

AWS 特定参数类型是 AWS 值,如 Amazon EC2 密钥对名称和 VPC ID。AWS CloudFormation 对照用户 AWS 账户中的现有值来验证这些参数值。要在开始创建或更新堆栈时捕获无效值,特定于 AWS 的参数类型很有帮助。

重要

对于敏感参数值(如密码),请将 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

您可以为 Type 属性指定以下值:

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 特定参数类型,模板用户必须指定其账户中的现有 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

Amazon 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>

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

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

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 cloudformation describe-stacks AWS CLI 命令)返回参数值。可指定的最小长度为 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]