本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 CloudFormation 提供的參數類型，在執行時期指定現有資源 建立範本時，您可以使用 CloudFormation 提供的專用參數類型，建立參數，要求使用者輸入現有 AWS 資源或 Systems Manager 參數的識別符。 **Topics** + [概觀](#cloudformation-supplied-parameter-types-overview) + [範例](#cloudformation-supplied-parameter-types-example) + [考量事項](#cloudformation-supplied-parameter-types-considerations) + [支援 AWS的特定參數類型](#aws-specific-parameter-types-supported) + [支援的 Systems Manager 參數類型](#systems-manager-parameter-types-supported) + [不支援的 Systems Manager 參數類型](#systems-manager-parameter-types-unsupported) ## 概觀 在 CloudFormation 中，可以透過在堆疊建立或更新期間提供輸入值，使用參數來自訂堆疊。此功能使得您的範本在不同案例中可重複使用且靈活。 在 CloudFormation 範本的 `Parameters` 區段中定義參數。每個參數都有名稱和類型，並且可以有額外的設定，例如預設值和允許的值。如需詳細資訊，請參閱[CloudFormation 範本 Parameters 語法](parameters-section-structure.md)。 參數類型會決定參數可以接受的輸入值類型。例如，`Number` 只接受數值，而 `String` 接受文字輸入。 CloudFormation 提供數種額外的參數類型，您可以在範本中用來參考現有的 AWS 資源和 Systems Manager 參數。 這些參數類型分為兩個類別： + **AWS特定參數類型** – CloudFormation 提供一組參數類型，可協助在建立或更新堆疊時擷取無效的值。當您使用這些參數類型時，使用範本的任何人都必須從他們建立堆疊所在的 AWS 帳戶 和 區域指定有效值。 如果他們使用 AWS 管理主控台，CloudFormation 會提供其帳戶和區域中現有值的預先填入清單。這樣，使用者不需要記住和正確輸入特定名稱或 ID。相反，他們只需從下拉式清單中選取值。在某些情況下，他們甚至可以依 ID、名稱或 `Name` 標籤值來搜尋值。 + **Systems Manager 參數類型** – CloudFormation 也提供對應於 Systems Manager 參數存放區中現有參數的參數類型。當您使用這些參數類型時，使用範本的任何人都必須指定參數存放區金鑰作為 Systems Manager 參數類型的值，然後 CloudFormation 會從參數存放區擷取最新的值，以便在其堆疊中使用。當您需要使用新的屬性值 (例如新的 Amazon Machine Image (AMI) ID) 來頻繁更新應用程式時，這會很有用。如需參數存放區的相關資訊，請參閱 [Systems Manager 參數存放區](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。 在 `Parameters` 區段中定義參數後，可以使用 `Ref` 函數在整個 CloudFormation 範本中參考參數值。 ## 範例 下列範例顯示使用下列參數類型的範本。 + `AWS::EC2::VPC::Id` + `AWS::EC2::Subnet::Id` + `AWS::EC2::KeyPair::KeyName` + `AWS::SSM::Parameter::Value` 若要從此範本中建立堆疊，必須在您的帳戶中指定現有的 VPC ID、子網路 ID 和金鑰對名稱。也可以指定參考所需 AMI ID 的現有參數存放區金鑰，或保留預設值 `/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2`。此公有參數是最新 Amazon Linux 2 AMI 的區域 AMI ID 別名。如需公有參數的詳細資訊，請參閱**《AWS Systems Manager 使用者指南》中的[探索參數存放區中的公有參數](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-finding-public-parameters.html)。 ### JSON ``` { "Parameters": { "VpcId": { "Description": "ID of an existing Virtual Private Cloud (VPC).", "Type": "AWS::EC2::VPC::Id" }, "PublicSubnetId": { "Description": "ID of an existing public subnet within the specified VPC.", "Type": "AWS::EC2::Subnet::Id" }, "KeyName": { "Description": "Name of an existing EC2 key pair to enable SSH access to the instance.", "Type": "AWS::EC2::KeyPair::KeyName" }, "AMIId": { "Description": "Name of a Parameter Store parameter that stores the ID of the Amazon Machine Image (AMI).", "Type": "AWS::SSM::Parameter::Value", "Default": "/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2" } }, "Resources": { "InstanceSecurityGroup": { "Type": "AWS::EC2::SecurityGroup", "Properties": { "GroupDescription": "Enable SSH access via port 22", "VpcId": { "Ref": "VpcId" }, "SecurityGroupIngress": [ { "IpProtocol": "tcp", "FromPort": 22, "ToPort": 22, "CidrIp": "0.0.0.0/0" } ] } }, "Ec2Instance": { "Type": "AWS::EC2::Instance", "Properties": { "KeyName": { "Ref": "KeyName" }, "ImageId": { "Ref": "AMIId" }, "NetworkInterfaces": [ { "AssociatePublicIpAddress": "true", "DeviceIndex": "0", "SubnetId": { "Ref": "PublicSubnetId" }, "GroupSet": [{ "Ref": "InstanceSecurityGroup" }] } ] } } }, "Outputs": { "InstanceId": { "Value": { "Ref": "Ec2Instance" } } } } ``` ### YAML ``` Parameters: VpcId: Description: ID of an existing Virtual Private Cloud (VPC). Type: AWS::EC2::VPC::Id PublicSubnetId: Description: ID of an existing public subnet within the specified VPC. Type: AWS::EC2::Subnet::Id KeyName: Description: Name of an existing EC2 KeyPair to enable SSH access to the instance. Type: AWS::EC2::KeyPair::KeyName AMIId: Description: Name of a Parameter Store parameter that stores the ID of the Amazon Machine Image (AMI). Type: AWS::SSM::Parameter::Value Default: /aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2 Resources: InstanceSecurityGroup: Type: AWS::EC2::SecurityGroup Properties: GroupDescription: Enable SSH access via port 22 VpcId: !Ref VpcId SecurityGroupIngress: - IpProtocol: tcp FromPort: 22 ToPort: 22 CidrIp: 0.0.0.0/0 Ec2Instance: Type: AWS::EC2::Instance Properties: KeyName: !Ref KeyName ImageId: !Ref AMIId NetworkInterfaces: - AssociatePublicIpAddress: "true" DeviceIndex: "0" SubnetId: !Ref PublicSubnetId GroupSet: - !Ref InstanceSecurityGroup Outputs: InstanceId: Value: !Ref Ec2Instance ``` ### AWS CLI 命令來建立堆疊 下列 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack.html) 命令會根據範例範本來建立堆疊。 ``` aws cloudformation create-stack --stack-name MyStack \ --template-body file://sampletemplate.json \ --parameters \ ParameterKey="VpcId",ParameterValue="vpc-a123baa3" \ ParameterKey="PublicSubnetId",ParameterValue="subnet-123a351e" \ ParameterKey="KeyName",ParameterValue="MyKeyName" \ ParameterKey="AMIId",ParameterValue="MyParameterKey" ``` 若要使用接受字串清單的參數類型，例如 `List`，您必須使用雙反斜線來轉義 `ParameterValue` 內的逗號，如下列範例所示。 ``` --parameters ParameterKey="SubnetIDs",ParameterValue="subnet-5ea0c127\\,subnet-6194ea3b\\,subnet-c87f2be0" ``` ## 考量事項 強烈建議您使用動態參考來限制存取敏感組態定義，例如第三方憑證。如需詳細資訊，請參閱[使用動態參考取得存放在其他服務中的值](dynamic-references.md)。 如果您想要允許範本使用者指定來自不同 的值 AWS 帳戶，請勿使用 AWS特定的參數類型。反之，請定義類型 `String` 或 `CommaDelimitedList` 的參數。 使用 Systems Manager 參數類型時需要記住幾件事： + 可以在主控台中或透過執行 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stacks.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stacks.html) 或 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-change-set.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-change-set.html)，查看堆疊的**參數**索引標籤中的已解析參數值。請謹記，這些值是在建立或更新堆疊時所設定，因此可能會與參數存放區中的最新值不同。 + 對於堆疊更新，當您使用**使用現有值**選項 (或 `UsePreviousValue` 設定為 true) 時，這表示您想要繼續使用相同的參數存放區金鑰，而不是其值。CloudFormation 始終會擷取最新的值。 + 如果您指定任何允許的值或其他限制條件，CloudFormation 會根據您指定的參數索引鍵進行驗證，但不會驗證其值。您應該驗證參數存放區本身中的值。 + 當您建立或更新堆疊並建立變更集時，CloudFormation 會使用參數存放區中當時存在的任何值。如果指定的參數不存在於發起人的 參數存放區中 AWS 帳戶，CloudFormation 會傳回驗證錯誤。 + 當您執行變更集時，CloudFormation 會使用變更集中所指定的值。您應該先檢閱這些值，再執行變更集，因為它們可能會在您建立變更集與執行變更集之間於參數存放區中變更。 + 對於存放在相同 中的參數存放區參數 AWS 帳戶，您必須提供參數名稱。對於另一個 AWS 帳戶共用的參數存放區參數，必須提供完整的參數 ARN。 ## 支援 AWS的特定參數類型 CloudFormation AWS支援下列特定類型： `AWS::EC2::AvailabilityZone::Name` 可用區域，例如 `us-west-2a`。 `AWS::EC2::Image::Id` Amazon EC2 映像 ID，例如 `ami-0ff8a91507f77f867`。請注意，CloudFormation 主控台不會顯示此參數類型的下拉式值清單。 `AWS::EC2::Instance::Id` Amazon EC2 執行個體 ID，例如 `i-1e731a32`。 `AWS::EC2::KeyPair::KeyName` Amazon EC2 金鑰對名稱。 `AWS::EC2::SecurityGroup::GroupName` 預設 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` 區域的可用區域陣列，例如 `us-west-2a, us-west-2b`。 `List` Amazon EC2 映像 ID 陣列，例如 `ami-0ff8a91507f77f867, ami-0a584ac55a7631c0c`。請注意，CloudFormation 主控台不會顯示此參數類型的下拉式值清單。 `List` Amazon EC2 執行個體 ID 陣列，例如 `i-1e731a32, i-1e731a34`。 `List` 預設 VPC 安全群組名稱陣列，例如 `my-sg-abc, my-sg-def`。 `List` 安全群組 ID 陣列，例如 `sg-a123fd85, sg-b456fd85`。 `List` 子網路 ID 陣列，例如 `subnet-123a351e, subnet-456b351e`。 `List` Amazon EBS 磁碟區 ID 陣列，例如 `vol-3cdd3f56, vol-4cdd3f56`。 `List` VPC ID 陣列，例如 `vpc-a123baa3, vpc-b456baa3`。 `List` Amazon Route 53 託管區域 ID 陣列，例如 `Z23YXV4OVPL04A, Z23YXV4OVPL04B`。 ## 支援的 Systems Manager 參數類型 CloudFormation 支援下列 Systems Manager 參數類型： `AWS::SSM::Parameter::Name` Systems Manager 參數索引鍵的名稱。僅使用此參數類型來檢查必要的參數是否存在。CloudFormation 不會擷取與參數相關聯的實際值。 `AWS::SSM::Parameter::Value` 值為字串的 Systems Manager 參數。這對應至參數存放區中的 `String` 參數類型。 `AWS::SSM::Parameter::Value>` 或 `AWS::SSM::Parameter::Value` 值為字串清單的 Systems Manager 參數。這對應至參數存放區中的 `StringList` 參數類型。 `AWS::SSM::Parameter::Value` 值為 AWS特定參數類型的 Systems Manager 參數。 例如，以下指定 `AWS::EC2::KeyPair::KeyName` 類型： + `AWS::SSM::Parameter::Value` `AWS::SSM::Parameter::Value>` Systems Manager 參數，其值是 AWS特定參數類型的清單。 例如，以下指定 `AWS::EC2::KeyPair::KeyName` 類型清單： + `AWS::SSM::Parameter::Value>` ## 不支援的 Systems Manager 參數類型 CloudFormation 不支援下列 Systems Manager 參數類型： + Systems Manager 參數類型清單 — 例如：`List>` 此外，CloudFormation 不支援將範本參數定義為 `SecureString` Systems Manager 參數類型。不過，您可以將安全字串指定為某些資源的參數*值*。如需詳細資訊，請參閱[使用動態參考取得存放在其他服務中的值](dynamic-references.md)。