ecspresso is a deployment tool for Amazon ECS
Alternatives To Ecspresso
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Waypoint4,69613 days ago84September 22, 2022337mpl-2.0Go
A tool to build, deploy, and release any application on any platform.
Microservices Demo3,346
a day ago108apache-2.0Python
Deployment scripts & config for Sock Shop
Awesome Ecs2,784
11 days ago3
A curated list of awesome ECS guides, development tools, and resources
Ecs Refarch Continuous Deployment828
4 months ago13apache-2.0Shell
ECS Reference Architecture for creating a flexible and scalable deployment pipeline to Amazon ECS using AWS CodePipeline
Ecs Deploy760515 days ago31April 20, 202237otherPython
Powerful CLI tool to simplify Amazon ECS deployments, rollbacks & scaling
4 days ago137October 04, 202212mitGo
ecspresso is a deployment tool for Amazon ECS
Retool Onpremise413
15 days ago27Shell
Deploying Retool On Prem
Hako26571010 months ago115May 31, 20227mitRuby
Deploy Docker container
Ecs Deploy255
14 days ago4apache-2.0Go
ecs-deploy is a continuous deployment platform for AWS ECS. It automates deploys based a simple json/yaml file which can be integrated in your CI/CD
Ecs Canary Blue Green Deployment155
4 years ago1apache-2.0Python
Example code for demonstrating a canary "blue-green" deployment strategy for use with EC2 Container Service (ECS).
Alternatives To Ecspresso
Select To Compare

Alternative Project Comparisons


ecspresso is a deployment tool for Amazon ECS.

(pronounced same as "espresso")


ecspresso handbook (Japanese)

ecspresso Advent Calendar 2020 (Japanese)

Differences of v1 between v2.


Homebrew (macOS and Linux)

$ brew install kayac/tap/ecspresso

asdf (macOS and Linux)

$ asdf plugin add ecspresso
$ asdf install ecspresso 2.0.0
$ asdf global ecspresso 2.0.0

Binary packages


CircleCI Orbs

version: 2.1
  ecspresso: fujiwara/[email protected]
      - checkout
      - ecspresso/install:
          version: v2.0.0 # or latest
          # version-file: .ecspresso-version
      - run:
          command: |
            ecspresso version

version: latest installs different versions of ecspresso for each Orb version.

Orb fujiwara/[email protected] supports version-file: path/to/file installs ecspresso that version written in the file. This version number does not have v prefix, For example, 2.0.0.

GitHub Actions

Action kayac/[email protected] installs an ecspresso binary for Linux(x86_64) into /usr/local/bin. This action runs install only.

    runs-on: ubuntu-latest
      - uses: actions/[email protected]
      - uses: kayac/[email protected]
          version: v2.0.0 # or latest
          # version-file: .ecspresso-version
      - run: |
          ecspresso deploy --config ecspresso.yml

Pass the parameter "latest" to use the latest version of ecspresso.

      - uses: kayac/[email protected]
          version: latest

version: latest installs different versions of ecspresso for each Action version.

GitHub Action kayac/[email protected] supports version-file: path/to/file installs ecspresso that version written in the file. This version number does not have v prefix, For example 2.0.0.


Usage: ecspresso <command>

  -h, --help                      Show context-sensitive help.
      --envfile=ENVFILE,...       environment files
      --debug                     enable debug log
      --ext-str=KEY=VALUE;...     external string values for Jsonnet
      --ext-code=KEY=VALUE;...    external code values for Jsonnet
      --config="ecspresso.yml"    config file

    output AppSpec YAML for CodeDeploy to STDOUT

    delete service

    deploy service

    deregister task definition

    show diff between task definition, service definition with current running
    service and task definition

    execute command on task

  init --service=SERVICE
    create configuration files from existing ECS service

    refresh service. equivalent to deploy --skip-task-definition
    --force-new-deployment --no-update-service

    register task definition

  render <targets>
    render config, service definition or task definition file to STDOUT

    show revisions of task definitions

    rollback service

    run task

    scale service. equivalent to deploy --skip-task-definition

    show status of service

    list tasks that are in a service or having the same family

    verify resources in configurations

    wait until service stable

    show version

