Amazon Elastic Container Service
开发人员指南 (API Version 2014-11-13)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

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 群集。如果 default 群集不存在,Amazon ECS 容器代理会尝试创建它。如果指定了非 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

默认值:Null

对于私有注册表身份验证是必需的。这是 ECS_ENGINE_AUTH_DATA 中的身份验证数据的类型。有关更多信息,请参阅 身份验证格式

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"}}

默认值:Null

对于私有注册表身份验证是必需的。如果 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 表示形式,以及注册表所需的身份验证参数(如该账户的用户名、密码和电子邮件地址)。有关更多信息,请参阅 身份验证格式

AWS_DEFAULT_REGION

示例值: us-east-1

默认值:从 EC2 实例元数据中获取。

要在 API 请求中使用以及用于推断正确的后端主机的区域。

AWS_ACCESS_KEY_ID

示例值: AKIAIOSFODNN7EXAMPLE

默认值:从 EC2 实例元数据中获取。

由代理用于所有调用的访问密钥

AWS_SECRET_ACCESS_KEY

示例值: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

默认值:从 EC2 实例元数据中获取。

由代理用于所有调用的私有密钥

AWS_SESSION_TOKEN

用于临时凭证的会话令牌

默认值:从 EC2 实例元数据中获取。

DOCKER_HOST

示例值: unix:///var/run/docker.sock

默认值: unix:///var/run/docker.sock

用于创建与 Docker 守护程序的连接;行为方式与 Docker 客户端使用的环境变量相似。

ECS_LOGLEVEL

示例值: crit | error | warn | info | debug

默认值: info

要在 stdout 上进行日志记录的级别。

ECS_LOGFILE

示例值: /ecs-agent.log

默认值:Null

要将完整调试信息输出到的路径。如果为空白,则不会记录任何日志。如果设置此值,则将调试级别(无论 ECS_LOGLEVEL 如何)的日志写入到该文件。

ECS_CHECKPOINT

示例值: true | false

默认值:如果 ECS_DATADIR 显式设置为非空值,则 ECS_CHECKPOINT 将设置为 true;否则,它将设置为 false

是否要将检查点状态保存到 ECS_DATADIR 指定的位置。

ECS_DATADIR

示例值: /data

默认值:Null

正在运行 Amazon ECS 容器代理的容器上的永久数据目录的名称。该目录用于保存有关集群和代理状态的信息。

ECS_UPDATES_ENABLED

示例值: true | false

默认值: false

在请求 ECS 代理更新时是否退出以进行更新。

ECS_UPDATE_DOWNLOAD_DIR

示例值: /cache

要放置容器中的已下载的更新 tarball 的文件系统位置。

ECS_DISABLE_METRICS

示例值: true | false

默认值: false

是否对 Amazon ECS 禁用 CloudWatch 指标。如果此值设置为 true,则不会收集 CloudWatch 指标。

ECS_RESERVED_MEMORY

示例值:32

默认值:0

要为不由 ECS 管理的进程预留的内存量(以 MiB 为单位)。

ECS_AVAILABLE_LOGGING_DRIVERS

示例值: ["json-file","awslogs"]

默认值: ["json-file","awslogs"]

容器实例上可用的日志记录驱动程序。在容器实例上运行的 Amazon ECS 容器代理必须先将该实例上可用的日志记录驱动程序注册到 ECS_AVAILABLE_LOGGING_DRIVERS 环境变量,然后放置在该实例上的容器才能在任务中使用这些驱动程序的日志配置选项。有关如何使用 awslogs 日志驱动程序的信息,请参阅。有关可用于 Docker 版本的不同日志驱动程序的更多信息,请参阅 Docker 文档中的配置日志记录驱动程序

ECS_DISABLE_PRIVILEGED

示例值: true | false

默认值: false

是否在容器实例上禁用启动特权容器。如果此值设置为 true,则不允许使用特权容器。

ECS_SELINUX_CAPABLE

示例值: true | false

默认值: false

SELinux 是否在容器实例上可用。

ECS_APPARMOR_CAPABLE

示例值: true | false

