Amazon EC2 Container Service
开发人员指南 (API Version 2014-11-13)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Amazon ECS 容器代理配置

Amazon ECS 容器代理支持很多部署选项,其中大多数选项应通过环境变量来设置。提供了以下环境变量,并且它们都是可选的。

如果容器实例是利用针对 Amazon ECS 优化过的 AMI 启动的,则可以在 /etc/ecs/ecs.config 文件中设置这些环境变量,然后重新启动代理。您还可以在启动时将这些配置变量写入到具有 Amazon EC2 用户数据的容器实例。有关更多信息,请参阅 使用 Amazon EC2 用户数据引导启动容器实例

如果要手动启动 Amazon ECS 容器代理 (对于没有针对 Amazon ECS 优化过的 AMI),则可以在用于启动代理的 docker run 命令中使用这些环境变量 (使用语法 --env=VARIABLE_NAME=VARIABLE_VALUE)。对于敏感信息 (如私有存储库的身份验证凭证),您应该将代理环境变量存储在一个文件中并利用 --env-file path_to_env_file 选项一次性将它们传递完。

可用参数

环境键 示例值 说明 默认值
ECS_CLUSTER MyCluster 此代理应签入的集群。如果此值未定义,则假定使用 default 群集。如果 default 群集不存在,Amazon ECS 容器代理会尝试创建它。如果指定了非 default 群集,但该群集不存在,注册将失败。 default
ECS_RESERVED_PORTS [22, 80, 5000, 8080] 应标记为不可用于在此容器实例上的计划的一组端口。 [22, 2375, 2376, 51678]
ECS_RESERVED_PORTS_UDP [53, 123] 应标记为不可用于在此容器实例上的计划的一组 UDP 端口。 []
ECS_ENGINE_AUTH_TYPE dockercfg | docker 对于私有注册表身份验证是必需的。这是 ECS_ENGINE_AUTH_DATA 中的身份验证数据的类型。有关更多信息,请参阅 身份验证格式 Null
ECS_ENGINE_AUTH_DATA

示例 (ECS_ENGINE_AUTH_TYPE=dockercfg):

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

示例 (ECS_ENGINE_AUTH_TYPE=docker):

