ecspresso

ecspresso v2 introduces several enhancements over v1:

• CodeDeploy configuration: You can now specify the CodeDeploy application name and deployment group name directly in your configuration file.
• CodeDeploy UX: A progress bar is shown during CodeDeploy deployments.
• Verification: The verify command now verifies the container image platform.
• Terraform state: Supports multiple tfstate files using a prefix.
• Plugins: Added support for the SSM parameter store plugin.
• ECS Service Connect: Full support for ECS Service Connect.

If you need to pull data from multiple different Terraform state files, use the func_prefix option in the plugin configuration. This adds a unique prefix to the template functions for that specific plugin instance.

Example Setup

In ecspresso.yml, assign a func_prefix to each plugin entry.

Usage

In your templates, call the functions using the prefix: {{ prefix_tfstate ... }}.

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

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

ECS Express mode allows deploying services with a single definition file instead of separate task and service definitions.

Configuration: Use express_definition in your ecspresso.yml instead of task_definition and service_definition.

Supported Commands: init --express, deploy, diff, render expressdef, delete, status, rollback (partial), verify, exec, refresh, tasks, wait.

Unsupported Commands: scale, run, revisions, register, deregister, appspec.

Migration: Use ecspresso init --no-express to import an existing Express service as a standard (non-express) service.

# ecspresso.yml
region: ap-northeast-1
cluster: ecspresso
service: myservice
express_definition: ecs-express-def.json

ecspresso supports template syntax in JSON, YAML, or Jsonnet files to inject environment variables.

• {{ env 'VAR' 'default' }}: Replaces with the value of environment variable VAR. If VAR is not set, it uses 'default'.
• {{ must_env 'VAR' }}: Replaces with the value of environment variable VAR. If VAR is not set, the deployment aborts immediately.

Example: Updating an image tag In ecs-task-def.json:

{
  "image": "nginx:{{ must_env `IMAGE_TAG` }}"
}

Deploy with the variable:

IMAGE_TAG=stable ecspresso deploy --config ecspresso.yml

ecspresso supports Jsonnet for service and task definitions (since v1.7) and configuration files (since v2.0). If a file has the .jsonnet extension, ecspresso processes it as Jsonnet, converts it to JSON, and then loads it with evaluation template syntax.

To pass variables to Jsonnet files, use the --ext-str and --ext-code flags to set Jsonnet External Variables.

$ ecspresso --ext-str Foo=foo --ext-code "Bar=1+1" ...

{
  foo: std.extVar('Foo'), // = "foo"
  bar: std.extVar('Bar'), // = 2
}

Manage the lifecycle of your ECS services using the following commands. It is highly recommended to use --dry-run before executing destructive operations.

Deployment

• Preview changes: ecspresso deploy --config <config_file> --dry-run
• Deploy service: ecspresso deploy --config <config_file>
• Deploy and wait: Wait until the deployment reaches a stable state. ecspresso deploy --config <config_file> --wait-until stable

Rollback

• Rollback to previous task definition: ecspresso rollback --config <config_file>
• Rollback preview: ecspresso rollback --config <config_file> --dry-run

Scaling

• Scale tasks: Set a specific number of tasks for the service. ecspresso scale --config <config_file> --tasks <number>

# Deploy and wait until stable
ecspresso deploy --config ecspresso.yml --wait-until stable

If you need to see the final, resolved configuration after template variables and functions have been expanded, use the render command.

• Render task definition: ecspresso render --config <config_file> taskdef
• Render service definition: ecspresso render --config <config_file> servicedef

# Render resolved task definition
ecspresso render --config ecspresso.yml taskdef

Use these commands to execute one-off tasks or inspect currently running tasks.

• Run a one-off task: Runs a standalone task using the service's task definition. ecspresso run --config <config_file>
• Run and watch logs: Run a task and stream logs for a specific container. ecspresso run --config <config_file> --watch-container <container_name>
• List running tasks: Retrieve a list of running tasks in JSON format. ecspresso tasks --config <config_file> --output json

# Run and watch logs
ecspresso run --config ecspresso.yml --watch-container app

To migrate an existing service to use Fargate Spot, first ensure capacityProviders and defaultCapacityProviderStrategy are set for the ECS cluster. Then, define a capacityProviderStrategy in your service definition and apply it using ecspresso deploy --update-service.

{
  "capacityProviderStrategy": [
    {
      "base": 1,
      "capacityProvider": "FARGATE",
      "weight": 1
    },
    {
      "base": 0,
      "capacityProvider": "FARGATE_SPOT",
      "weight": 1
    }
  ]
}