本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 為私有 Docker 映像檔設定 Amazon ECS 容器執行個體
Amazon ECS 容器代理程式可利用基本身分驗證，使用私有登錄檔進行身分驗證。當您啟用私有登錄檔身分驗證時，您可以使用您任務定義中的私有 Docker 映像。只有使用 EC2 的任務才支援此功能。
另一種啟用私有登錄檔身分驗證的方法 AWS Secrets Manager ，是使用 安全地存放私有登錄檔登入資料，然後在容器定義中參考它們。這可讓您的任務使用來自私有儲存庫的映像。此方法支援使用 EC2 或 Fargate 的任務。如需詳細資訊，請參閱[在 Amazon ECS 中使用非AWS 容器映像](private-auth.md)。
Amazon ECS 容器代理程式會在啟動時尋找兩個環境變數：
+ `ECS_ENGINE_AUTH_TYPE` 可指定要傳送之身分驗證資料的類型。
+ `ECS_ENGINE_AUTH_DATA` 包含實際身分驗證的登入資料。
Linux 版 Amazon ECS 最佳化 AMI 會在容器執行個體啟動及每一次服務啟動時 (使用 **sudo start ecs** 命令)，針對這些變數掃描 `/etc/ecs/ecs.config` 檔案。不是 Amazon ECS 最佳化的 AMI 應將這些環境變數存放在一個檔案中，並使用 `--env-file path_to_env_file` 選項將它們傳遞到啟動容器代理程式的 **docker run** 命令。
**重要**
我們不建議您在執行個體啟動時使用 Amazon EC2 使用者資料插入這些身分驗證環境變數，或使用 `--env` 選項將它們傳遞至 **docker run** 命令。這些方法不適合用於敏感性資料，例如身分驗證登入資料。如需將安全地將身分驗證登入資料新增至容器執行個體的詳細資訊，請參閱 [將 Amazon ECS 容器執行個體組態儲存於 Amazon S3 中](ecs-config-s3.md)。
## 身分驗證格式
私有登錄檔身分驗證有兩種可用的格式，`dockercfg` 和 `docker`。
**dockercfg 身分驗證格式**
`dockercfg` 格式使用存放在執行 **docker login** 命令時建立之組態檔中的身分驗證資訊。您可以透過在您的本機系統上執行 **docker login**，輸入您的登錄使用者名稱、密碼及電子郵件地址來建立此檔案。您也可以登入容器執行個體，並在該處執行命令。根據您的 Docker 版本，這個檔案會做為 `~/.dockercfg` 或 `~/.docker/config.json` 儲存。
```
cat ~/.docker/config.json
```
輸出：
```
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "zq212MzEXAMPLE7o6T25Dk0i"
}
}
}
```
**重要**
較新版本的 Docker 會如上所示，使用外部 `auths` 物件建立組態檔。Amazon ECS 代理程式只支援以下格式的 `dockercfg` 身分驗證資料，而不包含 `auths` 物件。如果您已安裝 **jq** 公用程式，即可使用以下命令擷取此資料：**cat \$1/.docker/config.json \$1 jq .auths**
```
cat ~/.docker/config.json | jq .auths
```
輸出：
```
{
"https://index.docker.io/v1/": {
"auth": "zq212MzEXAMPLE7o6T25Dk0i",
"email": "email@example.com"
}
}
```
在上述範例中，以下環境變數應新增到 Amazon ECS 容器代理程式在執行時間載入的環境變數檔案 (適用於 Amazon ECS 最佳化 AMI 的 `/etc/ecs/ecs.config`)。如果您不使用 Amazon ECS 最佳化 AMI，且您使用 **docker run** 手動啟動代理程式，請在啟動代理程式時使用 `--env-file path_to_env_file` 選項指定環境變數檔案。
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
```
您可以使用以下語法設定多個私有登錄檔：
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example-01.com"},"repo.example-02.com":{"auth":"fQ172MzEXAMPLEoF7225DU0j","email":"email@example-02.com"}}
```
**docker 身分驗證格式**
`docker` 格式會使用代理程式應進行身分驗證的登錄伺服器 JSON 表示法。它也包含了該登錄所需要的身分驗證參數 (例如該帳戶的使用者名稱、密碼和電子郵件地址)。針對 Docker Hub 帳戶，JSON 表示法如以下內容所示：
```
{
"https://index.docker.io/v1/": {
"username": "my_name",
"password": "my_password",
"email": "email@example.com"
}
}
```
在此範例中，以下環境變數應新增到 Amazon ECS 容器代理程式在執行時間載入的環境變數檔案 (適用於 Amazon ECS 最佳化 AMI 的 `/etc/ecs/ecs.config`)。如果您不使用 Amazon ECS 最佳化 AMI，且您使用 **docker run** 手動啟動代理程式，請在啟動代理程式時使用 `--env-file path_to_env_file` 選項指定環境變數檔案。
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
```
您可以使用以下語法設定多個私有登錄檔：
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"username":"my_name","password":"my_password","email":"email@example-01.com"},"repo.example-02.com":{"username":"another_name","password":"another_password","email":"email@example-02.com"}}
```
## 程序
使用以下程序，開啟容器執行個體的私有登錄檔。
**若要在 Amazon ECS 最佳化 AMI 中啟用私有登錄檔**
1. 使用 SSH 登入您的容器執行個體。
1. 開啟 `/etc/ecs/ecs.config` 檔案，為您的登錄檔和帳戶新增 `ECS_ENGINE_AUTH_TYPE` 和 `ECS_ENGINE_AUTH_DATA` 值：
```
sudo vi /etc/ecs/ecs.config
```
此範例會驗證 Docker Hub 使用者帳戶：
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
```
1. 檢查您的代理程式是否是使用 `ECS_DATADIR` 環境變數儲存其狀態：
```
docker inspect ecs-agent | grep ECS_DATADIR
```
輸出：
```
"ECS_DATADIR=/data",
```
**重要**
若先前的命令並未傳回 `ECS_DATADIR` 環境變數，您必須停止任何在此容器執行個體上執行的任務，才能停止您的代理。較新的代理會使用 `ECS_DATADIR` 環境變數儲存其狀態，讓您可以在任務執行中時停止和啟動它們，而不會有任何問題。如需詳細資訊，請參閱[更新 Amazon ECS 容器代理程式](ecs-agent-update.md)。
1. 停止 `ecs` 服務：
```
sudo stop ecs
```
輸出：
```
ecs stop/waiting
```
1. 重新啟動 `ecs` 服務。
+ 對於 Amazon ECS 最佳化 Amazon Linux 2 AMI：
```
sudo systemctl restart ecs
```
+ 對於 Amazon ECS 最佳化 Amazon Linux AMI：
```
sudo stop ecs && sudo start ecs
```
1. (選用) 您可以驗證代理已在執行中，並透過查詢代理自我檢查 API 操作，查看您新的容器執行個體的一些資訊。如需詳細資訊，請參閱[Amazon ECS 容器自我檢查](ecs-agent-introspection.md)。
```
curl http://localhost:51678/v1/metadata
```