{"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}

对于私有注册表身份验证是必需的。如果 ECS_ENGINE_AUTH_TYPE=dockercfg,则 ECS_ENGINE_AUTH_DATA 值应该是通过运行 docker login 创建的 Docker 配置文件 (~/.dockercfg~/.docker/config.json) 的内容。如果 ECS_ENGINE_AUTH_TYPE=docker,则 ECS_ENGINE_AUTH_DATA 值应该是身份验证所针对的注册表服务器的 JSON 表示形式,以及注册表所需的身份验证参数(如该账户的用户名、密码和电子邮件地址)。有关更多信息,请参阅 身份验证格式 Null
AWS_DEFAULT_REGION us-east-1 要在 API 请求中使用以及用于推断正确的后端主机的区域。 从 EC2 实例元数据中获取。
AWS_ACCESS_KEY_ID AKIAIOSFODNN7EXAMPLE 由代理用于所有调用的访问密钥 从 EC2 实例元数据中获取。
AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY 由代理用于所有调用的私有密钥 从 EC2 实例元数据中获取。
DOCKER_HOST unix:///var/run/docker.sock 用于创建与 Docker 守护程序的连接;行为方式与 Docker 客户端使用的环境变量相似。 unix:///var/run/docker.sock
ECS_LOGLEVEL crit | error | warn | info | debug 要在 stdout 上进行日志记录的级别。 info
ECS_LOGFILE /ecs-agent.log 要将完整调试信息输出到的路径。如果为空白,则不会记录任何日志。如果设置此值,则将调试级别(无论 ECS_LOGLEVEL 如何)的日志写入到该文件。 Null
ECS_CHECKPOINT true | false 是否要将检查点状态保存到利用 ECS_DATADIR 指定的位置。 如果 ECS_DATADIR 显式设置为非空值,则 ECS_CHECKPOINT 将设置为 true;否则,它将设置为 false
ECS_DATADIR /data 正在运行 Amazon ECS 容器代理的容器上的永久数据目录的名称。该目录用于保存有关集群和代理状态的信息。 Null
ECS_UPDATES_ENABLED true | false 在请求 ECS 代理更新时是否退出以进行更新。 false
ECS_UPDATE_DOWNLOAD_DIR /cache 要放置容器中的已下载的更新 tarball 的文件系统位置。
ECS_DISABLE_METRICS true | false 是否对 Amazon ECS 禁用 CloudWatch 指标。如果此值设置为 true,则不会收集 CloudWatch 指标。 false
ECS_DOCKER_GRAPHPATH /var/lib/docker 用于创建已启动容器的状态文件的路径。状态文件用于读取容器的利用率指标。 /var/lib/docker
AWS_SESSION_TOKEN 用于临时凭证的会话令牌 从 EC2 实例元数据中获取。
ECS_RESERVED_MEMORY 32 要为不由 ECS 管理的进程预留的内存量(以 MiB 为单位)。 0
ECS_AVAILABLE_LOGGING_DRIVERS ["json-file","awslogs"]

有关如何使用 awslogs 日志驱动程序的信息,请参阅使用 awslogs 日志驱动程序

有关可用于 Docker 版本的不同日志驱动程序的更多信息,请参阅 Docker 文档中的配置日志记录驱动程序

容器实例上可用的日志记录驱动程序。在容器实例上运行的 Amazon ECS 容器代理必须先将该实例上可用的日志记录驱动程序注册到 ECS_AVAILABLE_LOGGING_DRIVERS 环境变量,然后放置在该实例上的容器才能在任务中使用这些驱动程序的日志配置选项。 ["json-file","awslogs"]
ECS_DISABLE_PRIVILEGED true | false 是否在容器实例上禁用启动特权容器。如果此值设置为 true,则不允许使用特权容器。 false
ECS_SELINUX_CAPABLE true | false SELinux 是否在容器实例上可用。 false
ECS_APPARMOR_CAPABLE true | false AppArmor 是否在容器实例上可用。 false
ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION 1h(有效时间单位为“ns”、“us”(或“µs”)、“ms”、“s”、“m”和“h”。) 从任务停止到删除 Docker 容器所等待的持续时间。由于这将删除 Docker 容器数据,因此请注意,如果此值设置得过低,您可能无法检查已停止的容器或无法在日志删除前查看它们。最短持续时间为 1m;任何短于 1 分钟的值都会被忽略。 3h
ECS_CONTAINER_STOP_TIMEOUT 10m(有效时间单位为“ns”、“us”(或“µs”)、“ms”、“s”、“m”和“h”。) 从任务停止到其容器由于未自行正常退出而被强制终止所等待的持续时间。 30s
HTTP_PROXY 10.0.0.131:3128 供 ECS 代理用来连接到 Internet 的 HTTP 代理的主机名(或 IP 地址)和端口号(例如,在您的容器实例无法通过 Amazon VPC Internet 网关或 NAT 网关/实例的访问外部网络的情况下)。如果设置了此变量,您还必须设置 NO_PROXY 变量以筛选来自 HTTP 代理的 EC2 实例元数据和 Docker 守护程序流量。有关更多信息,请参阅 HTTP 代理配置 Null
NO_PROXY
  • Linux: 169.254.169.254,169.254.170.2,/var/run/docker.sock

  • Windows: 169.254.169.254,169.254.170.2,\\.\pipe\docker_engine

不应转发到指定的 HTTP_PROXY 的 HTTP 流量。您必须指定 169.254.169.254,/var/run/docker.sock 以筛选来自 HTTP 代理的 EC2 实例元数据和 Docker 守护程序流量。有关更多信息,请参阅 HTTP 代理配置 Null
ECS_ENABLE_TASK_IAM_ROLE true | false 是否应在具有 bridgedefault 网络模式的任务容器的容器实例上启用任务的 IAM 角色。有关更多信息,请参阅 任务的 IAM 角色 false
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST true | false 是否应在具有 host 网络模式的任务容器的容器实例上启用任务的 IAM 角色。此变量仅在代理版本 1.12.0 和更高版本上受支持。有关更多信息,请参阅 任务的 IAM 角色 false
ECS_DISABLE_IMAGE_CLEANUP true 是否为 Amazon ECS 代理禁用自动化映像清除。有关更多信息,请参阅 自动化任务和映像清除 false
ECS_IMAGE_CLEANUP_INTERVAL 30m 自动化映像清除周期之间的时间间隔。如果设置为短于 10 分钟,该值将被忽略。 30m
ECS_IMAGE_MINIMUM_CLEANUP_AGE 30m 拉取映像与可考虑将其进行自动化映像清除之间的最短时间间隔。 1h
ECS_NUM_IMAGES_DELETE_PER_CYCLE 5 要在单次自动化映像清除周期中删除的映像的最大数量。如果设置为小于 1,该值将被忽略。 5
ECS_INSTANCE_ATTRIBUTES {"custom attribute": "custom_attribute_value"}

有关可用自定义属性的信息,请参阅属性

自定义属性列表为 JSON 形式,应用于您的容器实例。在实例注册时使用该属性会添加自定义属性,这样可跳过通过 AWS 管理控制台手动添加自定义属性的方法。

此变量的无效 JSON 值将导致代理退出,代码为 5,代理日志中也将出现一条消息。如果 JSON 值有效,但验证属性时发现问题 (例如,值过长或包含无效字符),仍会进行容器实例注册,但代理会退出,代码为 5,代理日志中也将写入一条消息。有关如何找到代理日志的信息,请参阅Amazon ECS 容器代理日志

Null

将容器实例配置存储在 Amazon S3 中

Amazon ECS 容器代理配置通过上面所述的环境变量来控制。针对 Amazon ECS 优化过的 AMI 将在容器代理启动时检查 /etc/ecs/ecs.config 中是否有这些变量,并相应地配置代理。某些无害环境变量(如 ECS_CLUSTER)可在启动时通过 Amazon EC2 用户数据传递到容器实例,并可写入到此文件而不会造成任何后果。但是,其他敏感信息 (如您的 AWS 凭证 ECS_ENGINE_AUTH_DATA 变量) 不应通过用户数据传递到某个实例或以它们将在 .bash_history 文件中显示的方式写入到 /etc/ecs/ecs.config

将配置信息存储在 Amazon S3 中的私有存储桶中并向您的容器实例 IAM 角色授予只读访问权限,这是一个允许在启动时配置容器实例的安全方便的方法。您可以将 ecs.config 文件的副本存储在私有存储桶中,再使用 Amazon EC2 用户数据安装 AWS CLI,然后在实例启动时将配置信息复制到 /etc/ecs/ecs.config

为容器实例角色授予 Amazon S3 只读访问权限

  1. 通过以下网址打开 IAM 控制台:https://console.amazonaws.cn/iam/

  2. 在导航窗格中,选择 Roles

  3. 选择用于容器实例的 IAM 角色(此角色可能名为 ecsInstanceRole)。有关更多信息,请参阅 Amazon ECS 容器实例 IAM 角色

  4. Managed Policies 下,选择 Attach Policy

  5. Attach Policy 页面上,将 S3 键入到 Filter 字段中以缩小策略结果的范围。

  6. 选中 AmazonS3ReadOnlyAccess 策略左侧的框并单击 Attach Policy

在 Amazon S3 中存储 ecs.config 文件

  1. 采用以下格式,利用ecs.config中的有效环境变量和值创建 Amazon ECS 容器代理配置 文件。此示例将配置私有注册表身份验证。有关更多信息,请参阅私有注册表身份验证

    Copy
    ECS_ENGINE_AUTH_TYPE=dockercfg ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
  2. 在 Amazon S3 中创建私有存储桶以存储您的配置文件。有关更多信息,请参阅 Amazon Simple Storage Service 入门指南 中的创建存储桶

  3. ecs.config 文件上传到 Amazon S3 存储桶。有关更多信息,请参阅 Amazon Simple Storage Service 入门指南 中的将对象添加到存储桶

在启动时从 Amazon S3 加载 ecs.config 文件

  1. 完成本节中的上述过程以允许 Amazon S3 对您的容器实例进行只读访问,并将 ecs.config 文件存储在私有 Amazon S3 存储桶中。

  2. 通过执行启动 Amazon ECS 容器实例中的步骤启动新的容器实例。在步骤 7中,使用以下示例脚本。该脚本将安装 AWS CLI 并将您的配置文件复制到 /etc/ecs/ecs.config

    Copy
    #!/bin/bash yum install -y aws-cli aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config