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

# 將敏感資料傳遞至 Amazon ECS 容器
<a name="specifying-sensitive-data"></a>

您可以安全地將敏感資料 (例如資料庫憑證) 傳遞至容器。

秘密 (例如 API 金鑰和資料庫憑證) 經常被應用程式用來存取其他系統。其通常由使用者名稱和密碼、憑證或 API 金鑰組成。對這些秘密的存取應限制在使用 IAM 的特定 IAM 主體，並在執行期插入容器。

秘密可以從 AWS Secrets Manager 和 Amazon EC2 Systems Manager 參數存放區無縫注入容器。這些秘密可以在您的任務中引用為以下任何內容。

1. 被引用為使用 `secrets` 容器定義參數的環境變數。

1. 如果您的日誌平台需要驗證，則被引用為 `secretOptions`。如需詳細資訊，請參閱[紀錄組態選項](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html#API_LogConfiguration_Contents)。

1. 如果從中提取容器的登錄檔需要驗證，則使用 `repositoryCredentials` 容器定義參數的映像會將其參照為提取的秘密。從 Amazon ECR Public Gallery 提取映像時使用此方法。如需詳細資訊，請參閱[任務的私有登錄檔身分驗證](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)。

建議您在設定秘密管理時執行下列動作。

## 使用 AWS Secrets Manager 或 AWS Systems Manager 參數存放區來存放秘密資料
<a name="security-secrets-management-recommendations-storing-secret-materials"></a>

您應該將 API 金鑰、資料庫憑證與其他秘密資料安全儲存在 Secrets Manager 中，或將其作為加密參數安全儲存在 Systems Manager Parameter Store 中。這些服務類似，因為它們都是 AWS KMS 用於加密敏感資料的受管金鑰值存放區。不過，Secrets Manager 還具備自動輪換秘密、產生隨機秘密及跨帳戶共用秘密的能力。若要使用這些功能，可選擇 Secrets Manager。反之，則可在 Systems Manager Parameter Store 中使用加密參數。

**重要**  
如果您的秘密發生變更，您必須強制執行新部署或啟動新任務，才能擷取最新的秘密值。如需詳細資訊，請參閱下列主題：  
任務 – 先停止任務，再重新啟動。如需詳細資訊，請參閱[停止 Amazon ECS 任務](standalone-task-stop.md)及[將應用程式作為 Amazon ECS 任務執行](standalone-task-create.md)。
服務 – 更新服務並使用「強制執行新部署」選項。如需詳細資訊，請參閱[更新 Amazon ECS 服務](update-service-console-v2.md)。

## 從加密的 Amazon S3 儲存貯體擷取資料
<a name="security-secrets-management-recommendations-encrypted-s3-buckets"></a>

您應該將秘密儲存於加密的 Amazon S3 儲存貯體中，並使用任務角色來限制對這些秘密的存取。此舉可防止環境變數的值在日誌中意外洩漏，或在執行 `docker inspect` 時遭到暴露。執行此動作時，必須寫入應用程式，才能讀取 Amazon S3 儲存貯體中的秘密。如需說明，請參閱[對 Amazon S3 儲存貯體設定預設伺服器端加密行為](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html)。

## 使用附屬容器將秘密掛載至磁碟區
<a name="security-secrets-management-recommendations-mount-secret-volumes"></a>

由於環境變數的資料外洩風險較高，因此您應該執行附屬容器，從 讀取秘密 AWS Secrets Manager 並將其寫入共用磁碟區。透過使用 [Amazon ECS 容器排序](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html)，此容器可以在應用程式容器之前執行和結束。執行此操作時，應用程式容器隨後會掛載寫入秘密的磁碟區。就像 Amazon S3 儲存貯體方法一樣，必須寫入您的應用程式才能從共用磁碟區讀取秘密。由於磁碟區的範圍限定在任務，因此會在任務停止後自動刪除磁碟區。如需範例，請參閱 [task-def.json](https://github.com/aws-samples/aws-secret-sidecar-injector/blob/master/ecs-task-def/task-def.json) 專案。

在 Amazon EC2 上，寫入秘密的磁碟區可以使用 AWS KMS 客戶受管金鑰加密。在 上 AWS Fargate，磁碟區儲存會使用服務受管金鑰自動加密。

# 將個別環境變數傳遞至 Amazon ECS 容器
<a name="taskdef-envfiles"></a>

**重要**  
建議您將敏感資料儲存在 AWS Secrets Manager 秘密或 AWS Systems Manager 參數存放區參數中。如需詳細資訊，請參閱[將敏感資料傳遞至 Amazon ECS 容器](specifying-sensitive-data.md)。  
任務定義中指定的環境變數可供所有使用者和角色讀取，系統允許這些使用者和角色對任務定義執行 `DescribeTaskDefinition` 動作。

您可以將環境變數透過下列方式傳遞至容器：
+ 個別方式：使用 `environment` 容器定義參數。這會映射到 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) 的 `--env` 選項。
+ 大批方式：使用 `environmentFiles` 容器定義參數列出內含環境變數的一個或多個檔案。檔案必須託管在 Amazon S3 中。這會映射到 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) 的 `--env-file` 選項。

