{"id":19806505,"url":"https://github.com/monade/ecs-deploy-cli","last_synced_at":"2025-05-01T07:30:54.736Z","repository":{"id":51242227,"uuid":"349972492","full_name":"monade/ecs-deploy-cli","owner":"monade","description":"A cli and a DSL to make ECS deployments simpler and safer","archived":true,"fork":false,"pushed_at":"2021-11-11T09:42:31.000Z","size":103,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-25T13:04:13.591Z","etag":null,"topics":["aws","ecs","ecs-cluster","ecs-deploy","fargate"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-21T11:04:04.000Z","updated_at":"2025-03-13T09:16:18.000Z","dependencies_parsed_at":"2022-09-10T08:11:47.202Z","dependency_job_id":null,"html_url":"https://github.com/monade/ecs-deploy-cli","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fecs-deploy-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fecs-deploy-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fecs-deploy-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fecs-deploy-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monade","download_url":"https://codeload.github.com/monade/ecs-deploy-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251840144,"owners_count":21652287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","ecs","ecs-cluster","ecs-deploy","fargate"],"created_at":"2024-11-12T09:07:44.228Z","updated_at":"2025-05-01T07:30:54.478Z","avatar_url":"https://github.com/monade.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/monade/ecs-deploy-cli.svg?branch=master)](https://travis-ci.com/monade/ecs-deploy-cli)\n[![Gem Version](https://badge.fury.io/rb/ecs_deploy_cli.svg)](https://badge.fury.io/rb/ecs_deploy_cli)\n\n# ECS Deploy CLI\n\nA CLI + DSL to simplify deployments on AWS [Elastic Container Service](https://aws.amazon.com/it/ecs/).\n\n## Motivation\n\nOnce you've configured your cluster on ECS, running Continous Deployment is not that easy.\n\nA simple deployment requires:\n* Upload the Docker image\n* Update all your tasks\n* Update all services\n* Update eventual Scheduled Tasks manually\n\nWe had some struggle with the official `ecs-cli` approach related with static compose files, requiring a lot of repetition (and potential errors) while defining tasks and envs.\n\nMoreover, you might want some business logic about how your cluster should be configured, like using ENV files, or switch between stages (production / staging), or adjusting container requirements based on external variables.\n\nSo, why not creating a DSL built on top of our favourite language? \u003c3\n\n## Installation\n\nYou can install this gem globally\n```bash\n  $ gem install ecs_deploy_cli\n```\n\nOr add the gem to your Gemfile:\n\n```ruby\n  gem 'ecs_deploy_cli'\n```\n\n## Usage\n\nFirst, define a ECSFile in your project, to design your ECS cluster.\n\n**The cluster and the service must be already there!**\n\nExample of a Rails app on ECS:\n```ruby\naws_region ENV.fetch('AWS_REGION', 'eu-central-1')\n\n# Used to create ARNs\naws_profile_id '123123'\n\n# Defining the cluster name. The block data is for the cluster creation configuration.\ncluster 'yourproject-cluster' do\n  # Default instance type\n  instance_type 't3.small'\n  # A keypair with this name must exist in your account\n  keypair_name 'test'\n\n  # This creates a new VPC in your region. You can also use an existing one.\n  vpc do\n    availability_zones 'eu-central-1a', 'eu-central-1b', 'eu-central-1c'\n  end\nend\n\n# This is used as a template for the next two containers, it will not be used inside a task\ncontainer :base_container do\n  image \"#{ENV['REPO_URL']}:#{ENV['CURRENT_VERSION']}\"\n  load_envs 'envs/base.yml'\n  load_envs 'envs/production.yml'\n  env key: 'MANUAL_ENV', value: '123'\n  secret key: 'SUPER_SECRET_VARIABLE', value: 'superSecretKey' # Taking the secret from AWS System Manager with name \"arn:aws:ssm:__AWS_REGION__:__AWS_PROFILE_ID__:parameter/superSecretKey\"\n  working_directory '/app'\n   # Configuring cloudwatch logs. It automatically creates a log group `/ecs/yourproject`\n  cloudwatch_logs 'yourproject'\nend\n\n# The rails web application\ncontainer :web, extends: :base_container do\n  cpu 512\n  memory limit: 3584, reservation: 3584\n  command 'bundle', 'exec', 'puma', '-C', 'config/puma.rb'\n\n  expose host_port: 0, protocol: 'tcp', container_port: 3000\nend\n\n# The rails job worker\ncontainer :worker, extends: :base_container do\n  cpu 1536\n  memory limit: 3584, reservation: 3584\n  command 'bundle', 'exec', 'shoryuken', '-C', 'config/shoryuken.yml', '-R'\nend\n\n# A container to exec cron jobs\ncontainer :cron, extends: :base_container do\n  command 'rails', 'runner'\n\n  requires_compatibilities ['FARGATE']\nend\n\n# The main task, having two containers\ntask :yourproject do\n  containers :web, :worker\n  cpu 2048\n  memory 3584\n\n  tag 'product', 'yourproject'\nend\n\n# The main service\nservice :'yourproject-service' do\n  task :yourproject\n\n  # You can also link an existing load balancer to a task, for instance:\n  # load_balancer :'yourproject-load-balancer' do\n  #   target_group_arn 'loader-target-group/123abc'\n  #   container_name :web\n  #   container_port 3000\n  # end\nend\n\n# A task for cron jobs\ntask :'yourproject-cron' do\n  containers :cron\n  cpu 256\n  memory 1024\n  # This is automatically converted to the relative ARN\n  execution_role 'ecsTaskExecutionRole'\n  network_mode 'awsvpc'\n\n  tag 'product', 'yourproject'\nend\n\n# Scheduled tasks using Cloudwatch Events / Eventbridge\ncron :scheduled_emails do\n  task :'yourproject-cron' do\n    # Container overrides\n    container :cron do\n      command 'rails', 'cron:exec'\n    end\n  end\n  subnets 'subnet-123123'\n  launch_type 'FARGATE'\n  # Task role override:\n  # task_role 'somerole'\n\n  # Examples:\n  # run_every '2 hours'\n  run_at '0 * * * ? *'\nend\n```\n\nNow you can use the cli commands to control your cluster.\n\n## Use cases\n\nThis DSL can be used both to create new clusters or to control/modify existing ones.\n\nIf you want to create a new cluster with the configuration defined in your ECSFile, you can run the `ecs-cli setup` command (see reference below).\n\nOtherwise, you can just validate that the ECSFile is correctly defined in a safe way.\n\nThere are a couple of commands that help you here:\n* `ecs-deploy validate`: checks if the defined cluster and services exist on your AWS account. It also check for errors in your ECSFile.\n* `ecs-deploy diff` computes the differences between your ECSFile configuration and your existing cluster configuration, printing them in STDOUT.\n\n## CLI commands\n\nYou can find the full command list by running `ecs-deploy help`.\n\n### Validate\n```bash\n  $ ecs-deploy validate\n```\n\nIt checks if your ECSFile is valid and if the cluster/services you've defined exist in your account/region.\n\n### Setup\n```bash\n  $ ecs-deploy setup\n```\n\nIt creates the cluster and the services as defined in your ECSFile\n\n### Deploy\n```bash\n  $ ecs-deploy deploy\n```\nIt deploys (a.k.a. updates) all services and scheduled tasks\n\n### Deploy only services\n```bash\n  $ ecs-deploy deploy-services\n```\nIt runs a deployment just on services\n\n### Deploy only scheduled tasks\n```bash\n  $ ecs-deploy deploy-scheduled-tasks\n```\nIt runs a deployment just on scheduled tasks\n\n### Diff\n```bash\n  $ ecs-deploy diff\n```\nIt prints the differences between your local task_definitions and the ones in your AWS account. Useful to debug what has to be updated using `deploy`.\n\n### Run task\n```bash\n  $ ecs-deploy run-task [task_name] --subnets subnet1,subnet2 --launch-type [FARGATE|EC2] --security-groups sg-123,sg-234\n```\nIt starts a task in the cluster based on a task definition, given a launch type, a security group and/or subnets.\n\n### SSH\n```bash\n  $ ecs-deploy ssh\n```\n\nIt connects with SSH to a cluster container instance. If there are more than one, it will prompt which one you want to connect.\n\nYou can also filter by task (`--task [YOUR-TASK]`) or by service (`--service [YOUR-SERVICE]`)\n\n*IMPORTANT* You have to open port 22 in your cluster security group to your IP.\n\n## API\n\nYou can also use it as an API:\n```ruby\nrequire 'ecs_deploy_cli'\n\nparser = EcsDeployCli::DSL::Parser.load('ECSFile')\n# This will update all your services and tasks to fit the new configuration\nrunner = EcsDeployCli::Runner.new(parser)\nrunner.update_services!\n```\n\n### Known issues\n- The ecsInstanceRole has to be created manually if missing: https://docs.aws.amazon.com/batch/latest/userguide/instance_IAM_role.html\n\n## TODOs\n- Creating the ecsInstanceRole automatically\n- Create scheduled tasks on setup\n- Navigate through logs (or maybe not: https://github.com/jorgebastida/awslogs)\n- Recap cluster status\n- More configuration options\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonade%2Fecs-deploy-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonade%2Fecs-deploy-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonade%2Fecs-deploy-cli/lists"}