amazon/amazon-ecs-agent

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 套接字、日志目录、数据目录，以及设置必要环境变量：

bash
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 文件，内容如下：

yaml
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 支持通过环境变量自定义行为，完整列表可参考 https://github.com/aws/amazon-ecs-agent#environment-variables%E3%80%82%E5%B8%B8%E7%94%A8%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E8%AF%B4%E6%98%8E%EF%BC%9A

7. 更新方法

7.1 使用 Amazon ECS 优化 AMI 的场景

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

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

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

bash
# 停止并删除现有 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：https://github.com/aws/amazon-ecs-agent

问题反馈

如遇使用问题，可在 GitHub Issues 页面提交：https://github.com/aws/amazon-ecs-agent/issues