For more options for sub-commands, See ecspresso sub-command --help.

Quick Start

ecspresso can easily manage your existing/running ECS service by codes.

Try ecspresso init for your ECS service with option --region, --cluster and --service.

$ ecspresso init --region ap-northeast-1 --cluster default --service myservice --config ecspresso.yml
2019/10/12 01:31:48 myservice/default save service definition to ecs-service-def.json
2019/10/12 01:31:48 myservice/default save task definition to ecs-task-def.json
2019/10/12 01:31:48 myservice/default save config to ecspresso.yml

Let me see the generated files ecspresso.yml, ecs-service-def.json, and ecs-task-def.json.

And then, you already can deploy the service by ecspresso!

$ ecspresso deploy --config ecspresso.yml

Configuration file

A configuration file of ecspresso (YAML or JSON, or Jsonnet format).

region: ap-northeast-1 # or AWS_REGION environment variable
cluster: default
service: myservice
task_definition: taskdef.json
timeout: 5m # default 10m

ecspresso deploy works as below.

  • Register a new task definition from task-definition file (JSON or Jsonnet).
    • Replace {{ env `FOO` `bar` }} syntax in the JSON file to environment variable "FOO".
      • If "FOO" is not defined, replaced by "bar"
    • Replace {{ must_env `FOO` }} syntax in the JSON file to environment variable "FOO".
      • If "FOO" is not defined, abort immediately.
  • Update service tasks by the service_definition file (JSON or Jsonnet).
  • Wait for the service to be stable.

Configuration files and task/service definition files are read by go-config. go-config has template functions env, must_env and json_escape.

Example of deployment

Rolling deployment

$ ecspresso deploy --config ecspresso.yml
2017/11/09 23:20:13 myService/default Starting deploy
Service: myService
Cluster: default
TaskDefinition: myService:3
    PRIMARY myService:3 desired:1 pending:0 running:1
2017/11/09 23:20:13 myService/default Creating a new task definition by myTask.json
2017/11/09 23:20:13 myService/default Registering a new task definition...
2017/11/09 23:20:13 myService/default Task definition is registered myService:4
2017/11/09 23:20:13 myService/default Updating service...
2017/11/09 23:20:13 myService/default Waiting for service stable...(it will take a few minutes)
2017/11/09 23:23:23 myService/default  PRIMARY myService:4 desired:1 pending:0 running:1
2017/11/09 23:23:29 myService/default Service is stable now. Completed!

Blue/Green deployment (with AWS CodeDeploy)

