chrissdh/gitlab-worker

ECS Fargate GitLab CI工作节点镜像

1. 镜像概述

本镜像专为GitLab CI/CD流水线设计，用于在AWS ECS Fargate服务上部署和运行CI/CD工作节点（worker）。集成GitLab Runner核心组件与ECS Fargate优化配置，提供轻量级、弹性伸缩的无服务器CI/CD任务执行环境，无需手动管理底层服务器 infrastructure。

2. 核心功能与特性

2.1 GitLab CI原生兼容

• 支持GitLab CI/CD流水线全流程，包括任务拉取、代码检出、构建执行、结果上报
• 兼容.gitlab-ci.yml标准语法及GitLab Runner 14.0+版本特性

2.2 ECS Fargate深度优化

• 针对Fargate无服务器环境优化镜像体积（基础镜像采用alpine或debian-slim）
• 内置ECS任务生命周期管理逻辑，适配Fargate任务调度与资源分配模型
• 支持Fargate任务元数据服务（Task Metadata Endpoint）访问

2.3 弹性与隔离性

• 任务级资源隔离，避免多CI任务相互干扰
• 支持基于Fargate任务数量的弹性伸缩，按需扩展CI工作能力
• 自动适配Fargate CPU/内存资源配置，支持1 vCPU至4 vCPU及对应内存规格

2.4 安全与合规

• 非root用户运行，遵循容器安全最佳实践
• 支持AWS IAM角色认证（通过任务执行角色或任务角色）
• 内置日志转发能力，支持对接CloudWatch Logs

3. 使用场景

• 无服务器CI/CD环境：适用于希望避免管理CI服务器的团队，通过Fargate实现完全托管的工作节点
• 弹性工作负载：CI任务量波动大的场景（如夜间批量构建、版本发布峰值），通过Fargate自动扩缩容控制成本
• 多团队隔离：企业级环境中，不同团队/项目可通过独立Fargate任务定义隔离CI资源
• AWS生态集成：已使用AWS ECS、S3、ECR等服务的团队，实现CI/CD流程与AWS基础设施无缝衔接

4. 使用方法与配置说明

4.1 镜像拉取

bash
docker pull [镜像仓库地址]/ecs-fargate-gitlab-ci-worker:latest

注：需替换[镜像仓库地址]为实际镜像仓库（如ECR、Docker Hub等）

4.2 GitLab Runner注册与配置

4.2.1 注册Runner

通过GitLab项目设置获取Runner注册令牌，执行以下命令注册Fargate工作节点类型Runner：

bash
docker run --rm -it [镜像仓库地址]/ecs-fargate-gitlab-ci-worker:latest \
  gitlab-runner register \
  --url "https://gitlab.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --executor "custom" \
  --custom-run-exec "/opt/ecs-fargate-runner" \
  --description "ECS Fargate CI Worker"

4.2.2 核心配置项

Runner配置文件（config.toml）关键参数：

toml
[[runners]]
  name = "ECS Fargate CI Worker"
  url = "https://gitlab.com/"
  token = "RUNNER_TOKEN"
  executor = "custom"
  [runners.custom]
    run_exec = "/opt/ecs-fargate-runner"
  [runners.docker]
    tls_verify = false
    image = "docker:20.10"  # 基础构建镜像，可自定义

4.3 环境变量说明

4.4 部署示例

4.4.1 Docker Run单机部署

bash
docker run -d \
  --name gitlab-ci-worker \
  -e AWS_REGION=us-east-1 \
  -e ECS_CLUSTER=gitlab-ci-cluster \
  -e ECS_TASK_DEFINITION=gitlab-ci-task:1 \
  -v /etc/gitlab-runner:/etc/gitlab-runner \  # 挂载Runner配置目录
  [镜像仓库地址]/ecs-fargate-gitlab-ci-worker:latest

4.4.2 Docker Compose部署

yaml
version: '3.8'
services:
  gitlab-ci-worker:
    image: [镜像仓库地址]/ecs-fargate-gitlab-ci-worker:latest
    container_name: gitlab-ci-worker
    restart: always
    environment:
      - AWS_REGION=us-east-1
      - ECS_CLUSTER=gitlab-ci-cluster
      - ECS_TASK_DEFINITION=gitlab-ci-task:1
      - GITLAB_CI_DEBUG=false
    volumes:
      - gitlab-runner-config:/etc/gitlab-runner
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  gitlab-runner-config:

4.5 自定义配置

4.5.1 资源调整

通过环境变量覆盖默认资源配置：

bash
docker run -d \
  ...
  -e FARGATE_CPU=2 \          # 2 vCPU
  -e FARGATE_MEMORY=4096 \    # 4096 MiB
  ...

4.5.2 日志配置

默认日志输出至stdout，可通过修改Runner配置对接CloudWatch Logs：

toml
[[runners]]
  ...
  [runners.logs]
    output = "cloudwatch"
    cloudwatch_group_name = "/ecs/gitlab-ci-worker"
    cloudwatch_region = "us-east-1"

5. 注意事项

• 确保ECS任务执行角色具有足够权限（ecs:RunTask, ecs:DescribeTasks, logs:PutLogEvents等）
• Fargate任务定义需配置正确的网络模式（awsvpc）及安全组（允许GitLab服务器和Runner通信）
• 镜像标签建议使用具体版本号而非latest，确保部署一致性
• 大规模场景建议配合GitLab Runner Autoscaler实现基于任务队列长度的自动扩缩容