# CloudFormation 模板 Parameters 语法 使用可选的 `Parameters` 部分来自定义模板。利用参数，您能够在每次创建或更新堆栈时在模板中输入自定义值。通过在模板中使用参数，您可以构建可重复使用的灵活模板，以便根据具体场景进行自定义。 通过定义适当类型的参数，您可以在使用控制台创建堆栈时从现有资源的标识符列表中进行选择。有关更多信息，请参阅 [使用 CloudFormation 提供的参数类型在运行时指定现有资源](cloudformation-supplied-parameter-types.md)。 参数是指定堆栈资源属性值的一种常用方法。但是，可能会有一些因区域而异的设置，或是一些因其他条件或依赖关系而需要用户确定的复杂设置。在这些情况下，您可能需要将一些逻辑放入模板本身中，以便用户可以指定简单值（或不指定任何值）来获得期望的结果，例如通过使用映射。有关更多信息，请参阅 [CloudFormation 模板 Mappings 语法](mappings-section-structure.md)。 ## 语法 您需要在模板的 `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 参数](aws-cloudformation-interface.md)。 对于具有默认值的参数，CloudFormation 将使用默认值，除非用户指定其他值。如果省略默认属性，则用户将需要指定该参数的值。但是，要求用户输入值并不能确保该值有效。要验证参数的值，您可以声明一些约束或指定某个特定于 AWS 的参数类型。 对于没有默认值的参数，用户必须在创建堆栈时指定一个键名称值。否则，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 返回使用星号 (\$1\$1\$1\$1\$1) 遮蔽的参数值，但存储在下面指定位置的信息除外。 *必需*：否 使用 `NoEcho` 属性不会遮蔽在以下各区段中存储的任何信息： + `Metadata` 模板区段。CloudFormation 不会转换、修改或编辑您在 `Metadata` 部分中包含的任何信息。有关更多信息，请参阅 [Metadata](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html)。 + `Outputs` 模板区段。有关更多信息，请参阅 [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html)。 + 资源定义的 `Metadata` 属性。有关更多信息，请参阅 [`Metadata` 属性](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-metadata.html)。 强烈建议您不要使用这些机制来包含敏感信息，例如密码。 我们建议不要将敏感信息直接嵌入 CloudFormation 模板中，而应使用堆栈模板中的动态参数来引用在 CloudFormation 外部存储和管理的敏感信息，例如 AWS Systems Manager Parameter Store 或 AWS Secrets Manager 中的敏感信息。 有关更多信息，请参阅[请勿将凭证嵌入您的模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/security-best-practices.html#creds)最佳实践。 我们建议不要在作为资源主标识符一部分的资源属性中包含 `NoEcho` 参数或任何敏感数据。 当 `NoEcho` 参数包含在构成主资源标识符的属性中时，CloudFormation 可能会在主资源标识符中使用*实际明文值*。此资源 ID 可能出现在任何派生输出或目标中。 要确定哪些资源属性构成了资源类型的主标识符，请参阅 [AWS 资源和属性类型参考](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-template-resource-type-ref.html)中该资源的资源参考文档。在 **Return values**（返回值）部分，`Ref` 函数返回值，表示构成资源类型主标识符的资源属性。 `Type` 参数 (`DataType`) 的数据类型。 *是否必需*：是 CloudFormation 支持以下参数类型： `String` 一个文字字符串。您可以使用以下属性来声明约束：`MinLength`、`MaxLength`、`Default`、`AllowedValues` 和 `AllowedPattern`。 例如，用户可指定 `"MyUserName"`。 `Number` 整型或浮点型。CloudFormation 将参数值作为数字进行验证；但当您在模板中的其他位置使用参数时（例如，通过使用 `Ref` 内置函数），该参数值将变为字符串。 您可以使用以下属性来声明约束：`MinValue`、`MaxValue`、`Default` 和 `AllowedValues`。 例如，用户可指定 `"8888"`。 `List` 以逗号分隔的整型或浮点型数组。CloudFormation 将参数值作为数字进行验证；但当您在模板中的其他位置使用参数时（例如，通过使用 `Ref` 内置函数），该参数值将变为字符串列表。 例如，用户可指定 `"80,20"`，并且 `Ref` 将生成 `["80","20"]`。 `CommaDelimitedList` 一组用逗号分隔的文本字符串。字符串的总数应比逗号总数多 1。此外，会对每个成员字符串进行空间修剪。 例如，用户可指定 `"test,dev,prod"`，并且 `Ref` 将生成 `["test","dev","prod"]`。 特定于 AWS 的参数类型 AWS 值，例如 Amazon EC2 密钥对名称和 VPC ID。有关更多信息，请参阅 [在运行时指定现有资源](cloudformation-supplied-parameter-types.md)。 Systems Manager 参数类型 与 Systems Manager Parameter Store 中的现有参数对应的参数。您指定 Systems Manager 参数键作为 Systems Manager 参数类型的值，然后 CloudFormation 从 Parameter Store 中检索最新的值来用于堆栈。有关更多信息，请参阅 [在运行时指定现有资源](cloudformation-supplied-parameter-types.md)。 ## 参数的一般要求 使用参数时存在以下要求： + 一个 CloudFormation 模板中最多可包含 200 个参数。 + 必须为每个参数提供一个逻辑名称（也称为逻辑 ID），该名称必须是字母数字，并且在模板内的所有逻辑名称中必须唯一。 + 必须向每个参数分配一个 CloudFormation 支持的参数类型。有关更多信息，请参阅[类型](#parameters-section-structure-properties-type)。 + 必须向每个参数分配一个运行时的值，这样 CloudFormation 才能成功预置堆栈。您可以选择为要使用的 CloudFormation 指定默认值，除非提供有其他值。 + 必须在同一模板内声明和引用参数。您可以引用模板的 `Resources` 和 `Outputs` 部分中的参数。 ## 示例 **Topics** + [简单字符串参数](#parameters-section-structure-example-1) + [密码参数](#parameters-section-structure-example-2) + [引用参数](#parameters-section-structure-example-3) + [逗号分隔列表参数](#parameters-section-structure-example-4) + [从逗号分隔列表参数返回值](#parameters-section-structure-example-5) ### 简单字符串参数 以下示例声明了一个名为 `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::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: !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 中的安全字符串。有关更多信息，请参阅 [使用动态引用获取存储在其他服务中的值](dynamic-references.md)。 您也可以在 `Ref` 或 `Sub` 函数中使用伪参数来动态填充值。有关更多信息，请参阅 [使用伪参数获取 AWS 值](pseudo-parameter-reference.md)。