onsdigital/spp-ecs-task-runner

ecs-task-runner Docker镜像文档

镜像概述

ecs-task-runner是由ONSdigital开发的Docker镜像，旨在简化AWS ECS（Elastic Container Service）上一次性任务的管理流程。该镜像提供了任务定义提交、任务运行、状态监控、日志获取及任务生命周期管理的一站式解决方案，支持Fargate和EC2两种启动类型，适用于需要在ECS集群中执行短期、一次性任务的场景。

核心功能与特性

主要功能

• 任务生命周期管理：支持从任务定义提交、任务启动到任务完成的全流程管理，可自动等待任务结束并返回退出代码
• 多启动类型支持：兼容AWS Fargate（无服务器）和EC2（容器实例）两种ECS启动类型
• 日志集成：自动获取并输出任务运行日志，便于问题排查和任务监控
• 环境变量配置：通过环境变量灵活配置AWS认证、任务参数、网络设置等关键信息
• 错误处理：提供详细的错误信息，支持任务失败时的日志捕获和退出代码返回

技术特性

• 轻量级镜像，基于Alpine Linux构建，体积小、启动快
• 原生支持AWS SDK，无需额外安装AWS CLI
• 支持任务定义的JSON文件或内联JSON字符串配置
• 可配置任务超时时间，避免无限等待

使用场景与适用范围

ecs-task-runner适用于需要在AWS ECS集群中执行一次性、短期任务的场景，典型应用包括：

• CI/CD自动化流程：在持续集成/部署中运行测试任务、数据库迁移、应用部署验证等
• 数据处理任务：定时执行ETL作业、数据备份、日志分析等批处理任务
• 运维自动化：执行集群维护、配置更新、资源清理等管理任务
• 事件驱动型任务：响应外部事件（如S3文件上传、SQS消息）触发的一次性处理任务

使用方法与配置说明

前提条件

• 已配置AWS凭证（通过环境变量、IAM角色或AWS配置文件），且具备ECS任务执行权限
• 已创建ECS集群及任务定义（或通过参数动态生成任务定义）
• 网络配置满足任务运行需求（如VPC、子网、安全组）

镜像获取

bash
docker pull docker.xuanyuan.run/onsdigital/ecs-task-runner:latest

基本使用示例（Docker Run）

运行Fargate类型任务

bash
docker run --rm \
  -e AWS_REGION=eu-west-1 \
  -e AWS_ACCESS_KEY_ID=AKIAEXAMPLE \
  -e AWS_SECRET_ACCESS_KEY=secret \
  -e ECS_CLUSTER=my-cluster \
  -e LAUNCH_TYPE=FARGATE \
  -e TASK_DEFINITION='{"family":"my-task","networkMode":"awsvpc","containerDefinitions":[{"name":"my-container","image":"nginx","essential":true}]}' \
  -e SUBNETS=subnet-123456,subnet-789012 \
  -e SECURITY_GROUPS=sg-123456 \
  docker.xuanyuan.run/onsdigital/ecs-task-runner

使用任务定义文件

bash
docker run --rm \
  -v $(pwd)/task-definition.json:/task-definition.json \
  -e AWS_REGION=eu-west-1 \
  -e ECS_CLUSTER=my-cluster \
  -e TASK_DEFINITION_FILE=/task-definition.json \
  docker.xuanyuan.run/onsdigital/ecs-task-runner

关键配置参数

Docker Compose示例

yaml
version: '3'
services:
  ecs-task:
    image: docker.xuanyuan.run/onsdigital/ecs-task-runner:latest
    environment:
      - AWS_REGION=eu-west-1
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - ECS_CLUSTER=my-production-cluster
      - LAUNCH_TYPE=FARGATE
      - SUBNETS=subnet-abc123,subnet-def456
      - SECURITY_GROUPS=sg-xyz789
      - TASK_TIMEOUT=1800
    volumes:
      - ./task-definition.json:/task-definition.json
    command: --task-definition-file /task-definition.json

注意事项

• AWS权限：运行容器的环境需具备ecs:RunTask、ecs:DescribeTasks、logs:GetLogEvents等权限，建议通过IAM角色（如ECS任务执行角色）授权而非硬编码密钥
• 任务定义：确保任务定义中的网络配置（如awsvpc模式）与启动类型匹配（FARGATE仅支持awsvpc）
• 日志配置：任务定义需正确配置CloudWatch Logs驱动，否则可能无法获取日志
• 超时设置：根据任务实际运行时间调整TASK_TIMEOUT，避免过早终止长时间运行的任务

更多详细信息请参考https://github.com/ONSdigital/ecs-task-runner%E3%80%82