heyjobs/ecs-deploy

ecs-deploy Docker镜像文档

镜像概述

ecs-deploy是一个简化Amazon Elastic Container Service (ECS)蓝绿部署流程的脚本工具。它通过操作ECS的任务定义(Task Definition)和服务(Service)实体，实现自动蓝绿部署，确保应用更新过程中无服务中断。该工具支持多种配置方式，可灵活集成到CI/CD流程中。

核心功能与特性

• 蓝绿部署自动化：无需手动操作AWS控制台，通过命令行触发ECS服务的蓝绿部署
• 灵活的AWS凭证管理：支持通过命令行参数、环境变量或IAM实例角色提供AWS凭证
• 任务定义管理：自动拉取、修改并注册新版本的任务定义
• 镜像标签控制：支持通过参数、环境变量或标签覆盖更新容器镜像
• 多容器任务支持：可同时更新任务定义中的多个容器镜像标签
• 部署参数配置：自定义期望任务数、健康检查阈值、部署超时时间等
• 部署验证：自动监控服务部署状态，确保新任务正常运行

使用场景与适用范围

• 持续集成/部署流程：集成到CI/CD管道中，实现代码提交后的自动部署
• 多环境部署：适用于开发、测试、生产等不同环境的ECS服务部署
• 零停机更新：需要保持服务可用性的生产环境应用更新
• 多容器应用：包含多个关联容器的微服务应用部署
• 任务定义版本管理：需要保留或清理历史任务定义版本的场景

依赖要求

• AWS CLI：用于与AWS ECS服务交互
• jq：命令行JSON处理器，用于解析和修改任务定义

使用方法与配置说明

命令参数说明

必选参数（至少提供以下之一）

• -n | --service-name：要部署的服务名称
• -d | --task-definition：要部署的任务定义名称

必选AWS配置参数

• -k | --aws-access-key：AWS访问密钥ID（也可通过环境变量AWS_ACCESS_KEY_ID设置）
• -s | --aws-secret-key：AWS密钥（也可通过环境变量AWS_SECRET_ACCESS_KEY设置）
• -r | --region：AWS区域名称（也可通过环境变量AWS_DEFAULT_REGION设置）
• -p | --profile：AWS配置文件名称（使用此参数时仍需提供访问密钥、密钥和区域）
• -c | --cluster：ECS集群名称
• -i | --image：Docker镜像名称，格式：[domain][:port][/repo][/][image][:tag]
• --aws-instance-profile：使用当前实例关联的IAM角色

可选参数

• -D | --desired-count：服务中要保持运行的任务数量
• -m | --min：部署期间运行任务的最小健康百分比（minimumHealthyPercent）
• -M | --max：部署期间运行任务的最大百分比（maximumPercent）
• -t | --timeout：部署超时时间（默认90秒）
• -e | --tag-env-var：从环境变量获取镜像标签（覆盖-i中的标签）
• -to | --tag-only：为任务中所有镜像应用新标签（覆盖-i中的标签）
• -a | --aws-assume-role：要承担的AWS角色ARN
• --mfa：角色承担的MFA ARN/序列号
• --max-definitions：保留的任务定义修订版数量（超出将注销最旧版本）
• --enable-rollback：超时未运行时回滚任务定义
• --force-new-deployment：强制新部署（默认false）
• --use-latest-task-def：使用最新创建的任务定义作为基础，而非最后使用的版本
• --skip-deployments-check：跳过部署检查（适用于排水时间长的服务）
• --run-task：立即运行创建的任务（使用此参数时不需要服务名称）
• --run-task-overrides：任务运行覆盖配置（仅与--run-task一起使用，JSON格式）
• -v | --verbose：详细输出
• --version：显示版本信息

部署示例

1. 简单服务部署（使用环境变量配置AWS凭证）

bash
ecs-deploy -c production1 -n doorman-service -i docker.repo.com/doorman:latest

