Amazon Elastic Container Service
开发人员指南 (API 版本 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

Linux 上的默认值:default

Windows 上的默认值:default

此代理应签入的集群。如果此值未定义,则假定使用 default 群集。如果 default 群集不存在,Amazon ECS 容器代理会尝试创建它。如果指定了非 default 群集,但该群集不存在,注册将失败。

ECS_RESERVED_PORTS

示例值:[22, 80, 5000, 8080]

Linux 上的默认值:[22, 2375, 2376, 51678, 51679]

Windows 上的默认值:[53, 135, 139, 445, 2375, 2376, 3389, 5985, 51678, 51679]

应标记为不可用于在此容器实例上的计划的一组端口。

ECS_RESERVED_PORTS_UDP

示例值:[53, 123]

Linux 上的默认值:[]

Windows 上的默认值:[]

应标记为不可用于在此容器实例上的计划的一组 UDP 端口。

ECS_ENGINE_AUTH_TYPE

示例值:dockercfg | docker

Linux 上的默认值:Null

Windows 上的默认值: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"}}

Linux 上的默认值:Null

Windows 上的默认值: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

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

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

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

AWS_ACCESS_KEY_ID

示例值:AKIAIOSFODNN7EXAMPLE

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

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

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

AWS_SECRET_ACCESS_KEY

示例值:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

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

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

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

AWS_SESSION_TOKEN

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

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

用于临时凭证的会话令牌

DOCKER_HOST

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

Linux 上的默认值:unix:///var/run/docker.sock

Windows 上的默认值:npipe:////./pipe/docker_engine

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

ECS_LOGLEVEL

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

Linux 上的默认值:info

Windows 上的默认值:info

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

ECS_LOGFILE

示例值:/ecs-agent.log

Linux 上的默认值:Null

Windows 上的默认值:Null

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

ECS_CHECKPOINT

示例值:true | false

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

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

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

ECS_DATADIR

示例值:/data

Linux 上的默认值:/data/

Windows 上的默认值:C:\ProgramData\Amazon\ECS\data

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

ECS_UPDATES_ENABLED

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_UPDATE_DOWNLOAD_DIR

示例值:/cache

Linux 上的默认值:Null

Windows 上的默认值:Null

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

ECS_DISABLE_METRICS

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:true

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

ECS_RESERVED_MEMORY

示例值:32

Linux 上的默认值:0

Windows 上的默认值:0

要从分配给您的任务的池中删除的内存量 (MiB)。这将为关键系统进程 (包括 Docker 守护程序和 Amazon ECS 容器代理) 有效预留内存。例如,如果您指定 ECS_RESERVED_MEMORY=256,则代理将为该实例注册总内存减去 256 MiB 后得到的内存量,256 MiB 的系统内存无法由 ECS 任务分配。有关更多信息,请参阅 Container Instance Memory Management

ECS_AVAILABLE_LOGGING_DRIVERS

示例值:["awslogs","fluentd","gelf","json-file","journald","splunk"]

Linux 上的默认值:["json-file","none"]

Windows 上的默认值:["json-file","none"]

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

ECS_DISABLE_PRIVILEGED

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_SELINUX_CAPABLE

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_APPARMOR_CAPABLE

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION

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

Linux 上的默认值:3h

Windows 上的默认值:3h

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

ECS_CONTAINER_STOP_TIMEOUT

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

Linux 上的默认值:30s

Windows 上的默认值:30s

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

ECS_CONTAINER_START_TIMEOUT

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

Linux 上的默认值:3m

Windows 上的默认值:8m

在放弃启动容器之前等待的时间期限。

HTTP_PROXY

示例值:10.0.0.131:3128

Linux 上的默认值:Null

Windows 上的默认值: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

Linux 上的默认值:Null

Windows 上的默认值:Null

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

ECS_ENABLE_TASK_IAM_ROLE

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_DISABLE_IMAGE_CLEANUP

示例值:true

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_IMAGE_CLEANUP_INTERVAL

示例值:30m

Linux 上的默认值:30m

Windows 上的默认值:30m

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

ECS_IMAGE_MINIMUM_CLEANUP_AGE

示例值:30m

Linux 上的默认值:1h

Windows 上的默认值:1h

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

ECS_NUM_IMAGES_DELETE_PER_CYCLE

示例值:5

Linux 上的默认值:5

Windows 上的默认值:5

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

ECS_IMAGE_PULL_BEHAVIOR

示例值:default | always | once | prefer-cached

Linux 上的默认值:default

Windows 上的默认值:default

用于为您的容器实例自定义拉取映像流程的行为。下面介绍了可选行为:

  • 如果指定 default,则远程拉取映像。如果映像拉取失败,容器将在实例上使用缓存的映像。

  • 如果指定 always,则始终远程拉取映像。如果映像拉取失败,任务将失败。此选项可确保始终拉取映像的最新版本。所有缓存映像均被忽略,并受自动映像清除过程支配。

  • 如果指定 once,则在之前尚未拉取映像或映像已被自动映像清除过程删除时远程拉取映像。否则,将使用实例上缓存的映像。这样可确保不会进行不必要的映像拉取尝试。

  • 如果指定 prefer-cached,则在没有缓存映像时远程拉取映像。否则,将使用实例上缓存的映像。为容器禁用自动映像清除,以确保不会删除缓存的映像。

ECS_INSTANCE_ATTRIBUTES

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

Linux 上的默认值:Null

Windows 上的默认值:Null

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

注意

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

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

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

ECS_ENABLE_TASK_ENI

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:不适用

是否为要使用其自己的网络接口启动的任务启用任务联网。

ECS_CNI_PLUGINS_PATH

示例值:/ecs/cni

Linux 上的默认值:/amazon-ecs-cni-plugins

Windows 上的默认值:不适用

cni 二进制文件所在的路径。

ECS_AWSVPC_BLOCK_IMDS

示例值:true | false

Linux 上的默认值:false

Windows 上的默认值:不适用

是否阻止使用 awsvpc 网络模式启动的任务对实例元数据的访问。

ECS_AWSVPC_ADDITIONAL_LOCAL_ROUTES

示例值:["10.0.15.0/24"]

Linux 上的默认值:[]

Windows 上的默认值:不适用

awsvpc 网络模式中,将通过主桥而不是任务弹性网络接口路由至这些前缀的流量。

ECS_ENABLE_CONTAINER_METADATA

示例值:true

Linux 上的默认值:false

Windows 上的默认值:false

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

ECS_HOST_DATA_DIR

示例值:/var/lib/ecs

Linux 上的默认值:/var/lib/ecs

Windows 上的默认值:不适用

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

ECS_ENABLE_TASK_CPU_MEM_LIMIT

示例值:true | false

Linux 上的默认值:true

Windows 上的默认值:false

是否启用任务级 CPU 和内存限制。

ECS_CGROUP_PATH

示例值:/sys/fs/cgroup

Linux 上的默认值:/sys/fs/cgroup

Windows 上的默认值:不适用

ECS 代理需要的根 cgroup 路径。这是可从代理装载访问的路径。

ECS_ENABLE_CPU_UNBOUNDED_WINDOWS_WORKAROUND

示例值:true | false

Linux 上的默认值:不适用

Windows 上的默认值:false

当为 true 时,ECS 将允许 CPU 未绑定 (CPU=0) 任务与 CPU 绑定任务一起在 Windows 中运行。

ECS_TASK_METADATA_RPS_LIMIT

示例值:100,150

Linux 上的默认值:40,60

Windows 上的默认值:40,60

任务元数据终端节点的稳定状态和突增阈值限制的整数值 (用逗号分隔)。

将容器实例配置存储在 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 文件上传到 S3 存储桶。有关更多信息,请参阅 Amazon Simple Storage Service 入门指南 中的将对象添加到存储桶

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

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