默认值: false

AppArmor 是否在容器实例上可用。

ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION

示例值:1h (有效时间单位为“ns”、“us”(或“µs”)、“ms”、“s”、“m”和“h”。)

默认值: 3h

从任务停止到删除 Docker 容器所等待的持续时间。由于这将删除 Docker 容器数据,因此请注意,如果此值设置得过低,您可能无法检查已停止的容器或无法在日志删除前查看它们。最短持续时间为 1m;任何短于 1 分钟的值都会被忽略。

ECS_CONTAINER_STOP_TIMEOUT

示例值:10m (有效时间单位为“ns”、“us”(或“µs”)、“ms”、“s”、“m”和“h”。)

默认值: 30s

从任务停止到其容器由于未自行正常退出而被强制终止所等待的持续时间。

HTTP_PROXY

示例值: 10.0.0.131:3128

默认值:Null

供 ECS 代理用来连接到 Internet 的 HTTP 代理的主机名 (或 IP 地址)和端口号 (例如,在您的容器实例无法通过 Amazon VPC Internet 网关或 NAT 网关/实例的访问外部网络的情况下)。如果设置了此变量,您还必须设置 NO_PROXY 变量以筛选来自 HTTP 代理的 EC2 实例元数据和 Docker 守护程序流量。有关更多信息,请参阅 HTTP 代理配置

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

默认值:Null

不应转发到指定的 HTTP_PROXY 的 HTTP 流量。您必须指定 169.254.169.254,/var/run/docker.sock 以筛选来自 HTTP 代理的 EC2 实例元数据和 Docker 守护程序流量。有关更多信息,请参阅 HTTP 代理配置

ECS_ENABLE_TASK_IAM_ROLE

示例值: true | false

默认值: false

是否应在具有 bridgedefault 网络模式的任务容器的容器实例上启用任务的 IAM 角色。有关更多信息,请参阅 任务的 IAM 角色

ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST

示例值: true | false

默认值: false

是否应在具有 host 网络模式的任务容器的容器实例上启用任务的 IAM 角色。此变量仅在代理版本 1.12.0 和更高版本上受支持。有关更多信息,请参阅 任务的 IAM 角色

ECS_DISABLE_IMAGE_CLEANUP

示例值: true

默认值: false

是否为 Amazon ECS 代理禁用自动化映像清除。有关更多信息,请参阅 自动化任务和映像清除

ECS_IMAGE_CLEANUP_INTERVAL

示例值: 30m

默认值: 30m

自动化映像清除周期之间的时间间隔。如果设置为短于 10 分钟,该值将被忽略。

ECS_IMAGE_MINIMUM_CLEANUP_AGE

示例值: 30m

默认值: 1h

拉取映像与可考虑将其进行自动化映像清除之间的最短时间间隔。

ECS_NUM_IMAGES_DELETE_PER_CYCLE

示例值: 5

默认值: 5

要在单次自动化映像清除周期中删除的映像的最大数量。如果设置为小于 1,该值将被忽略。

ECS_INSTANCE_ATTRIBUTES

示例值: {"custom attribute": "custom_attribute_value"}

默认值:Null

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

注意

添加的属性将不会应用于已注册的容器实例。要向已注册的容器实例添加自定义属性,请参阅添加属性

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

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

ECS_ENABLE_CONTAINER_METADATA

示例值: true

默认值: false

当为 true 时,代理会创建一个文件,用于描述容器的元数据。此文件可以通过使用容器环境变量 $ECS_CONTAINER_METADATA_FILE 来定位和使用。

ECS_HOST_DATA_DIR

示例值: /var/lib/ecs

默认值: /var/lib/ecs

安装 ECS_DATADIR 的主机上的源目录。在 ECS 代理作为容器运行的情况下,我们使用它来确定容器元数据文件的源装载路径。我们不在 Windows 中使用此值,因为 ECS 代理并不作为容器运行。

将容器实例配置存储在 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 页面上的 Filter 中,键入 S3 以缩小策略结果的范围。

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

在 Amazon S3 中存储 ecs.config 文件

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

    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

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