Amazon Elastic Container Service Agent 镜像文档

1. 镜像概述和主要用途

Amazon Elastic Container Service (ECS) Agent 是 Amazon ECS 的核心组件，用于在 Amazon EC2 实例上协调和管理容器的生命周期。该镜像作为 EC2 实例与 ECS 服务之间的通信桥梁，负责接收 ECS 服务的任务定义、启动/停止容器、监控容器状态并上报实例和任务信息。

注意：此镜像仅支持在 Amazon EC2 实例上运行。在 EC2 外部环境中运行不受支持，可能因依赖 EC2 元数据服务等原因无法正常工作。

2. 核心功能与特性

• Docker 守护进程交互：通过挂载 Docker 套接字（/var/run/docker.sock）与主机 Docker 守护进程通信，实现容器生命周期管理。
• 任务协调：接收 ECS 服务下发的任务定义，在 EC2 实例上调度和运行容器。
• 状态上报：实时监控容器运行状态，并向 ECS 服务上报实例资源使用情况和任务状态。
• 日志与数据管理：支持日志文件和运行数据的持久化存储，确保代理运行信息可追溯。
• 配置灵活性：通过环境变量自定义日志路径、日志级别、数据目录等核心参数。

3. 使用场景与适用范围

适用范围

• 仅运行在 Amazon EC2 实例上。
• 需配合 Amazon ECS 服务使用。

使用场景

• 构建基于 Amazon ECS 的容器集群，管理容器化应用的部署、扩展和运行。
• 在非 ECS 优化 AMI 的 EC2 实例上手动部署 ECS Agent，加入 ECS 集群。

4. 标签说明

• latest：始终指向最新稳定版本的 Agent。
• 版本标签：格式为 vX.Y.Z（如 v1.1.0），对应特定发布版本，用于版本锁定。

5. 使用方法

5.1 前置条件

• 运行环境为 Amazon EC2 实例。
• 实例已安装 Docker 且 Docker 守护进程正常运行。

5.2 直接通过 Docker 运行

推荐通过以下命令启动 ECS Agent，关键配置包括挂载 Docker 套接字、日志目录、数据目录，以及设置必要环境变量：

docker run --name ecs-agent -d \
  -v /var/run/docker.sock:/var/run/docker.sock \  # 挂载 Docker 套接字，实现与 Docker 守护进程通信
  -v /var/log/ecs/:/log \                         # 挂载日志目录，持久化 Agent 日志
  -v /var/lib/ecs/data:/data \                    # 挂载数据目录，存储 Agent 运行数据
  -p 127.0.0.1:51678:51678 \                      # 本地端口映射，Agent 内部端口 51678
  -e ECS_LOGFILE=/log/ecs-agent.log \             # 指定日志文件路径
  -e ECS_LOGLEVEL=info \                          # 设置日志级别（info/warn/debug等）
  -e ECS_DATADIR=/data \                          # 指定数据存储目录
  amazon/amazon-ecs-agent:latest

5.3 Docker Compose 配置示例

创建 docker-compose.yml 文件，内容如下：

version: '3'
services:
  ecs-agent:
    image: amazon/amazon-ecs-agent:latest
    container_name: ecs-agent
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/log/ecs/:/log
      - /var/lib/ecs/data:/data
    ports:
      - "127.0.0.1:51678:51678"
    environment:
      - ECS_LOGFILE=/log/ecs-agent.log
      - ECS_LOGLEVEL=info
      - ECS_DATADIR=/data

启动命令：docker-compose up -d

6. 配置说明

6.1 卷挂载说明

6.2 端口映射

• 127.0.0.1:51678:51678：将容器内 51678 端口映射到主机本地回环地址的 51678 端口，用于 Agent 内部通信。

6.3 环境变量配置

ECS Agent 支持通过环境变量自定义行为，完整列表可参考 Agent GitHub 页面。常用环境变量说明：

7. 更新方法

7.1 使用 Amazon ECS 优化 AMI 的场景

需遵循 ECS 官方文档 中的更新步骤。

7.2 手动部署的场景（非 ECS 优化 AMI）

通过以下命令更新至最新版本：

# 停止并删除现有 Agent 容器
docker stop ecs-agent
docker rm ecs-agent

# 拉取最新镜像
docker pull amazon/amazon-ecs-agent:latest

# 重新启动 Agent（使用 5.2 节中的 docker run 命令）
docker run --name ecs-agent -d ... amazon/amazon-ecs-agent:latest

8. 源代码与问题反馈

源代码

Agent 源代码托管于 GitHub：[***]

问题反馈

如遇使用问题，可在 GitHub Issues 页面提交：[***]