本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 透過 Amazon ECS 環境變數傳遞 Secrets Manager 秘密
在將秘密作為環境變數插入時，可指定秘密的完整內容、秘密內的特定 JSON 金鑰。這可協助您控制向容器公開的敏感資料。如需有關秘密版本控制的詳細資訊，請參閱 *AWS Secrets Manager User Guide* 中的 [What's in a Secrets Manager secret?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/whats-in-a-secret.html#term_version) 章節。
使用環境變數將 Secrets Manager 秘密插入容器時應考量下列事項。
+ 敏感資料會在初次啟動容器時，嵌入您的容器。如果後續更新或輪換秘密，則容器不會自動收到更新的值。您必須啟動新的任務，或如果任務是服務的一部分，您可以更新服務，並使用 **Force new deployment (強制新的部署)** 選項強制服務來啟動新的任務。
+ 容器上執行的應用程式、容器日誌及偵錯工具皆能存取環境變數。
+ 對於 上的 Amazon ECS 任務 AWS Fargate，請考慮下列事項：
+ 若要將秘密的完整內容作為環境變數或在日誌組態中插入，您必須使用平台版本 `1.3.0` 或更新版本。如需相關資訊，請參閱[適用於 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
+ 若要將特定 JSON 金鑰或秘密版本作為環境變數或在日誌組態中插入，您必須使用平台版本 `1.4.0` 或更新版本 (Linux)，或者 `1.0.0` (Windows)。如需相關資訊，請參閱[適用於 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
+ 對於 EC2 上的 Amazon ECS 任務，應考慮下列事項：
+ 若要使用秘密的特定 JSON 索引鍵或版本插入秘密，您的容器執行個體必須有 `1.37.0` 版或更新版本的容器代理程式。不過，我們建議您使用最新版的容器代理。如需檢查代理程式版本及更新至最新版本的資訊，請參閱「[更新 Amazon ECS 容器代理程式](ecs-agent-update.md)」。
若要插入秘密的完整內容做為環境變數，或在日誌組態中插入秘密，則容器執行個體必須有 `1.22.0` 版或更新版本的容器代理程式。
+ 使用介面 VPC 端點來增強安全控制能力，並透過私有子網路連線至 Secrets Manager。您必須建立 Secrets Manager 的介面 VPC 端點。如需有關 VPC 端點的資訊，請參閱《AWS Secrets Manager 使用者指南》**中的[建立VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)。如需有關使用 Secrets Manager 與 Amazon VPC 的詳細資訊，請參閱 [How to connect to Secrets Manager service within a Amazon VPC](https://aws.amazon.com/blogs//security/how-to-connect-to-aws-secrets-manager-service-within-a-virtual-private-cloud/)。
+ 對於設定為使用 `awslogs` 日誌記錄驅動程式的 Windows 任務，您也必須在容器執行個體上設定 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 環境變數。使用下列語法：
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
```
+ 任務定義必須使用具備 Secrets Manager 額外許可的任務執行角色。如需詳細資訊，請參閱[Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md)。
## 建立 AWS Secrets Manager 秘密
您可以使用 Secrets Manager 主控台為您的敏感資料建立秘密。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
## 將環境變數新增至容器定義
您可以在容器定義中指定下列項目：
+ 包含要在容器中設定之環境變數名稱的 `secrets` 物件
+ Secrets Manager 秘密的 Amazon Resource Name (ARN)
+ 包含要提供給容器之敏感資料的其他參數
下列範例示範了必須為 Secrets Manager 秘密指定的完整語法。
```
arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{secret-name}}:{{json-key}}:{{version-stage}}:{{version-id}}
```
以下部分說明其他參數。這些參數雖然是選用，但如果您不使用，則必須包含冒號 `:` 來使用預設值。以下提供範例深入說明。
`json-key`
使用您要設為環境變數值的值，來指定金鑰/值對中的金鑰名稱。僅支援 JSON 格式的值。如果您沒有指定 JSON 金鑰，則會使用秘密的完整內容。
`version-stage`
指定您要使用之秘密版本的預備標籤。如果指定了版本預備標籤，就無法指定版本 ID。如果未指定版本階段，則預設會擷取具有 `AWSCURRENT` 階段標籤的秘密。
預備標籤會用來在不同版本的秘密更新或輪換時加以追蹤。每個版本的秘密都有一或多個預備標籤和 ID。
`version-id`
針對您要使用的秘密版本，指定其唯一識別符。如果指定了版本 ID，就無法指定版本預備標籤。如果未指定版本 ID，則預設會擷取具有 `AWSCURRENT` 階段標籤的秘密。
版本 ID 會用來在不同版本的秘密更新或輪換時加以追蹤。每個版本的秘密都有 ID。如需詳細資訊，請參閱 *《AWS Secrets Manager 使用者指南》*中的 [AWS Secrets Manager的重要術語和概念](https://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_secret)。
### 容器定義範例
下列範例示範您可以在容器定義中參考 Secrets Manager 秘密的方法。
**Example 參考完整秘密**
以下是任務定義的程式碼片段，顯示參考 Secrets Manager 秘密全文時的格式。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "{{environment_variable_name}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{secret_name-AbCdEf}}"
}]
}]
}
```
若要從容器內存取此秘密的值，您需要呼叫 `$environment_variable_name`。
**Example 引用完整秘密**
以下是任務定義的程式碼片段，顯示引用多個 Secrets Manager 秘密全文時的格式。
```
{
"containerDefinitions": [{
"secrets": [
{
"name": "{{environment_variable_name1}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{secret_name-AbCdEf}}"
},
{
"name": "{{environment_variable_name2}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{secret_name-abcdef}}"
},
{
"name": "{{environment_variable_name3}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{secret_name-ABCDEF}}"
}
]
}]
}
```
若要從容器內存取此秘密的值，您需要呼叫 `$environment_variable_name1`、`$environment_variable_name2`、`$environment_variable_name3`。
**Example 參考秘密中的特定金鑰**
以下示範 [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) 命令的範例輸出，會顯示秘密的內容，以及與其相關的版本預備標籤和版本 ID。
```
{
"ARN": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}",
"Name": "{{appauthexample}}",
"VersionId": "{{871d9eca-18aa-46a9-8785-981ddEXAMPLE}}",
"SecretString": "{\"{{username1}}\":\"{{password1}}\",\"{{username2}}\":\"{{password2}}\",\"{{username3}}\":\"{{password3}}\"}",
"VersionStages": [
"{{AWSCURRENT}}"
],
"CreatedDate": 1581968848.921
}
```
在 ARN 結尾指定金鑰名稱，來在容器定義中參考上一個輸出的特定金鑰。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "{{environment_variable_name}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}:{{username1}}::"
}]
}]
}
```
**Example 參考特定秘密版本**
以下示範 [describe-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/describe-secret.html) 命令的範例輸出，會顯示秘密的未加密內容，以及所有版本秘密的中繼資料。
```
{
"ARN": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}",
"Name": "{{appauthexample}}",
"Description": "Example of a secret containing application authorization data.",
"RotationEnabled": false,
"LastChangedDate": 1581968848.926,
"LastAccessedDate": 1581897600.0,
"Tags": [],
"VersionIdsToStages": {
"{{871d9eca-18aa-46a9-8785-981ddEXAMPLE}}": [
"{{AWSCURRENT}}"
],
"{{9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE}}": [
"{{AWSPREVIOUS}}"
]
}
}
```
在 ARN 結尾指定金鑰名稱，來在容器定義中參考上一個輸出的特定版本預備標籤。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "{{environment_variable_name}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}::{{AWSPREVIOUS}}:"
}]
}]
}
```
在 ARN 結尾指定金鑰名稱，來在容器定義中參考上一個輸出的特定版本 ID。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "{{environment_variable_name}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}:::{{9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE}}"
}]
}]
}
```
**Example 參考秘密的特定金鑰和版本預備標籤**
以下說明如何參考秘密中的特定金鑰和特定版本預備標籤。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "{{environment_variable_name}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}:{{username1}}:{{AWSPREVIOUS}}:"
}]
}]
}
```
若要指定特定的金鑰和版本 ID，請使用下列語法。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "{{environment_variable_name}}",
"valueFrom": "arn:aws:secretsmanager:{{region}}:{{aws_account_id}}:secret:{{appauthexample-AbCdEf}}:{{username1}}::{{9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE}}"
}]
}]
}
```
如需有關如何使用環境變數中指定的秘密建立任務定義的資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。