2. 完整参数部署

bash
ecs-deploy -k ABC123 -s SECRETKEY -r us-east-1 -c production1 -n doorman-service -i docker.repo.com/doorman -t 240 -e CI_TIMESTAMP -v

3. 更新任务定义镜像

bash
ecs-deploy -d open-door-task -i docker.repo.com/doorman:17

4. 使用AWS配置文件

bash
ecs-deploy -p PROFILE -c production1 -n doorman-service -i docker.repo.com/doorman -t 240 -e CI_TIMESTAMP -v

5. 更新多容器任务的标签

bash
ecs-deploy -c staging -n core-service -to 0.1.899 -i ignore

安装步骤

1. 安装并配置AWS CLI：

   bash
   # 参考AWS官方文档安装：http://docs.aws.amazon.com/cli/latest/userguide/tutorial-ec2-ubuntu.html#install-cli
   

2. 安装jq：

   bash
   # 参考jq安装文档：https://github.com/stedolan/jq/wiki/Installation
   

3. 安装ecs-deploy：

   bash
   curl https://raw.githubusercontent.com/silinternational/ecs-deploy/master/ecs-deploy | sudo tee /usr/bin/ecs-deploy
   sudo chmod +x /usr/bin/ecs-deploy
   

工作原理

ecs-deploy通过以下步骤实现蓝绿部署：

1. 拉取任务定义：获取当前服务使用的任务定义（或最新创建的任务定义，如使用--use-latest-task-def）
2. 修改任务定义：根据提供的镜像参数更新容器镜像标签
3. 注册新版本：将修改后的任务定义注册为新版本
4. 更新服务：将服务配置更新为使用新版本的任务定义
5. 监控部署：查询AWS API，确认服务成功创建并运行新任务

注意：ECS服务在更新任务定义时会自动执行蓝绿部署，先启动新任务并确认健康状态，再终止旧任务，确保服务不中断。

使用环境变量指定镜像标签

通过-e参数可从环境变量获取镜像标签，适用于CI/CD环境中动态生成标签的场景。例如，在Codeship环境中使用CI_TIMESTAMP变量作为标签：

bash
ecs-deploy -c production1 -n doorman-api -i my.private.repo/doorman-api -e CI_TIMESTAMP

AWS IAM策略配置

以下是ecs-deploy所需的IAM策略示例：

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DeregisterTaskDefinition",
        "ecs:DescribeServices",
        "ecs:DescribeTaskDefinition",
        "ecs:DescribeTasks",
        "ecs:ListTasks",
        "ecs:ListTaskDefinitions",
        "ecs:RegisterTaskDefinition",
        "ecs:StartTask",
        "ecs:StopTask",
        "ecs:UpdateService",
        "iam:PassRole"
      ],
      "Resource": "*"
    }
  ]
}

故障排除

• AWS凭证错误：若未正确配置AWS凭证，会出现类似错误：You must specify a region. You can also configure your region by running "aws configure".，需检查AWS CLI配置或环境变量设置。
• 镜像标签默认值：若未通过-i、-e或-to指定标签，默认使用latest标签。

测试

ecs-deploy使用https://github.com/sstephenson/bats%E8%BF%9B%E8%A1%8C%E8%87%AA%E5%8A%A8%E5%8C%96%E6%B5%8B%E8%AF%95%EF%BC%8C%E4%B8%BB%E8%A6%81%E6%B5%8B%E8%AF%95%E6%9C%AC%E5%9C%B0%E6%95%B0%E6%8D%AE%E8%A7%A3%E6%9E%90%E5%92%8C%E5%A4%84%E7%90%86%E9%80%BB%E8%BE%91%E3%80%82%E6%96%B0%E5%8A%9F%E8%83%BD%E5%92%8CPR%E5%BA%94%E5%B0%BD%E5%8F%AF%E8%83%BD%E6%8F%90%E4%BE%9B%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E3%80%82