CloudFormation 模板 Parameters 语法 - Amazon CloudFormation
语法属性参数的一般要求示例相关资源
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

CloudFormation 模板 Parameters 语法

使用可选的 Parameters 部分来自定义模板。利用参数，您能够在每次创建或更新堆栈时在模板中输入自定义值。通过在模板中使用参数，您可以构建可重复使用的灵活模板，以便根据具体场景进行自定义。

通过定义适当类型的参数，您可以在使用控制台创建堆栈时从现有资源的标识符列表中进行选择。有关更多信息，请参阅 使用 CloudFormation 提供的参数类型在运行时指定现有资源。

参数是指定堆栈资源属性值的一种常用方法。但是，可能会有一些因区域而异的设置，或是一些因其他条件或依赖关系而需要用户确定的复杂设置。在这些情况下，您可能需要将一些逻辑放入模板本身中，以便用户可以指定简单值（或不指定任何值）来获得期望的结果，例如通过使用映射。有关更多信息，请参阅 CloudFormation 模板 Mappings 语法。

语法

您需要在模板的 Parameters 部分声明参数，该部分会使用以下通用语法：

JSON

"Parameters" : {
  "ParameterLogicalID" : {
    "Description": "Information about the parameter",
    "Type" : "DataType",
    "Default" : "value",
    "AllowedValues" : ["value1", "value2"]
  }
}

YAML

Parameters:
  ParameterLogicalID:
    Description: Information about the parameter
    Type: DataType
    Default: value
    AllowedValues:
      - value1
      - value2

一个参数包含一系列属性，这些属性定义了其值但也限制了其值。唯一必需的属性是 Type，该属性可以是 String、Number 或 CloudFormation 提供的参数类型。您还可以添加 Description 属性来描述要指定的值的类型。在创建堆栈向导中使用该模板时，参数的名称和描述会在指定参数页面中显示。

注意

默认情况下，CloudFormation 控制台按照输入参数的逻辑 ID 的字母顺序列出这些参数。要覆盖此默认排序并将相关参数组合在一起，您可以在模板中使用 AWS::CloudFormation::Interface 元数据键。有关更多信息，请参阅 AWS::CloudFormation::Interface。

对于具有默认值的参数，CloudFormation 将使用默认值，除非用户指定其他值。如果省略默认属性，则用户将需要指定该参数的值。但是，要求用户输入值并不能确保该值有效。要验证参数的值，您可以声明一些约束或指定某个特定于 Amazon 的参数类型。

对于没有默认值的参数，用户必须在创建堆栈时指定一个键名称值。否则，CloudFormation 将无法创建堆栈并引发异常：

Parameters: [KeyName] must have values

属性

AllowedPattern

一个正则表达式，表示要允许 String 和 CommaDelimitedList 类型使用的模式。应用于类型为 String 的参数时，模式必须与提供的整个参数值匹配。应用于类型为 CommaDelimitedList 的参数时，模式必须与列表中的每个值匹配。

必需：否

AllowedValues

包含参数允许值列表的阵列。应用于类型为 String 的参数时，该参数值必须是允许的值之一。应用于类型为 CommaDelimitedList 的参数时，列表中的每个值都必须是指定的允许的值之一。

必需：否

注意

如果您使用 YAML，并且想要在 AllowedValues 中使用 Yes 和 No 字符串，请使用单引号来防止 YAML 解析器考虑这些布尔值。

ConstraintDescription

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

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

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

Malformed input-Parameter MyParameter must only contain uppercase and lowercase letters and numbers

必需：否

Default

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

必需：否

Description

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

必需：否

MaxLength

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

必需：否

MaxValue

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

必需：否

MinLength

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

必需：否

MinValue

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

必需：否

NoEcho

是否遮蔽参数值以防止在控制台、命令行或 API 中显示。如果您将 NoEcho 属性设置为 true，则对于描述堆栈或堆栈事件的任何调用，CloudFormation 返回使用星号 (*****) 遮蔽的参数值，但存储在下面指定位置的信息除外。

必需：否

重要

使用 NoEcho 属性不会遮蔽在以下各区段中存储的任何信息：

强烈建议您不要使用这些机制来包含敏感信息，例如密码。

重要

我们建议不要将敏感信息直接嵌入 CloudFormation 模板中，而应使用堆栈模板中的动态参数来引用在 CloudFormation 外部存储和管理的敏感信息，例如 Amazon Systems Manager Parameter Store 或 Amazon Secrets Manager 中的敏感信息。

有关更多信息，请参阅 请勿将凭证嵌入您的模板 最佳实践。

重要

我们建议不要在作为资源主标识符一部分的资源属性中包含 NoEcho 参数或任何敏感数据。

