Amazon Elastic Container Service
开发人员指南 (API 版本 2014-11-13)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

容器实例的私有注册表身份验证

Amazon ECS 容器代理可使用基本身份验证对私有注册表(包括 Docker Hub)进行身份验证。当启用私有注册表身份验证时,您可以在任务定义中使用私有 Docker 映像。只有使用 EC2 启动类型的任务才支持此功能。

另一种启用私有注册表身份验证的方法是使用 AWS Secrets Manager 在容器定义中安全地存储并随后引用您的私有注册表凭证。这样,您的任务就可以使用私有存储库中的映像。此方法支持使用 EC2 或 Fargate 启动类型的任务。有关更多信息,请参阅任务的私有注册表身份验证

Amazon ECS 容器代理在启动时将查找两个环境变量:

  • ECS_ENGINE_AUTH_TYPE,指定要发送的身份验证数据的类型。

  • ECS_ENGINE_AUTH_DATA,包含实际身份验证凭证。

当容器实例启动时以及每次启动服务(利用 sudo start ecs 命令)时,Amazon ECS-optimized AMI 的 Linux 变体将在 /etc/ecs/ecs.config 文件中扫描这些变量。未经 Amazon ECS 优化的 AMI 应将这些环境变量存储在一个文件中,然后利用 --env-file path_to_env_file 选项将其传递到用于启动容器代理的 docker run 命令。

重要

我们不建议在实例启动时利用 Amazon EC2 用户数据注入这些身份验证环境变量或利用 --env 选项将其传递到 docker run 命令。这些方法不适合敏感数据,如身份验证凭证。有关将身份验证凭证安全地添加到容器实例的信息,请参阅将容器实例配置存储在 Amazon S3 中

身份验证格式

私有注册表身份验证有两种可用格式:dockercfgdocker

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 ~/.docker/config.json | jq .auths

cat ~/.docker/config.json | jq .auths

输出:

{
  "https://index.docker.io/v1/": {
    "auth": "zq212MzEXAMPLE7o6T25Dk0i",
    "email": "email@example.com"
  }
}

在上面的示例中,以下环境变量应添加到 Amazon ECS 容器代理在运行时加载的环境变量文件中(对于Amazon ECS-optimized AMI,该文件为 /etc/ecs/ecs.config)。如果没有使用Amazon ECS-optimized 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-optimized AMI,该文件为 /etc/ecs/ecs.config)。如果没有使用Amazon ECS-optimized 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-optimized AMI 中启用私有注册表

  1. 使用 SSH 登录到您的容器实例。

  2. 打开 /etc/ecs/ecs.config 文件并为注册表和账户添加 ECS_ENGINE_AUTH_TYPEECS_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"}}
  3. 检查您的代理是否使用 ECS_DATADIR 环境变量保存其状态:

    docker inspect ecs-agent | grep ECS_DATADIR

    输出:

    "ECS_DATADIR=/data",

    重要

    如果上一个命令未返回 ECS_DATADIR 环境变量,则您在停止代理前必须停止在此容器实例上运行的任何任务。使用 ECS_DATADIR 环境变量的较新的代理将会保存其状态,您可以在任务运行的过程中停止和启动它们,而不会造成问题。有关更多信息,请参阅更新 Amazon ECS 容器代理

  4. 停止 ecs 服务:

    sudo stop ecs

    输出:

    ecs stop/waiting
  5. 重新启动 ecs 服务。

    • 对于Amazon ECS-optimized Amazon Linux 2 AMI:

      sudo systemctl restart ecs
    • 对于Amazon ECS-optimized Amazon Linux AMI:

      sudo stop ecs && sudo start ecs
  6. (可选) 您可以通过查询代理自检 API 操作,验证代理是否正在运行并查看有关新容器实例的一些信息。有关更多信息,请参阅 Amazon ECS 容器代理自检

    curl http://localhost:51678/v1/metadata

    输出:

    {
      "Cluster": "default",
      "ContainerInstanceArn": "<container_instance_ARN>",
      "Version": "Amazon ECS Agent - v1.32.0 (a7f81040)"
    }