以下任務定義片段示範如何指定個別環境變數。

```
{
    "family": "",
    "containerDefinitions": [
        {
            "name": "",
            "image": "",
            ...
            "environment": [
                {
                    "name": "variable",
                    "value": "value"
                }
            ],
            ...
        }
    ],
    ...
}
```

# 將環境變數傳遞至 Amazon ECS 容器
<a name="use-environment-file"></a>

**重要**  
建議您將敏感資料儲存在 AWS Secrets Manager 秘密或 AWS Systems Manager 參數存放區參數中。如需詳細資訊，請參閱[將敏感資料傳遞至 Amazon ECS 容器](specifying-sensitive-data.md)。  
環境變數檔案是 Simple Storage Service (Amazon S3) 中的物件，所有 Amazon S3 安全考量事項均適用。  
Windows 容器與 Fargate 上的 Windows 容器不支援使用 `environmentFiles` 參數。

您可以建立環境變數檔案，並將其儲存於 Amazon S3 中，將環境變數傳遞至您的容器。

透過在檔案中指定環境變數，您可以批次導入環境變數。在容器定義中指定 `environmentFiles` 物件，其中具有內含環境變數檔案的 Amazon S3 儲存貯體清單。

Amazon ECS 不會對環境變數強制執行大小限制，但是大型環境變數檔案可能會填滿磁碟空間。使用環境變數檔案的每個任務都會導致檔案複本下載到磁碟。Amazon ECS 會在任務清理過程中移除該檔案。

如需有關支援之環境變數的資訊，請參閱[進階容器定義參數 - 環境](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_environment)。