当 NoEcho 参数包含在构成主资源标识符的属性中时，CloudFormation 可能会在主资源标识符中使用实际明文值。此资源 ID 可能出现在任何派生输出或目标中。

要确定哪些资源属性构成了资源类型的主标识符，请参阅 Amazon 资源和属性类型参考中该资源的资源参考文档。在 Return values（返回值）部分，Ref 函数返回值，表示构成资源类型主标识符的资源属性。

Type

参数 (DataType) 的数据类型。

必需：是

CloudFormation 支持以下参数类型：

String

一个文字字符串。您可以使用以下属性来声明约束：MinLength、MaxLength、Default、AllowedValues 和 AllowedPattern。

例如，用户可指定 "MyUserName"。

Number

整型或浮点型。CloudFormation 将参数值作为数字进行验证；但当您在模板中的其他位置使用参数时（例如，通过使用 Ref 内置函数），该参数值将变为字符串。

您可以使用以下属性来声明约束：MinValue、MaxValue、Default 和 AllowedValues。

例如，用户可指定 "8888"。

List<Number>

以逗号分隔的整型或浮点型数组。CloudFormation 将参数值作为数字进行验证；但当您在模板中的其他位置使用参数时（例如，通过使用 Ref 内置函数），该参数值将变为字符串列表。

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

CommaDelimitedList

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

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

特定于 Amazon 的参数类型

Amazon 值，例如 Amazon EC2 密钥对名称和 VPC ID。有关更多信息，请参阅 在运行时指定现有资源。

Systems Manager 参数类型

与 Systems Manager Parameter Store 中的现有参数对应的参数。您指定 Systems Manager 参数键作为 Systems Manager 参数类型的值，然后 CloudFormation 从 Parameter Store 中检索最新的值来用于堆栈。有关更多信息，请参阅 在运行时指定现有资源。

参数的一般要求

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

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

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

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

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

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

示例

简单字符串参数

以下示例声明了一个名为 InstanceTypeParameter，类型为 String 的参数。利用此参数，您可以为堆栈指定 Amazon EC2 实例类型。如果在创建或更新堆栈期间未提供任何值，CloudFormation 将使用 t2.micro 的默认值。

JSON

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

YAML

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

密码参数

以下示例声明了一个名为 DBPwd，类型为 String 且没有默认值的参数。将 NoEcho 属性设置为 true 是为了防止在堆栈描述中显示参数值。可指定的最小长度为 1，可指定的最大长度为 41。该模式允许小写和大写字母字符和数字。此示例还演示了 AllowedPattern 属性的正则表达式用法。

JSON

"Parameters" : {
  "DBPwd" : {
    "NoEcho" : "true",
    "Description" : "The database admin account password",
    "Type" : "String",
    "MinLength" : "1",
    "MaxLength" : "41",
    "AllowedPattern" : "^[a-zA-Z0-9]*$"
  }
}

YAML

Parameters: 
  DBPwd: 
    NoEcho: true
    Description: The database admin account password
    Type: String
    MinLength: 1
    MaxLength: 41
    AllowedPattern: ^[a-zA-Z0-9]*$

引用参数

您可以使用 Ref 内置函数来引用某个参数，然后 CloudFormation 将使用该参数的值来预置堆栈。您可以引用同一模板的 Resources 和 Outputs 部分中的参数。

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

JSON

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

YAML

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

逗号分隔列表参数

需要为单个属性提供多个值时，CommaDelimitedList 参数类型可能非常实用。以下示例声明了一个名为 DbSubnetIpBlocks 的参数，其默认值为用逗号分隔的三个 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

{
    "Parameters": {
        "VPC": {
            "Type": "String",
            "Default": "vpc-123456"
        },
        "VpcAzs": {
            "Type": "CommaDelimitedList",
            "Default": "us-west-2a, us-west-2b, us-west-2c"
        },
        "DbSubnetIpBlocks": {
            "Type": "CommaDelimitedList",
            "Default": "172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26"
        }
    },
    "Resources": {
        "DbSubnet1": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    0,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        0,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        },
        "DbSubnet2": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    1,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        1,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        },
        "DbSubnet3": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    2,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        2,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        }
    }
}

YAML

Parameters:
  VPC:
    Type: String
    Default: vpc-123456
  VpcAzs:
    Type: CommaDelimitedList
    Default: us-west-2a, us-west-2b, us-west-2c
  DbSubnetIpBlocks:
    Type: CommaDelimitedList
    Default: 172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26
Resources:
  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

CloudFormation 还支持使用动态引用来动态指定属性值。例如，您可能需要引用存储在 Systems Manager Parameter Store 中的安全字符串。有关更多信息，请参阅 使用动态引用获取存储在其他服务中的值。

您也可以在 Ref 或 Sub 函数中使用伪参数来动态填充值。有关更多信息，请参阅 伪参数参考。