ecspresso deploy can deploy service having CODE_DEPLOY deployment controller. See ecs-service-def.json below.

  "deploymentController": {
    "type": "CODE_DEPLOY"
  // ...

ecspresso doesn't create and modify any resources about CodeDeploy. You must create an application and a deployment group for your ECS service on CodeDeploy in the other way.

ecspresso finds a CodeDeploy deployment setting for the ECS service automatically. But, if you have too many CodeDeploy applications, API calls of that finding process may cause throttling.

In this case, you may specify CodeDeploy application_name and deployment_group_name in a config file.

# ecspresso.yml
  application_name: myapp
  deployment_group_name: mydeployment

ecspresso deploy creates a new deployment for CodeDeploy, and it continues on CodeDeploy.

$ ecspresso deploy --config ecspresso.yml --rollback-events DEPLOYMENT_FAILURE
2019/10/15 22:47:07 myService/default Starting deploy
Service: myService
Cluster: default
TaskDefinition: myService:5
   PRIMARY myService:5 desired:1 pending:0 running:1
2019/10/15 22:47:08 myService/default Creating a new task definition by ecs-task-def.json
2019/10/15 22:47:08 myService/default Registering a new task definition...
2019/10/15 22:47:08 myService/default Task definition is registered myService:6
2019/10/15 22:47:08 myService/default desired count: 1
2019/10/15 22:47:09 myService/default Deployment d-XXXXXXXXX is created on CodeDeploy
2019/10/15 22:47:09 myService/default

CodeDeploy appspec hooks can be defined in a config file. ecspresso creates Resources and version elements in appspec on deploy automatically.

cluster: default
service: test
service_definition: ecs-service-def.json
task_definition: ecs-task-def.json
    - BeforeInstall: "LambdaFunctionToValidateBeforeInstall"
    - AfterInstall: "LambdaFunctionToValidateAfterTraffic"
    - AfterAllowTestTraffic: "LambdaFunctionToValidateAfterTestTrafficStarts"
    - BeforeAllowTraffic: "LambdaFunctionToValidateBeforeAllowingProductionTraffic"
    - AfterAllowTraffic: "LambdaFunctionToValidateAfterAllowingProductionTraffic"

Scale out/in

To change a desired count of the service, specify scale --tasks.

$ ecspresso scale --config ecspresso.yml --tasks 10

scale command is equivalent to deploy --skip-task-definition --no-update-service.

Example of deploy

escpresso can deploy a service by service_definition JSON file and task_definition.

$ ecspresso deploy --config ecspresso.yml
# ecspresso.yml
service_definition: service.json

example of service.json below.

  "role": "ecsServiceRole",
  "desiredCount": 2,
  "loadBalancers": [
      "containerName": "myLoadbalancer",
      "containerPort": 80,
      "targetGroupArn": "arn:aws:elasticloadbalancing:[region]:[account-id]:targetgroup/{target-name}/201ae83c14de522d"

Keys are in the same format as aws ecs describe-services output.

  • deploymentConfiguration
  • launchType
  • loadBalancers
  • networkConfiguration
  • placementConstraint
  • placementStrategy
  • role
  • etc.

Example of run task

$ ecspresso run --config ecspresso.yml --task-def=db-migrate.json

When --task-def is not set, use a task definition included in a service.

Other options for RunTask API are set by service attributes(CapacityProviderStrategy, LaunchType, PlacementConstraints, PlacementStrategy and PlatformVersion).


Version constraint.

required_version in the configuration file is for fixing the version of ecspresso.

required_version: ">= 2.0.0, < 3"

This description allows execution if the version is greater than or equal to 2.0.0 and less than or equal to 3. If this configuration file is read in any other version, execution will fail at that point.

This feature is implemented by go-version.

Suspend and Resume application auto scaling.

ecspresso deploy and scale can suspend and resume application auto scaling.

  • --suspend-auto-scaling sets suspended state true.
  • --resume-auto-scaling sets suspended state false.

When you want to change the suspended state simply, try ecspresso scale --suspend-auto-scaling or ecspresso scale --resume-auto-scaling. That operation will change suspended state only.

Use Jsonnet instead of JSON and YAML.

ecspresso v1.7 or later can use Jsonnet file format for service and task definition.

v2.0 or later can use Jsonnet for configuration file too.

If the file extension is .jsonnet, ecspresso will process Jsonnet first, convert it to JSON, and then load it.

  cluser: 'default',
  service: 'myservice',
  service_definition: 'ecs-service-def.jsonnet',
  task_definition: 'ecs-task-def.jsonnet',

ecspresso includes as a library, we don't need the jsonnet command.

--ext-str and --ext-code flag sets Jsonnet External Variables.

$ ecspresso --ext-str Foo=foo --ext-code "Bar=1+1" ...
  foo: std.extVar('Foo'), // = "foo"
  bar: std.extVar('Bar'), // = 2

Deploy to Fargate

If you want to deploy services to Fargate, task definitions and service definitions require some settings.

For task definitions,

  • requiresCompatibilities (required "FARGATE")
  • networkMode (required "awsvpc")
  • cpu (required)
  • memory (required)
  • executionRoleArn (optional)
  "taskDefinition": {
    "networkMode": "awsvpc",
    "requiresCompatibilities": [
    "cpu": "1024",
    "memory": "2048",
    // ...

For service-definition,

  • launchType (required "FARGATE")
  • networkConfiguration (required "awsvpcConfiguration")
  "launchType": "FARGATE",
  "networkConfiguration": {
    "awsvpcConfiguration": {
      "subnets": [
      "securityGroups": [
      "assignPublicIp": "ENABLED"
  // ...

Fargate Spot support

  1. Set capacityProviders and defaultCapacityProviderStrategy to ECS cluster.
  2. If you hope to migrate existing service to use Fargate Spot, define capacityProviderStrategy into service definition as below. ecspresso deploy --update-service applies the settings to the service.
  "capacityProviderStrategy": [
      "base": 1,
      "capacityProvider": "FARGATE",
      "weight": 1
      "base": 0,
      "capacityProvider": "FARGATE_SPOT",
      "weight": 1
  // ...

ECS Service Connect support

ecspresso supports ECS Service Connect.

You can define serviceConnectConfiguration in service definition files and portMappings attributes in task definition files.

For more details, see also Service Connect parameters

How to check diff and verify service/task definitions before deploy.

ecspresso supports diff and verify subcommands.


Shows differences between local task/service definitions and remote (on ECS) definitions.

$ ecspresso diff
--- arn:aws:ecs:ap-northeast-1:123456789012:service/ecspresso-test/nginx-local
+++ ecs-service-def.json
@@ -38,5 +38,5 @@
   "placementConstraints": [],
   "placementStrategy": [],
-  "platformVersion": "1.3.0"
+  "platformVersion": "LATEST"
--- arn:aws:ecs:ap-northeast-1:123456789012:task-definition/ecspresso-test:202
+++ ecs-task-def.json
@@ -1,6 +1,10 @@
   "containerDefinitions": [
       "cpu": 0,
       "environment": [],
       "essential": true,
-      "image": "nginx:latest",
+      "image": "nginx:alpine",
       "logConfiguration": {
         "logDriver": "awslogs",
         "options": {


Verify resources related with service/task definitions.

For example,

  • An ECS cluster exists.
  • The target groups in service definitions match the container name and port defined in the definitions.
  • A task role and a task execution role exist and can be assumed by
  • Container images exist at the URL defined in task definitions. (Checks only for ECR or DockerHub public images.)
  • Secrets in task definitions exist and be readable.
  • Can create log streams, can put messages to the streams in specified CloudWatch log groups.

ecspresso verify tries to assume the task execution role defined in task definitions to verify these items. If failed to assume the role, it continues to verify with the current sessions.

$ ecspresso verify
2020/12/08 11:43:10 nginx-local/ecspresso-test Starting verify
    --> [OK]
    --> [OK]
      --> [OK]
      --> [OK]
    --> [OK]
  --> [OK]
  --> [OK]
  --> [OK]
2020/12/08 11:43:14 nginx-local/ecspresso-test Verify OK!

Manipulate ECS tasks.

ecspresso can manipulate ECS tasks. Use tasks and exec command.

After v2.0, These operations are provided by ecsta as a library. ecsta CLI can manipulate any ECS tasks (not limited to deployed by ecspresso).

Consider using ecsta as a CLI command.


task command lists tasks run by a service or having the same family to a task definition.

      --id=                       task ID
      --output=table              output format
      --find=false                find a task from tasks list and dump it as JSON
      --stop=false                stop the task
      --force=false               stop the task without confirmation
      --trace=false               trace the task

When --find option is set, you can select a task in a list of tasks and show the task as JSON.

ECSPRESSO_FILTER_COMMAND environment variable can define a command to filter tasks. For example peco, fzf and etc.

$ ECSPRESSO_FILTER_COMMAND=peco ecspresso tasks --find

When --stop option is set, you can select a task in a list of tasks and stop the task.


exec command executes a command on task.

session-manager-plugin is required in PATH.

      --id=                       task ID
      --command=sh                command to execute
      --container=                container name
      --port-forward=false        enable port forward
      --local-port=0              local port number
      --port=0                    remote port number (required for --port-forward)
      --host=                     remote host (required for --port-forward)

If --id is not set, the command shows a list of tasks to select a task to execute.

ECSPRESSO_FILTER_COMMAND environment variable works the same as tasks command.

See also the official document Using Amazon ECS Exec for debugging.

port forwarding

ecspresso exec --port-forward forwards local port to ECS tasks port.

$ ecspresso exec --port-forward --port 80 --local-port 8080

If --id is not set, the command shows a list of tasks to select a task to forward port.

When --local-port is not specified, use the ephemeral port for local port.


ecspresso has some plugins to extend template functions.


The tfstate plugin introduces template functions tfstate and tfstatef.


region: ap-northeast-1
cluster: default
service: test
service_definition: ecs-service-def.json
task_definition: ecs-task-def.json
  - name: tfstate
      url: s3://my-bucket/terraform.tfstate
      # or path: terraform.tfstate    # path to local file


  "networkConfiguration": {
    "awsvpcConfiguration": {
      "subnets": [
        "{{ tfstatef `aws_subnet.private['%s'].id` `az-a` }}"
      "securityGroups": [
        "{{ tfstate `` }}"

{{ tfstate "resource_type.resource_name.attr" }} will expand to an attribute value of the resource in tfstate.

{{ tfstatef "resource_type.resource_name['%s'].attr" "index" }} is similar to {{ tfstatef "resource_type.resource_name['index'].attr" }}. This function is useful to build a resource address with environment variables.

{{ tfstatef `aws_subnet.ecs['%s'].id` (must_env `SERVICE`) }}

Multiple tfstate support

func_prefix adds a prefix to template function names for each plugin configuration.

# ecspresso.yml
   - name: tfstate
       url: s3://tfstate/first.tfstate
     func_prefix: first_
   - name: tfstate
       url: s3://tfstate/second.tfstate
     func_prefix: second_

So in templates, functions are called with prefixes.

  "{{ first_tfstate `aws_s3_bucket.main.arn` }}",
  "{{ second_tfstate `aws_s3_bucket.main.arn` }}"


The cloudformation plugin introduces template functions cfn_output and cfn_export.

An example of CloudFormation stack template defines Outputs and Exports.

# StackName: ECS-ecspresso
    Value: !Ref PublicSubnetAz1
    Value: !Ref PublicSubnetAz2
    Value: !Ref EcsSecurityGroup
      Name: !Sub ${AWS::StackName}-EcsSecurityGroupId

Load cloudformation plugin in a config file.


# ...
  - name: cloudformation

cfn_output StackName OutputKey lookups OutputValue of OutputKey in the StackName. cfn_export ExportName lookups exported value by name.


  "networkConfiguration": {
    "awsvpcConfiguration": {
      "subnets": [
        "{{ cfn_output `ECS-ecspresso` `SubnetAz1` }}",
        "{{ cfn_output `ECS-ecspresso` `SubnetAz2` }}"
      "securityGroups": [
        "{{ cfn_export `ECS-ecspresso-EcsSecurityGroupId` }}"


The ssm plugin introduces a template function, ssm to read parameters from AWS Systems Manager(SSM) Parameter Store.

  - name: ssm

Suppose ssm parameter store has the following parameters:

  • name: '/path/to/string', type: String, value: "ImString"
  • name: '/path/to/stringlist', type: StringList, value: "ImStringList0,ImStringList1"
  • name: '/path/to/securestring', type: SecureString, value: "ImSecureString"

Then this template,

  "string": "{{ ssm `/path/to/string` }}",
  "stringlist": "{{ ssm `/path/to/stringlist` 1 }}",  *1
  "securestring": "{{ ssm `/path/to/securestring` }}"

will be rendered into this.

  "string": "ImString",
  "stringlist": "ImStringList1",
  "securestring": "ImSecureStriing"





Popular Aws Ecs Projects
Popular Deployment Projects
Popular Cloud Computing Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.