本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 從 Secrets Manager 中取得秘密或秘密值
<a name="dynamic-references-secretsmanager"></a>

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` 動態參考。

## 最佳實務
<a name="dynamic-references-secretsmanager-best-practices"></a>

在 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` 參數，例如測試或復原情況。

## 考量事項
<a name="dynamic-references-secretsmanager-considerations"></a>

使用 `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 都不應存留任何已解析的秘密值。但是，秘密值在服務的資源中使用時，秘密值就可能出現在此服務中。檢閱您的使用情況，以避免洩露秘密資料。

## 許可
<a name="dynamic-references-secretsmanager-permissions"></a>

若要指定存放在 Secrets Manager 中的秘密，您必須擁有許可才能呼叫 [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html) 以取得秘密。

## 參考模式
<a name="dynamic-references-secretsmanager-pattern"></a>

若要在 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` 版本。  
此區段可能不可包含冒號字元 (`:`)。

## 範例
<a name="dynamic-references-secretsmanager-examples"></a>

**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)

### 從秘密中擷取使用者名稱和密碼值
<a name="dynamic-references-secretsmanager-examples-user-name-and-password"></a>

以下 [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
<a name="dynamic-references-secretsmanager-examples-user-name-and-password.json"></a>

```
{
    "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
<a name="dynamic-references-secretsmanager-examples-user-name-and-password.yaml"></a>

```
  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
<a name="dynamic-references-secretsmanager-examples-entire-secretstring"></a>

下列動態參考會擷取 `MySecret` 的 `SecretString`。

```
{{resolve:secretsmanager:MySecret}}
```

或使用：

```
{{resolve:secretsmanager:MySecret::::}}
```

### 從特定版本的秘密中擷取值
<a name="dynamic-references-secretsmanager-examples-specific-version"></a>

下列動態參考會擷取 `MySecret` 的 `AWSPREVIOUS` 版本的 `password` 值。

```
{{resolve:secretsmanager:MySecret:SecretString:password:AWSPREVIOUS}}
```

### 從另一個 擷取秘密 AWS 帳戶
<a name="dynamic-references-secretsmanager-examples-secrets-from-another-account"></a>

下列動態參考會擷取另一個 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}}
```