ecspresso: running Amazon ECS services from files you can review

ECS definitions as files, generated from what you already run

ecspresso is a deployment tool for Amazon ECS, and the core of it is simple to state. It lets you manage ECS services and task definitions as code in JSON, YAML or Jsonnet files, which enables version control and infrastructure as code practices. The entry point is `ecspresso init`, which generates configuration files from existing ECS services, and the README's framing is that this makes it easy to start managing your infrastructure. That starting point is the interesting design decision, because the usual way to adopt a configuration tool is to write the configuration by hand, which is how a project ends up with a file nobody trusts. Generating the file from the running service means the first version of the configuration is a description of reality rather than a guess, and the review that follows is a review of a diff. The tool is written in Go, the module is `github.com/kayac/ecspresso/v2`, and the default branch is `v2`, with a document in `docs/` describing the differences between v1 and v2 for anyone still on the older line.

Definition files that can read from the rest of your infrastructure

The definition files support template syntax and Jsonnet native functions, and the point of that support is that a task definition is full of values that live elsewhere. The README lists what can be embedded, and it is a specific list: environment variables, Terraform state values, SSM parameters, and Secrets Manager ARNs. So a task definition can name a secret without containing the secret, or read a subnet or an account id out of Terraform state instead of hard coding it, and the resolved value appears only in the request that ECS receives. The Jsonnet route is the more expressive of the two formats, and the repository carries a `jsonnet.go` and a `jsonnet_test.go` with the Google Jsonnet library in the dependencies, alongside `goccy/go-yaml` for the YAML files and `itchyny/gojq` for JSON handling. The plugin system is what makes the external lookups work, and the plugins listed in the README are Terraform state, CloudFormation, SSM Parameter Store, Secrets Manager, and external commands, the last being the escape hatch for a value that comes from somewhere the tool has never heard of.

Diff, verify, deploy, and a way back

The deployment surface is broader than a single deploy command, and the safety-oriented parts are the most valuable. Multiple deployment strategies are supported, including rolling updates and blue/green deployments with both the ECS native and the CodeDeploy controllers, and there is a whole section on waiting for a deployment to finish, plus one on early success criteria for a rolling deployment, which is the feature that stops a pipeline from waiting for every single task to be healthy before it moves on. Before deploying you can preview changes with `diff` and validate configurations with `verify`, and if something goes wrong, `rollback` reverts to a previous state. The two commands that make this usable in a pull request workflow are `diff` and `verify`, because they are the ones you can run without touching production, and the README has a dedicated section on checking diff and verify for services and task definitions before deploying. There is also a section on manipulating ECS tasks for running one-off work, and one on managing Application Auto Scaling.

Getting it onto a machine, or into CI

The distribution options are unusually thorough for a small Go tool, and they cover every CI system worth naming. On a laptop there is a Homebrew tap with `brew install kayac/tap/ecspresso`, an asdf plugin, the aqua CLI version manager, and plain binary downloads from the releases page. For containers there is an image on GitHub Container Registry, based on the distroless static Debian 12 base and built for both linux/amd64 and linux/arm64, and the run invocation in the README shows the shape, with the AWS credentials directory mounted read only and the working directory mounted so the configuration file is available.

$ docker pull ghcr.io/kayac/ecspresso:v2.7.0

$ docker run --rm \
    -v ~/.aws:/root/.aws:ro \
    -v $(pwd):/work \
    -w /work \
    ghcr.io/kayac/ecspresso:v2.7.0 deploy --config ecspresso.yml

For CI there is a CircleCI Orb and a GitHub Action. The action `kayac/ecspresso@v2` installs the binary for Linux x86_64 into `/usr/local/bin`, and when an `args` input is provided it runs ecspresso with those arguments after installation, with the configuration file selected through the `ECSPRESSO_CONFIG` environment variable. Both the Orb and the Action support pinning a specific version or reading one from a version file, and both carry the same warning about `version: latest`, which is not recommended because it may cause unexpected behaviour when a new version of ecspresso is released. That warning is a good summary of how to treat a deployment tool in an automated pipeline.

A long list of AWS features, and the ones that change your options

The notes section of the README is a long index of what the tool can do inside ECS, and several entries are worth singling out because they decide whether the tool fits your setup. There is support for deploying to Fargate and for Fargate Spot, ECS Service Connect, EBS volume support, S3 Files volume support, and VPC Lattice support, alongside high resolution CloudWatch metrics. There is support for ECS Express mode for simplified deployments, and a version constraint section that explains the compatibility rules. Each of those is a small feature individually, but together they are the difference between a tool that supports a platform and a tool that lags behind it. The repository also carries an LLM agent integration section and an `AGENTS.md` at the root, with the `skillsmith` library in the dependencies, which is a hint that the project is being prepared for use by coding agents as well as by people. The Go dependency list is a good map of the AWS surface covered: the ECS, ECR, CodeDeploy, Application Auto Scaling, CloudWatch Logs, Elastic Load Balancing v2, IAM, Lambda, S3, Secrets Manager, Service Discovery, SSM, STS and VPC Lattice services, all from the v2 SDK.

Documentation, language and the shape of the project

The documentation is extensive and mostly Japanese, which is the biggest barrier for an English speaking reader and the most important thing to plan around. The README links a document on the differences between v1 and v2, the ecspresso Advent Calendar 2020, the ecspresso handbook published as a book on Zenn, and a command reference inside that handbook. The handbook is the real manual, and it is in Japanese. The README itself is a good index in English, and the project is also documented for agents, with the `AGENTS.md` file, a `docs/` directory and a `docs_embed.go` that suggests documentation is embedded in the binary. The code layout is a flat package with one file per command, so `deploy.go`, `diff.go`, `init.go`, `create.go`, `delete.go`, `register.go`, `deregister.go`, `refresh.go`, `config.go`, `jsonnet.go`, `plugin.go` and `express.go` sit next to each other with their test files, and the `cmd/` directory holds the entry point. The Makefile builds with the tags `no_gcs,no_azurerm`, which excludes the Google Cloud and Azure Resource Manager backends, and the test target runs `go test -race ./...`, so a fork inherits a race-enabled test suite and a goreleaser based packaging pipeline.

Editorial conclusion

Adopt ecspresso if you run Amazon ECS and want your service and task definitions under version control, reviewed like code, with the values your infrastructure already holds pulled in at deploy time. Do not adopt it for Kubernetes or for a multi cloud estate, since it is an AWS tool and its value comes from the AWS specific integrations rather than from being a generic deployer. Before you adopt it, run `ecspresso init` against a service you already have and read the generated file, because that file becomes the contract you will be reviewing later, and pin the version in CI rather than using latest, which the README warns can bring unexpected behaviour when a new release lands. The licence is MIT, the current line is v2 with 2.8.7 released on 2026-09-27, and the last push was on 2026-10-10.

Frequently asked questions

Official sources

1. Issues
2. kayac/ecspresso on GitHub
3. License: MIT
4. README
5. Releases