本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用動態參考取得存放在其他服務中的值 動態參考可讓您方便地指定在其他服務中存放且管理的外部值，並從基礎設施即程式碼範本中分離敏感資訊。在堆疊和變更集操作期間，CloudFormation 會在必要時擷取指定參考的值。 透過動態參考，您可以： + **使用安全字串** – 對於敏感資料，請一律使用 AWS Systems Manager 參數存放區中的安全字串參數或 中的秘密 AWS Secrets Manager ，以確保靜態加密您的資料。 + **限制存取** – 僅將 Parameter Store 參數或 Secrets Manager 秘密的存取權限制給已授權的主體和角色。 + **輪換憑證** – 定期輪換儲存在 Parameter Store 或 Secrets Manager 中的敏感資料，以維持高層級的安全性。 + **自動化輪換** – 利用 Secrets Manager 的自動輪換功能，在應用程式和環境中定期更新和分發敏感資料。 ## 一般考量事項 以下是在 CloudFormation 範本中指定動態參考之前要考慮的一般考量事項： + 不要在作為資源主識別碼一部分的資源屬性中包含動態引用或任何敏感資料。CloudFormation 可能會在主要資源識別符中使用實際的純文字值，這可能是安全風險。此資源 ID 可能會出現在任何衍生輸出或目的地中。 若要確定哪些資源屬性組成資源類型的主要識別碼，請參閱 [AWS 資源和屬性類型參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-template-resource-type-ref.html)中該資源的資源參考文件。在 **Return values** (傳回值) 區段中，`Ref` 函數傳回值表示組成資源類型主要識別碼的資源屬性。 + 您在一個堆疊範本中最多可以包含 60 個動態參考。 + 如果使用轉換 (例如 `AWS::Include` 或 `AWS::Serverless`)，CloudFormation 不會在套用轉換之前解析動態參考。反之，它會將動態參考的常值字串傳遞至轉換，並在您使用範本執行變更集時解析參考。 + 動態參考無法用於自訂資源中的安全值 (例如儲存在 Parameter Store 或 Secrets Manager 中的值)。 + `AWS::CloudFormation::Init` 中繼資料和 Amazon EC2 `UserData` 屬性也不支援動態參考。 + 請勿建立以反斜線 (\$1) 結尾的動態參考。CloudFormation 無法解析這些參考，這會導致堆疊操作失敗。 下列主題提供使用動態參考的資訊和其他考量事項。 **Topics** + [一般考量事項](#dynamic-references-considerations) + [從 Systems Manager Parameter Store 取得純文字值](dynamic-references-ssm.md) + [從 Systems Manager Parameter Store 中取得安全字串值](dynamic-references-ssm-secure-strings.md) + [從 Secrets Manager 中取得秘密或秘密值](dynamic-references-secretsmanager.md) # 從 Systems Manager Parameter Store 取得純文字值 建立 CloudFormation 範本時，建議您使用儲存在參數存放區中的純文字值。參數存放區是 的功能 AWS Systems Manager。如需 Parameter Store 的簡介，請參閱《AWS Systems Manager 使用者指南》中的 [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。** 若要在範本中使用 Parameter Store 的純文字值，請使用 `ssm` 動態參考。此參考可讓您存取 Parameter Store 中 `String` 或 `StringList` 參數類型的值。 若要驗證將在堆疊操作中使用的 `ssm` 動態參考版本，請為堆疊操作建立變更集。然後，在**範本**索引標籤中檢閱已處理的範本。如需詳細資訊，請參閱[建立 CloudFormation 堆疊的變更集](using-cfn-updating-stacks-changesets-create.md)。 使用 `ssm` 動態參考時，需要謹記幾個重要事項： + CloudFormation 不支援動態參考的偏離偵測。對於尚未指定參數版本的 `ssm` 動態參考，如果更新 Systems Manager 中的參數版本，建議也可以對包含 `ssm` 動態參考的任何堆疊執行堆疊更新操作，以便擷取最新的參數版本。 + 若要在 CloudFormation 範本的 `Parameters` 區段中使用 `ssm` 動態參考，必須包含版本編號。CloudFormation 不允許您在本節中參考沒有版本號碼的參數存放區值。或者，可以在範本中將參數定義為 Systems Manager 參數類型。執行此操作時，可以將 Systems Manager 參數金鑰指定為參數的預設值。然後，CloudFormation 將從 Parameter Store 中擷取參數值的最新版本，而無需指定版本編號。這可讓您的範本更簡單且更容易維護。如需詳細資訊，請參閱[使用 CloudFormation 提供的參數類型，在執行時期指定現有資源](cloudformation-supplied-parameter-types.md)。 + 對於自訂資源，CloudFormation 在將請求傳送到自訂資源之前會解析 `ssm` 動態參考。 + CloudFormation 不支援使用動態參考來參考從另一個 AWS 帳戶共用的參數。 + CloudFormation 在動態參考中不支援使用 Systems Manager 參數標籤。 ## 許可 若要指定存放在 Systems Manager 參數存放區的參數，您必須擁有許可才能呼叫 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) 以取得指定的參數。若要了解如何建立可提供特定 Systems Manager 參數存取權的 IAM 政策，請參閱**《AWS Systems Manager 使用者指南》中的[使用 IAM 政策限制對 Systems Manager 參數的存取](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-access.html)。 ## 參考模式 若要在 CloudFormation 範本中參考存放在 Systems Manager Parameter Store 中的純文字值，請使用下列 `ssm` 參考模式。 ``` {{resolve:ssm:parameter-name:version}} ``` 針對 parameter-name 和 version，您的參考必須遵守下列規則表達式模式： ``` {{resolve:ssm:[a-zA-Z0-9_.\-/]+(:\d+)?}} ``` `parameter-name` 參數存放區中的參數名稱。函數名稱區分大小寫。 必要. `version` 整數，指定要使用的參數版本。如果您沒有指定確切的版本，CloudFormation 會在您建立或更新堆疊時使用最新版本的參數。如需詳細資訊，請參閱《AWS Systems Manager 使用者指南》中的[使用參數版本](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-versions.html)。** 選用。 ## 範例 **Topics** + [公有 AMI ID 參數](#dynamic-references-ssm-public-ami-example) + [自訂 AMI ID 參數](#dynamic-references-ssm-custom-ami-example) ### 公有 AMI ID 參數 下列範例會建立參考公有 AMI 參數的 EC2 執行個體。動態參考會從公有參數中擷取最新的 Amazon Linux 2023 AMI ID。如需公有參數的詳細資訊，請參閱**《AWS Systems Manager 使用者指南》中的[探索參數存放區中的公有參數](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-finding-public-parameters.html)。 #### JSON ``` { "Resources": { "MyInstance": { "Type": "AWS::EC2::Instance", "Properties": { "ImageId": "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}", "InstanceType": "t2.micro" } } } } ``` #### YAML ``` Resources: MyInstance: Type: AWS::EC2::Instance Properties: ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}' InstanceType: t2.micro ``` ### 自訂 AMI ID 參數 下列範例會建立 EC2 啟動範本，它可參考儲存在 Parameter Store 中的自訂 AMI ID。動態參考會在執行個體從啟動範本啟動時，從 `golden-ami` 參數的 *`2`* 版本中擷取 AMI ID。 #### JSON ``` { "Resources": { "MyLaunchTemplate": { "Type": "AWS::EC2::LaunchTemplate", "Properties": { "LaunchTemplateName": { "Fn::Sub": "${AWS::StackName}-launch-template" }, "LaunchTemplateData": { "ImageId": "{{resolve:ssm:golden-ami:2}}", "InstanceType": "t2.micro" } } } } } ``` #### YAML ``` Resources: MyLaunchTemplate: Type: AWS::EC2::LaunchTemplate Properties: LaunchTemplateName: !Sub ${AWS::StackName}-launch-template LaunchTemplateData: ImageId: '{{resolve:ssm:golden-ami:2}}' InstanceType: t2.micro ``` # 從 Systems Manager Parameter Store 中取得安全字串值 在 CloudFormation 中，您可以將敏感資料儲存為 AWS Systems Manager 參數存放區中的「安全字串」，以使用密碼或授權金鑰等敏感資料，而無需直接在範本中公開。如需 Parameter Store 的簡介，請參閱《AWS Systems Manager 使用者指南》中的 [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。** 若要在範本中使用 Parameter Store 安全字串，請使用 `ssm-secure` 動態參考。CloudFormation 永遠不會存放實際的安全字串值。相反，它僅存放文字動態參考，其中包含安全字串的純文字參數名稱。 在堆疊建立或更新期間，CloudFormation 會視需要存取安全字串值，而不會公開實際值。安全字串僅用於有支援 `ssm-secure` 動態參考模式的資源屬性。如需詳細資訊，請參閱[對安全字串支援動態參數模式的資源](#template-parameters-dynamic-patterns-resources)。 CloudFormation 不會在任何 API 呼叫中傳回安全字串的實際參數值。它只會傳回常值動態參考。使用變更集來比較變更時，CloudFormation 只會比較文字動態參考字串。它不會解析和比較實際安全字串值。 使用 `ssm-secure` 動態參考時，需要謹記幾個重要事項： + CloudFormation 無法從其他 AWS 帳戶中存取 Parameter Store 值。 + CloudFormation 在動態參考中不支援使用 Systems Manager 參數標籤或公有參數。 + 在 `cn-north-1` 和 `cn-northwest-1` 區域中，Systems Manager 不支援安全字串。 + 自訂資源中目前不支援安全值的動態參考，例如 `ssm-secure`。 + 如果 CloudFormation 需要復原堆疊更新，且之前指定的安全字串參數版本不再可用，則復原操作將失敗。在這種情況下，您有兩個選項： + 使用 `CONTINUE_UPDATE_ROLLBACK` 略過資源。 + 在 Systems Manager 參數存放區中重新建立安全字串參數，並更新它，直到參數版本達到範本中使用的版本。然後，在不跳過資源的情況下使用 `CONTINUE_UPDATE_ROLLBACK`。 ## 對安全字串支援動態參數模式的資源 支援 `ssm-secure` 動態參考模式的資源包括： | 資源 | 屬性類型 | Properties | | --- | --- | --- | | [AWS::DirectoryService::MicrosoftAD](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-directoryservice-microsoftad.html) | | `Password` | | [AWS::DirectoryService::SimpleAD](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-directoryservice-simplead.html) | | `Password` | | [AWS::ElastiCache::ReplicationGroup](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-elasticache-replicationgroup.html) | | `AuthToken` | | [AWS::IAM::User](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-user.html) | [LoginProfile](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-iam-user-loginprofile.html) | `Password` | | [AWS::KinesisFirehose::DeliveryStream](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-kinesisfirehose-deliverystream.html) | [RedshiftDestinationConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-kinesisfirehose-deliverystream-redshiftdestinationconfiguration.html) | `Password` | | [AWS::OpsWorks::App](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-opsworks-app.html) | [來源](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opsworks-app-source.html) | `Password` | | [AWS::OpsWorks::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-opsworks-stack.html) | [CustomCookbooksSource](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opsworks-stack-source.html) | `Password` | | [AWS::OpsWorks::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-opsworks-stack.html) | [RdsDbInstances](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opsworks-stack-rdsdbinstance.html) | `DbPassword` | | [AWS::RDS::DBCluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbcluster.html) | | `MasterUserPassword` | | [AWS::RDS::DBInstance](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html) | | `MasterUserPassword` | | [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-redshift-cluster.html) | | `MasterUserPassword` | ## 參考模式 若要在 CloudFormation 範本中參考 Systems Manager Parameter Store 的安全字串值，請使用下列 `ssm-secure` 參考模式。 ``` {{resolve:ssm-secure:parameter-name:version}} ``` 針對 parameter-name 和 version，您的參考必須遵守下列規則表達式模式： ``` {{resolve:ssm-secure:[a-zA-Z0-9_.\-/]+(:\d+)?}} ``` `parameter-name` 參數存放區中的參數名稱。函數名稱區分大小寫。 必要. `version` 整數，指定要使用的參數版本。如果您沒有指定確切的版本，CloudFormation 會在您建立或更新堆疊時使用最新版本的參數。如需詳細資訊，請參閱《AWS Systems Manager 使用者指南》中的[使用參數版本](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-versions.html)。** 選用。 ## 範例 以下範例使用 `ssm-secure` 動態參考，將 IAM 使用者的密碼設為存放在 Parameter Store 的安全字串。依規定，CloudFormation 會使用 `IAMUserPassword` 參數的 *`10`* 版本，用於堆疊和變更集操作。 ### JSON ``` "MyIAMUser": { "Type": "AWS::IAM::User", "Properties": { "UserName": "MyUserName", "LoginProfile": { "Password": "{{resolve:ssm-secure:IAMUserPassword:10}}" } } } ``` ### YAML ``` MyIAMUser: Type: AWS::IAM::User Properties: UserName: 'MyUserName' LoginProfile: Password: '{{resolve:ssm-secure:IAMUserPassword:10}}' ``` # 從 Secrets Manager 中取得秘密或秘密值 Secrets Manager 是一項服務，可讓您安全地存放和管理秘密，例如資料庫憑證、密碼和第三方 API 金鑰。您可以使用 Secrets Manage 集中存放或控制對這些秘密的存取，因此您可以將程式碼中的硬式編碼憑證 (包括密碼)，取代為對 Secrets Manager 的 API 呼叫，以程式設計方式擷取秘密。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[什麼是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。 若要在 CloudFormation 範本內使用存放於 Secrets Manager 中的全部秘密或秘密值，您可使用 `secretsmanager` 動態參考。 ## 最佳實務 在 CloudFormation 範本中使用 Secrets Manager 動態參考時，請遵循下列最佳實務： + **使用 CloudFormation 範本的無版本參考** – 將憑證儲存在 Secrets Manager 中，並使用動態參考，而不指定 `version-stage` 或 `version-id` 參數，以支援適當的秘密輪換工作流程。 + **利用自動輪換** – 搭配使用 Secrets Manager 的自動輪換功能與無版本動態參考，進行憑證管理。這可確保定期更新憑證，而不需要變更範本。如需詳細資訊，請參閱[輪換 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。 + **謹慎使用版本控制的參考** – 僅針對特定案例指定明確的 `version-stage` 或 `version-id` 參數，例如測試或復原情況。 ## 考量事項 使用 `secretsmanager` 動態參考時，請注意以下重要考量： + CloudFormation 不會追蹤先前部署中使用的秘密版本。在實作動態參考之前，請仔細規劃您的秘密管理策略。盡可能使用無版本參考，以利用自動秘密輪換。在變更動態參考組態時 (例如從未版本化動態參考轉換為版本化動態參考時) 監控和驗證資源更新，反之亦然。 + 僅更新 Secrets Manager 中的秘密值不會自動導致 CloudFormation 擷取新值。CloudFormation 只會在修改包含動態參考之資源的資源建立或更新期間擷取秘密值。 例如，假設範本包含 [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html) 資源，其中 `MasterPassword` 屬性設定為 Secrets Manager 動態參考。從此範本建立堆疊後，可以在 Secrets Manager 中更新秘密的值。不過，`MasterPassword` 屬性會保留舊密碼值。 若要套用新的秘密值，需要修改 CloudFormation 範本中的 `AWS::RDS::DBInstance` 資源，並執行堆疊更新。 為了避免未來出現此手動程序，請考慮使用 Secrets Manager 自動輪換秘密。 + 自訂資源中目前不支援安全值的動態參考，例如 `secretsmanager`。 + 所有資源屬性中可以使用 `secretsmanager` 動態參考。使用 `secretsmanager` 動態參考表明 Secrets Manager 和 CloudFormation Logs 都不應存留任何已解析的秘密值。但是，秘密值在服務的資源中使用時，秘密值就可能出現在此服務中。檢閱您的使用情況，以避免洩露秘密資料。 ## 許可 若要指定存放在 Secrets Manager 中的秘密，您必須擁有許可才能呼叫 [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html) 以取得秘密。 ## 參考模式 若要在 CloudFormation 範本中參考 Secrets Manager 秘密，請使用下列 `secretsmanager` 參考模式。 ``` {{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}} ``` `secret-id` 秘密的名稱或 ARN。 若要存取 中的秘密 AWS 帳戶，您只需指定秘密名稱。若要存取不同 中的秘密 AWS 帳戶，請指定秘密的完整 ARN。 必要. `secret-string` 唯一支援的值為 `SecretString`。預設值為 `SecretString`。 `json-key` 您要擷取值的鍵值組的索引鍵名稱。如果您不指定 `json-key`，CloudFormation 會擷取整個秘密文字。 此區段可能不可包含冒號字元 (`:`)。 `version-stage` 要使用的秘密版本之預備標籤。Secrets Manager 在輪換程序期間使用預備標籤來追蹤不同版本。如果您使用 `version-stage`，請不要指定 `version-id`。如果您未指定 `version-stage` 或 `version-id`，則預設為 `AWSCURRENT` 版本。 此區段可能不可包含冒號字元 (`:`)。 `version-id` 您要使用的秘密版本的唯一識別碼。如果您指定 `version-id`，則請不要指定 `version-stage`。如果您未指定 `version-stage` 或 `version-id`，則預設為 `AWSCURRENT` 版本。 此區段可能不可包含冒號字元 (`:`)。 ## 範例 **Topics** + [從秘密中擷取使用者名稱和密碼值](#dynamic-references-secretsmanager-examples-user-name-and-password) + [擷取整個 SecretString](#dynamic-references-secretsmanager-examples-entire-secretstring) + [從特定版本的秘密中擷取值](#dynamic-references-secretsmanager-examples-specific-version) + [從另一個 擷取秘密 AWS 帳戶](#dynamic-references-secretsmanager-examples-secrets-from-another-account) ### 從秘密中擷取使用者名稱和密碼值 以下 [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html) 範例會擷取存放在 `MySecret` 秘密中的使用者名稱和密碼值。此範例顯示無版本動態參考的建議模式，它會自動使用 `AWSCURRENT` 版本並支援 Secrets Manager 輪換工作流程，而不需要變更範本。 #### JSON ``` { "MyRDSInstance": { "Type": "AWS::RDS::DBInstance", "Properties": { "DBName": "MyRDSInstance", "AllocatedStorage": "20", "DBInstanceClass": "db.t2.micro", "Engine": "mysql", "MasterUsername": "{{resolve:secretsmanager:MySecret:SecretString:username}}", "MasterUserPassword": "{{resolve:secretsmanager:MySecret:SecretString:password}}" } } } ``` #### YAML ``` MyRDSInstance: Type: AWS::RDS::DBInstance Properties: DBName: MyRDSInstance AllocatedStorage: '20' DBInstanceClass: db.t2.micro Engine: mysql MasterUsername: '{{resolve:secretsmanager:MySecret:SecretString:username}}' MasterUserPassword: '{{resolve:secretsmanager:MySecret:SecretString:password}}' ``` ### 擷取整個 SecretString 下列動態參考會擷取 `MySecret` 的 `SecretString`。 ``` {{resolve:secretsmanager:MySecret}} ``` 或使用： ``` {{resolve:secretsmanager:MySecret::::}} ``` ### 從特定版本的秘密中擷取值 下列動態參考會擷取 `MySecret` 的 `AWSPREVIOUS` 版本的 `password` 值。 ``` {{resolve:secretsmanager:MySecret:SecretString:password:AWSPREVIOUS}} ``` ### 從另一個 擷取秘密 AWS 帳戶 下列動態參考會擷取另一個 AWS 帳戶中 `MySecret` 的 `SecretString`。您必須指定完整的秘密 ARN，才能存取另一個秘密 AWS 帳戶。 ``` {{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret}} ``` 下列動態參考會擷取另一個 AWS 帳戶中 `MySecret` 的 `password` 值。您必須指定完整的秘密 ARN，才能存取另一個秘密 AWS 帳戶。 ``` {{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret:SecretString:password}} ```