在容器定義中指定環境變數檔案時，請考量下列事項。
+ 對於 Amazon EC2 上的 Amazon ECS 任務，您的容器執行個體需要版本 `1.39.0` 或更新的容器代理程式，才能使用此功能。如需如何檢查代理程式版本及更新至最新版本的資訊，請參閱「[更新 Amazon ECS 容器代理程式](ecs-agent-update.md)」。
+ 對於 AWS Fargate 上的 Amazon ECS 任務，您的任務必須使用平台版本 `1.4.0` 或更新版本 (Linux) 才能使用此功能。如需詳細資訊，請參閱[適用於 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。

  驗證作業系統平台是否支援該變數。如需詳細資訊，請參閱[容器定義](task_definition_parameters.md#container_definitions)及[其他任務定義參數](task_definition_parameters.md#other_task_definition_params)。
+ 檔案必須使用 `.env` 副檔名和 UTF-8 編碼。
+ 此功能需搭配任務執行角色使用，且該角色必須具備額外的 Amazon S3 許可。這可讓容器代理程式從 Amazon S3 中提取環境變數檔案。如需詳細資訊，請參閱[Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md)。
+ 每個任務定義限制 10 個檔案。
+ 環境檔案中的每一行都必須包含 `VARIABLE=VALUE` 格式的環境變數。空格或引號**會**包含為 Amazon ECS 檔案值的一部分。以 `#` 開頭的行會被視為註解，而忽略。如需有關環境變數檔案語法的詳細資訊，請參閱 Docker 文件中的 [Set environment variables (-e, --env, --env-file)](https://docs.docker.com/reference/cli/docker/container/run/#env)。

  下列為適當的語法。

  ```
  #This is a comment and will be ignored
  VARIABLE=VALUE
  ENVIRONMENT=PRODUCTION
  ```
+ 如果有在容器定義中使用 `environment` 參數指定的環境變數，它們的優先順序高於環境檔案中包含的變數。
+ 如果指定內含相同變數的多個環境檔案，則處理順序為先進入者為優先。這表示會使用變數的第一個值，並忽略重複變數的後續值。建議您使用唯一的變數名稱。
+ 如果將環境檔案指定為容器覆寫，則會使用該檔案。此外，在容器定義中指定的任何其他環境檔案都將被忽略。
+ 下列規則適用於 Fargate：
  + 檔案的處理方式與本機 Docker 環境檔案類似。
  + 若容器定義所引用的環境變數值為空白且儲存於 Amazon S3 中，則容器定義將不會出現在容器中。
  + 不支援 Shell 逸出處理。
  + 容器進入點會解譯 `VARIABLE` 值。

## 範例
<a name="environment-file-example"></a>

以下任務定義片段示範如何指定環境變數檔案。

```
{
    "family": "",
    "containerDefinitions": [
        {
            "name": "",
            "image": "",
            ...
            "environmentFiles": [
                {
                    "value": "arn:aws:s3:::amzn-s3-demo-bucket/envfile_object_name.env",
                    "type": "s3"
                }
            ],
            ...
        }
    ],
    ...
}
```

# 在 Amazon ECS 中以程式設計方式傳遞 Secrets Manager 秘密
<a name="secrets-app-secrets-manager"></a>

您可以使用 Secrets Manager 來儲存敏感資料，不必在應用程式中以純文字硬編碼敏感資訊。

我們建議使用這種方法擷取敏感資料，因為使用這種方法後，隨後如果 Secrets Manager 秘密有更新，應用程式會自動擷取最新版本的秘密。

在 Secrets Manager 中建立秘密。建立 Secret Manager 秘密後，更新應用程式程式碼即可擷取秘密。

保護 Secrets Manager 中的敏感資料之前，請先檢閱下列考量事項。
+ 僅支援存放文字資料的秘密，這些秘密是使用 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API 的 `SecretString` 參數建立的。不支援儲存二進位資料的秘密，即透過 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API 的 `SecretBinary` 參數建立的秘密。
+ 使用介面 VPC 端點來增強安全控制。您必須建立 Secrets Manager 的介面 VPC 端點。如需有關 VPC 端點的資訊，請參閱《AWS Secrets Manager 使用者指南》**中的[建立VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)。
+ 任務所使用的 VPC 必須使用 DNS 解析。
+ 任務定義必須使用具備 Secrets Manager 額外許可的任務角色。如需詳細資訊，請參閱[Amazon ECS 任務 IAM 角色](task-iam-roles.md)。

## 建立 Secrets Manager 秘密
<a name="secrets-app-secrets-manager-create-secret"></a>

您可以使用 Secrets Manager 主控台為您的敏感資料建立秘密。如需有關如何建立秘密的詳細資訊，請參閱《AWS Secrets Manager 使用者指南》**中的[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

## 更新應用程式以程式設計方式擷取 Secrets Manager 秘密
<a name="secrets-app-secrets-manager-update-app"></a>

您可以直接從應用程式呼叫 Secrets Manager API 來擷取秘密。如需詳細資訊，請參閱 *AWS Secrets Manager User Guide* 中的 [Retrieve secrets from AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。

若要擷取存放在 中的敏感資料 AWS Secrets Manager，請參閱 SDK [程式碼範例程式碼庫中的使用 AWS SDKs的 AWS Secrets Manager](https://docs.aws.amazon.com/code-library/latest/ug/secrets-manager_code_examples.html)程式碼範例。 *AWS *

# 在 Amazon ECS 中以程式設計方式傳遞 Systems Manager Parameter Store 秘密
<a name="secrets-app-ssm-paramstore"></a>

Systems Manager Parameter Store 提供安全的秘密儲存和管理。您可以將密碼、資料庫字串、EC2 執行個體 ID、AMI ID、授權碼等資料作為參數值儲存，不必在應用程式中硬編碼此類資訊。您存放的值可以是純文字或加密資料。

建議使用這種方法擷取敏感資料，因為使用這種方法後，隨後如果 Systems Manager Parameter Store 參數有更新，應用程式會自動擷取最新版本。

在保護 Systems Manager Parameter Store 中的敏感資料之前，請先檢閱以下考量事項。
+ 僅支援儲存文字資料的秘密。不支援儲存二進位資料的秘密。
+ 使用介面 VPC 端點來增強安全控制。
+ 任務所使用的 VPC 必須使用 DNS 解析。
+ 對於使用 EC2 的任務，您必須使用 Amazon ECS 代理程式組態變數 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true`，才能使用此功能。您可以在建立容器執行個體期間將其新增至 `/etc/ecs/ecs.config` 檔案，也可以將其新增至現有的執行個體，然後重新啟動 ECS 代理程式。如需詳細資訊，請參閱[Amazon ECS 容器代理程式組態](ecs-agent-config.md)。
+ 任務定義必須使用具備 Systems Manager Parameter Store 額外許可的任務角色。如需詳細資訊，請參閱[Amazon ECS 任務 IAM 角色](task-iam-roles.md)。

## 建立參數
<a name="secrets-app-ssm-paramstore-create-secret"></a>

您可以使用 Systems Manager 主控台為您的敏感資料建立 Systems Manager Parameter Store 參數。如需詳細資訊，請參閱《AWS Systems Manager 使用者指南》**中的[建立 Systems Manager 參數 (主控台)](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html) 或[建立 Systems Manager 參數 (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)。

## 更新應用程式，以程式設計方式擷取 Systems Manager Parameter Store 秘密
<a name="secrets-app-ssm-paramstore-update-app"></a>

若要擷取儲存在 Systems Manager 參數存放區參數中的敏感資料，請參閱 SDK [程式碼範例程式碼庫中的使用 AWS SDKs的 Systems Manager](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html) 程式碼範例。 *AWS *

# 透過 Amazon ECS 環境變數傳遞 Secrets Manager 秘密
<a name="secrets-envvar-secrets-manager"></a>

在將秘密作為環境變數插入時，可指定秘密的完整內容、秘密內的特定 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` 環境變數。使用下列語法：

  ```
  <powershell>
  [Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
  Initialize-ECSAgent -Cluster <cluster name> -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
  </powershell>
  ```
+ 任務定義必須使用具備 Secrets Manager 額外許可的任務執行角色。如需詳細資訊，請參閱[Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md)。

## 建立 AWS Secrets Manager 秘密
<a name="secrets-envvar-secrets-manager-create-secret"></a>

您可以使用 Secrets Manager 主控台為您的敏感資料建立秘密。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

## 將環境變數新增至容器定義
<a name="secrets-envvar-secrets-manager-update-container-definition"></a>

您可以在容器定義中指定下列項目：
+ 包含要在容器中設定之環境變數名稱的 `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)。

### 容器定義範例
<a name="secrets-examples"></a>

下列範例示範您可以在容器定義中參考 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)。

# 透過 Amazon ECS 環境變數傳遞 Systems Manager 參數
<a name="secrets-envvar-ssm-paramstore"></a>

Amazon ECS 可讓您將敏感資料儲存在 AWS Systems Manager 參數存放區參數中，然後在容器定義中參考，藉此將敏感資料注入容器。

使用環境變數將 Systems 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 端點來增強安全控制。您必須為 Systems Manager 建立介面 VPC 端點。如需有關 VPC 端點的資訊，請參閱 *AWS Systems Manager User Guide* 中的 [Improve the security of EC2 instances by using VPC endpoints for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-vpc.html)。
+ 任務定義必須使用具備 Systems Manager Parameter Store 額外許可的任務執行角色。如需詳細資訊，請參閱[Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md)。
+ 對於設定為使用 `awslogs` 日誌記錄驅動程式的 Windows 任務，您也必須在容器執行個體上設定 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 環境變數。使用下列語法：

  ```
  <powershell>
  [Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
  Initialize-ECSAgent -Cluster <cluster name> -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
  </powershell>
  ```

## 建立 Systems Manager 參數
<a name="secrets-envvar-ssm-paramstore-create-parameter"></a>

您可以使用 Systems Manager 主控台為您的敏感資料建立 Systems Manager Parameter Store 參數。如需詳細資訊，請參閱《AWS Systems Manager 使用者指南》**中的[建立 Systems Manager 參數 (主控台)](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html) 或[建立 Systems Manager 參數 (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)。

## 將環境變數新增至容器定義
<a name="secrets-ssm-paramstore-update-container-definition"></a>

在任務定義的容器定義內，為 `secrets` 指定要在容器中設定的環境變數名稱，以及 Systems Manager Parameter Store 參數 (含有要提供給容器的敏感資料) 的完整 ARN。如需詳細資訊，請參閱[secrets](task_definition_parameters.md#ContainerDefinition-secrets)。

以下是任務定義的程式碼片段，顯示參考 Systems Manager 參數存放區參數的格式。如果 Systems Manager 參數存放區參數與您要啟動的任務位於相同區域中，則您可以使用參數的完整 ARN 或名稱。如果參數存在於不同區域，則請指定完整 ARN。

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
    }]
  }]
}
```

如需有關如何使用環境變數中指定的秘密建立任務定義的資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。

## 更新應用程式，以程式設計方式擷取 Systems Manager Parameter Store 秘密
<a name="secrets-ssm-paramstore-update-app"></a>

若要擷取儲存在 Systems Manager 參數存放區參數中的敏感資料，請參閱 SDK [程式碼範例程式碼庫中的使用 AWS SDKs的 Systems Manager](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html) 程式碼範例。 *AWS *

# 為 Amazon ECS 記錄組態傳遞秘密
<a name="secrets-logconfig"></a>

您可以使用 `logConfiguration` 中的 `secretOptions` 參數，傳遞用於記錄的敏感資料。

您可以將秘密儲存於 Secrets Manager 或 Systems Manager 中。

## 使用 Secrets Manager
<a name="secrets-logconfig-secrets-manager"></a>

在您的容器定義內，指定 `logConfiguration` 時，您可指定 `secretOptions`，在該參數中，需提供要在容器中設定的日誌驅動程式選項名稱，以及含有要呈現給容器之敏感資料的 Secrets Manager 秘密之完整 ARN。如需有關建立秘密的詳細資訊，請參閱 [Create an AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

以下是任務定義的程式碼片段，顯示參考 Secrets Manager 秘密時的格式。

```
{
  "containerDefinitions": [{
    "logConfiguration": [{
      "logDriver": "splunk",
      "options": {
        "splunk-url": "https://your_splunk_instance:8088"
      },
      "secretOptions": [{
        "name": "splunk-token",
        "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
      }]
    }]
  }]
}
```

## 將環境變數新增至容器定義
<a name="secrets-envvar-ssm-paramstore-update-container-definition"></a>

在您的容器定義內，將 `secrets` 指定為要在容器中設定的環境變數名稱，以及 Systems Manager 參數存放區參數 (含有要呈現給容器的敏感資料) 的完整 ARN。如需詳細資訊，請參閱[secrets](task_definition_parameters.md#ContainerDefinition-secrets)。

以下是任務定義的程式碼片段，顯示參考 Systems Manager 參數存放區參數的格式。如果 Systems Manager 參數存放區參數與您要啟動的任務位於相同區域中，則您可以使用參數的完整 ARN 或名稱。如果參數存在於不同區域，則請指定完整 ARN。

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
    }]
  }]
}
```

如需有關如何使用環境變數中指定的秘密建立任務定義的資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。

## 使用 Systems Manager
<a name="secrets-logconfig-ssm-paramstore"></a>

您可以將敏感資料插入日誌組態。在您的容器定義內，指定 `logConfiguration` 時，您可用要在容器中設定的日誌驅動程式選項名稱指定 `secretOptions`，以及 Systems Manager 參數存放區參數 (含有要呈現給容器的敏感資料) 的完整 ARN。

**重要**  
如果 Systems Manager 參數存放區參數與您要啟動的任務位於相同區域中，則您可以使用參數的完整 ARN 或名稱。如果參數存在於不同區域，則請指定完整 ARN。

以下是任務定義的程式碼片段，顯示參考 Systems Manager 參數存放區參數的格式。

```
{
  "containerDefinitions": [{
    "logConfiguration": [{
      "logDriver": "fluentd",
      "options": {
        "tag": "fluentd demo"
      },
      "secretOptions": [{
        "name": "fluentd-address",
        "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter:/parameter_name"
      }]
    }]
  }]
}
```

# 在 Amazon ECS 中使用 Secrets Manager 秘密指定敏感資料
<a name="specifying-sensitive-data-tutorial"></a>

Amazon ECS 可讓您將敏感資料存放在 AWS Secrets Manager 秘密中，然後在容器定義中參考，藉此將敏感資料注入容器。如需詳細資訊，請參閱[將敏感資料傳遞至 Amazon ECS 容器](specifying-sensitive-data.md)。

了解如何建立 Secrets Manager 秘密、引用 Amazon ECS 任務定義中的秘密，然後查詢容器內顯示秘密內容的環境變數，驗證其是否能運作。

## 先決條件
<a name="specifying-sensitive-data-tutorial-prereqs"></a>

本教學課程假設已完成下列先決條件：
+ 已完成「[設定以使用 Amazon ECS。](get-set-up-for-amazon-ecs.md)」中的步驟。
+ 您的使用者具有必要的 IAM 許可，可建立 Secrets Manager 與 Amazon ECS 資源。

## 步驟 1：建立 Secrets Manager 機密
<a name="specifying-sensitive-data-tutorial-create-secret"></a>

您可以使用 Secrets Manager 主控台為您的敏感資料建立秘密。在本教學課程中，我們將建立基本秘密，以供存放容器中稍後參考的使用者名稱和密碼。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

**要儲存在此秘密中的鍵/值對**是教學課程結尾處容器中的環境變量值。

儲存**秘密 ARN**，以在後續步驟的任務執行 IAM 政策和任務定義中參考。

## 步驟 2：將秘密許可新增至任務執行角色
<a name="specifying-sensitive-data-tutorial-update-iam"></a>

若要讓 Amazon ECS 從 Secrets Manager 秘密擷取敏感資料，您必須擁有任務執行角色的秘密許可。如需詳細資訊，請參閱[Secrets Manager 或 Systems Manager 許可](task_execution_IAM_role.md#task-execution-secrets)。

## 步驟 3：建立任務定義
<a name="specifying-sensitive-data-tutorial-create-taskdef"></a>

您可以使用 Amazon ECS 主控台來建立一個參考 Secrets Manager 秘密的任務定義。

**建立一個指定秘密的任務定義**

使用 IAM 主控台，以所需的許可更新您的任務執行角色。

1. 開啟主控台，網址為 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)。

1. 在導覽窗格中，選擇 **Task Definitions** (任務定義)。

1. 選擇 **Create new task definitio** (建立新任務定義)、**Create new task definition with JSON** (使用 JSON 建立新的任務定義)。

1. 在 JSON 編輯器方塊中輸入以下任務定義 JSON 文字，確保為在步驟 1 建立的 Secrets Manager 秘密以及在步驟 2 中更新的任務執行角色，指定完整的 ARN。選擇**儲存**。

1. 

   ```
   {
       "executionRoleArn": "arn:aws:iam::aws_account_id:role/ecsTaskExecutionRole",
       "containerDefinitions": [
           {
               "entryPoint": [
                   "sh",
                   "-c"
               ],
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ],
               "command": [
                   "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' >  /usr/local/apache2/htdocs/index.html && httpd-foreground\""
               ],
               "cpu": 10,
               "secrets": [
                   {
                       "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:username_value",
                       "name": "username_value"
                   }
               ],
               "memory": 300,
               "image": "public.ecr.aws/docker/library/httpd:2.4",
               "essential": true,
               "name": "ecs-secrets-container"
           }
       ],
       "family": "ecs-secrets-tutorial"
   }
   ```

1. 選擇**建立**。

## 步驟 4：建立叢集
<a name="specifying-sensitive-data-tutorial-create-cluster"></a>

您可以使用 Amazon ECS 主控台建立一個叢集，其中包含要執行任務的容器執行個體。如果您的現有叢集有至少一個向其註冊的容器執行個體，並有可用資源可執行為此教學課程建立的一個任務定義執行個體，您可以跳到下一個步驟。

在本教學課程中，我們將使用 Amazon ECS 最佳化 Amazon Linux 2 AMI 建立具有一個 `t2.micro` 容器執行個體的叢集。

如需有關如何建立 EC2 叢集的資訊，請參閱[為 Amazon EC2 工作負載建立 Amazon ECS 叢集](create-ec2-cluster-console-v2.md)。

## 步驟 5：執行任務
<a name="specifying-sensitive-data-tutorial-run-task"></a>

您可以透過 Amazon ECS 主控台，使用您建立的任務定義來執行任務。在本教學課程中，我們將會執行使用 EC2 的任務，並使用我們在前一個步驟中建立的叢集。

如需有關如何執行任務的資訊，請參閱 [將應用程式作為 Amazon ECS 任務執行](standalone-task-create.md)。

## 步驟 6：驗證
<a name="specifying-sensitive-data-tutorial-verify"></a>

您可以使用下列步驟，驗證是否已成功完成所有步驟，以及是否已在您的容器中正確建立環境變數。

**驗證是否已建立環境變數**

1. 尋找您容器執行個體的公有 IP 或 DNS 地址。

   1. 開啟主控台，網址為 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)。

   1. 在導覽窗格中，選擇**叢集**，然後選擇建立的叢集。

   1. 選擇**基礎設施**，然後選擇容器執行個體。

   1. 記錄您執行個體的**公有 IP** 或**公有 DNS**。

1. 如果您使用的是 macOS 或 Linux 電腦，請使用下列命令連線到您的執行個體，並替換為您私有金鑰的路徑及執行個體的公有地址：

   ```
   $ ssh -i /path/to/my-key-pair.pem ec2-user@ec2-198-51-100-1.compute-1.amazonaws.com
   ```

   如需有關使用 Windows 電腦的詳細資訊，請參閱 *Amazon EC2 User Guide* 中的 [Connect to your Linux instance using PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-from-windows.html)。
**重要**  
如需有關執行個體連線問題的詳細資訊，請參閱 *Amazon EC2 User Guide* 中的 [Troubleshooting Connecting to Your Instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html)。

1. 列出在執行個體上執行的容器。請記下 `ecs-secrets-tutorial` 容器的容器 ID。

   ```
   docker ps
   ```

1. 使用上一個步驟輸出中的容器 ID，連接到 `ecs-secrets-tutorial` 容器。

   ```
   docker exec -it container_ID /bin/bash
   ```

1. 使用 `echo` 命令來列印環境變數的值。

   ```
   echo $username_value
   ```

   如果教學課程成功，您應該會看到以下輸出：

   ```
   password_value
   ```
**注意**  
或者，您可以使用 `env` (或 `printenv`) 命令列出您容器中的所有環境變數。

## 步驟 7：清除
<a name="specifying-sensitive-data-tutorial-cleanup"></a>

完成此教學課程時，建議您清除相關聯的資源，以免未使用的資源產生費用。

**清除資源**

1. 開啟主控台，網址為 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)。

1. 在導覽窗格中，選擇**叢集**。

1. 在**叢集**頁面上，選擇叢集。

1. 選擇 **Delete Cluster (刪除叢集)**。

1. 在確認方塊中，輸入 **delete *叢集名稱***，然後選擇**刪除**。

1. 在以下網址開啟 IAM 主控台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。

1. 在導覽窗格中，選擇**角色**。

1. 搜尋 `ecsTaskExecutionRole` 的角色清單並加以選取。

1. 選擇**許可**，然後選擇 **ECSSecretsTutorial** 旁邊的 **X**。選擇**移除**。

1. 開啟位於的 Secrets Manager 主控台[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。

1. 選取您所建立的 **username\$1value** 秘密，然後選擇 **Actions (動作)**、**Delete secret (刪除秘密)**。