ecspresso is a deployment tool for Amazon ECS.
(pronounced the same as "espresso" ☕)
ecspresso allows you to manage ECS services and task definitions as code in JSON, YAML, or Jsonnet files, enabling version control and infrastructure as code practices. You can generate configuration files from existing ECS services using ecspresso init, making it easy to start managing your infrastructure.
Definition files support template syntax and Jsonnet native functions to embed environment variables, Terraform state values, SSM parameters, and Secrets Manager ARNs. ecspresso supports multiple deployment strategies including rolling updates and Blue/Green deployments with both ECS native and CodeDeploy controllers. Before deploying, you can preview changes with diff and validate configurations with verify. If something goes wrong, rollback helps you safely revert to a previous state.
ecspresso also supports ECS Express mode for simplified deployments and provides a plugin system for extending functionality.
- Documents
- Install
- Usage
- Quick Start
- Configuration file
- Template syntax
- Deployment
- Scale out/in
- Rollback
- Run task
- Notes
- Version constraint
- Manage Application Auto Scaling
- Jsonnet support
- Deploy to Fargate
- Fargate Spot support
- ECS Service Connect support
- EBS Volume support
- S3 Files volume support
- VPC Lattice support
- ECS Gateway support
- High resolution CloudWatch metrics
- Pause lifecycle hooks
- ECS Express mode support
- Diff and Verify
- Manipulate ECS tasks
- Show documentation
- LLM agent integration
- Plugins
- LICENSE
- Differences between v2 and v3.
- Differences between v1 and v2.
- ecspresso Advent Calendar 2020 (Japanese)
- ecspresso handbook (Japanese)
- Command Reference (Japanese)
$ brew install kayac/tap/ecspresso$ asdf plugin add ecspresso
# or
$ asdf plugin add ecspresso https://github.com/kayac/asdf-ecspresso.git
$ asdf install ecspresso 3.0.0
$ asdf set -u ecspresso 3.0.0aqua is a CLI version manager.
$ aqua g -i kayac/ecspressomise can install ecspresso via its packslip backend, which verifies the signed release manifest before installing.
$ mise use packslip:github.com/kayac/ecspressoThe packslip backend can install only releases that ship a packslip.sigstore.json manifest (v3.0.0 and later). v2 releases are available via aqua (mise use aqua:kayac/ecspresso@2.8.9).
The agent skill for the installed version can be linked into a project with mise skills sync.
Releases since v3.0.0 include packslip.sigstore.json, a packslip manifest signed by the release workflow. It lists the digests of the archives and can be checked with packslip verify.
Docker images are available on GitHub Container Registry.
$ docker pull ghcr.io/kayac/ecspresso:v3.0.0The image is based on gcr.io/distroless/static-debian13 and supports both linux/amd64 and linux/arm64 architectures.
$ docker run --rm \
-v ~/.aws:/root/.aws:ro \
-v $(pwd):/work \
-w /work \
ghcr.io/kayac/ecspresso:v3.0.0 deploy --config ecspresso.ymlhttps://circleci.com/orbs/registry/orb/fujiwara/ecspresso
version: 2.1
orbs:
ecspresso: fujiwara/ecspresso@2.0.6
jobs:
install:
steps:
- checkout
- ecspresso/install:
version: v3.0.0 # or latest
# version-file: .ecspresso-version
os: linux # or windows or darwin
arch: amd64 # or arm64
- run:
command: |
ecspresso versionversion: latest installs different versions of ecspresso for each Orb version.
- fujiwara/ecspresso@0.0.15
- The latest release version (v2 and later)
- fujiwara/ecspresso@1.0.0
- The latest version of v1.x
- fujiwara/ecspresso@2.0.3
- The most recently published release (v2 and later)
- fujiwara/ecspresso@2.0.6
- The release marked as Latest on GitHub (e.g. it stays on v3.x after a newer v2.x release is published)
Note: version: latest is not recommended as it may cause unexpected behavior when a new version of ecspresso is released.
Orb fujiwara/ecspresso@2.0.2 supports version-file: path/to/file, which installs the ecspresso version specified in the file. This version number does not have a v prefix, For example, 2.0.0.
The GitHub Action has moved to kayac/ecspresso-action. See its README for inputs and details.
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: kayac/ecspresso-action@v3
with:
version: v3.0.0 # or latest
# version-file: .ecspresso-version
- run: |
ecspresso deploy --config ecspresso.ymlkayac/ecspresso@v3 is a deprecated wrapper that calls kayac/ecspresso-action and prints a deprecation warning. Replace uses: kayac/ecspresso@v2 with uses: kayac/ecspresso-action@v3. kayac/ecspresso@v2 keeps working as before.
Usage: ecspresso <command>
Flags:
-h, --help Show context-sensitive help.
--envfile=ENVFILE,... environment files ($ECSPRESSO_ENVFILE)
--debug enable debug log ($ECSPRESSO_DEBUG)
--ext-str=KEY=VALUE;... external string values for Jsonnet ($ECSPRESSO_EXT_STR)
--ext-code=KEY=VALUE;... external code values for Jsonnet ($ECSPRESSO_EXT_CODE)
--config="ecspresso.yml" config file ($ECSPRESSO_CONFIG)
--assume-role-arn="" the ARN of the role to assume ($ECSPRESSO_ASSUME_ROLE_ARN)
--timeout=TIMEOUT timeout. Override in a configuration file ($ECSPRESSO_TIMEOUT).
--filter-command=STRING filter command ($ECSPRESSO_FILTER_COMMAND)
--[no-]color enable colorized output ($ECSPRESSO_COLOR)
--log-format="text" log format (text, json) ($ECSPRESSO_LOG_FORMAT)
Commands:
appspec
output AppSpec YAML for CodeDeploy to STDOUT
delete
delete service
deploy
deploy service
deregister
deregister task definition
diff
show diff between task definition, service definition with current running
service and task definition
docs
show documentation for ecspresso
exec
execute command on task
init --service=SERVICE
create configuration files from existing ECS service
refresh
refresh service. equivalent to deploy --skip-task-definition
--force-new-deployment --no-update-service
register
register task definition
render <targets>
render config, service definition or task definition file to STDOUT
revisions
show revisions of task definitions
rollback
rollback service
run
run task
scale
scale service. equivalent to deploy --skip-task-definition
--no-update-service
status
show status of service
tasks
list tasks that are in a service or having the same family
verify
verify resources in configurations
wait
wait for the service deployment to complete
version
show versionFor more options for sub-commands, See ecspresso sub-command --help.
--log-format option controls the log output format. The default is text.
text format outputs human-readable logs. Attributes from slog.With (e.g. service/cluster) appear before the message, and per-call attributes appear after the message in [key:value] format.
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] deployment created on CodeDeploy [deployment_id:d-XXXXXXXXX] [url:https://...]
json format outputs structured JSON logs suitable for machine parsing. All attributes are output as individual JSON fields.
{"time":"2024-01-01T00:00:00.000+09:00","level":"INFO","msg":"deployment created on CodeDeploy","cluster":"default","service":"myService","deployment_id":"d-XXXXXXXXX","url":"https://..."}ecspresso allows you to easily manage your existing/running ECS services by code.
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
2024-01-01T00:00:00.000+09:00 [INFO] [myservice/default] saving service definition [path:ecs-service-def.json]
2024-01-01T00:00:00.000+09:00 [INFO] [myservice/default] saving task definition [path:ecs-task-def.json]
2024-01-01T00:00:00.000+09:00 [INFO] [myservice/default] saving config [path:ecspresso.yml]Review the generated files: ecspresso.yml, ecs-service-def.json, and ecs-task-def.json.
Now you can deploy the service using ecspresso!
$ ecspresso deploy --config ecspresso.ymlecspresso can read service and task definition files as a template. A typical use case is to replace the image's tag in the task definition file.
Modify ecs-task-def.json as below.
- "image": "nginx:latest",
+ "image": "nginx:{{ must_env `IMAGE_TAG` }}",Then, deploy the service with environment variable IMAGE_TAG.
$ IMAGE_TAG=stable ecspresso deploy --config ecspresso.ymlFor more information, refer to the Configuration file and Template syntax sections.
A configuration file for ecspresso (YAML, 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
ignore:
tags:
- ecspresso:ignore # ignore tags of service and task definitionecspresso deploy works as below.
- Register a new task definition from
task-definitionfile (JSON or Jsonnet).- Replace
{{ env `FOO` `bar` }}syntax in the JSON file with environment variable "FOO".- If "FOO" is not defined, replaced by "bar"
- Replace
{{ must_env `FOO` }}syntax in the JSON file wth environment variable "FOO".- If "FOO" is not defined, abort immediately.
- Replace
- Update service tasks by the
service_definitionfile (JSON or Jsonnet). - Wait for the service deployment to complete.
Configuration files and task/service definition files are read by go-config which provides template functions env, must_env and json_escape.
Plugin-provided functions (tfstate, cfn / cloudformation, ssm, secretsmanager) can be used in top-level configuration fields such as cluster, service, and region, not only inside task / service definitions. This is typically useful when ECS clusters are managed by Terraform:
region: ap-northeast-1
cluster: "{{ tfstate `aws_ecs_cluster.main.name` }}"
service: myservice
service_definition: ecs-service-def.json
task_definition: ecs-task-def.json
plugins:
- name: tfstate
config:
path: terraform.tfstatelocal tfstate = std.native('tfstate');
{
region: 'ap-northeast-1',
cluster: tfstate('aws_ecs_cluster.main.name'),
service: 'myservice',
service_definition: 'ecs-service-def.jsonnet',
task_definition: 'ecs-task-def.jsonnet',
plugins: [
{ name: 'tfstate', config: { path: 'terraform.tfstate' } },
],
}To make this work, ecspresso loads the configuration file in two passes:
- Extract only the
plugins(andregion) section, then run plugin setup. - Re-read the whole file with plugin-provided template / Jsonnet functions registered.
Notes and limitations:
- The
pluginsblock itself cannot reference plugin functions — that would be a chicken-and-egg loop. Useenv/must_envthere instead. - If
regionitself is resolved from a plugin function that needs AWS access (e.g.ssm,cfn), the AWS client for plugin setup falls back to theAWS_REGIONenvironment variable.
Important
Breaking change in v3 (not compatible with v2): the YAML configuration file must be valid YAML on its own — i.e. before template rendering. In particular, template literals that begin a scalar must be quoted, because YAML parses an unquoted leading { as a flow-mapping opener.
v2 template-rendered the whole file first and parsed YAML afterwards, which silently tolerated unquoted {{ ... }} at the start of a scalar. v3 reads the raw file with a YAML parser in pass 1 to extract plugins, so this no longer works.
# NG in v3 (worked in v2): YAML treats leading `{` as a flow-mapping opener
region: {{ must_env `AWS_REGION` }}
# OK: quote the scalar
region: "{{ must_env `AWS_REGION` }}"JSON and Jsonnet configurations are unaffected. Existing v2 YAML configs that already quote their template literals (the common case) continue to work without changes.
ecspresso uses the text/template standard package in Go to render template files, and parses them as YAML or JSON.
When using Jsonnet, ecspresso first renders the Jsonnet files and then parses them as text/template. As a result, template functions can only render string values using "{{ ... }}", since the template function syntax {{ }} conflicts with Jsonnet syntax. To render non-string values, consider using Jsonnet functions instead.
By default, ecspresso provides the following as template functions.
"{{ env `NAME` `default value` }}"This replaces the placeholder with the value of the environment variable NAME. If not set, it defaults to "default value".
"{{ must_env `NAME` }}"This replaces the placeholder with the value of environment variable NAME. If not set, ecspresso will panic and stop forcefully.
Defining critical values with must_env helps prevent unintended deployments by ensuring these values are set before execution.
"{{ must_env `JSON_VALUE` | json_escape }}"This escapes values as JSON strings, which is useful for embedding values as strings that require escaping, such as quotes.
ecspresso also adds some template functions via plugins. See the Plugins section.
ecspresso deploy performs rolling deployment by default.
$ ecspresso deploy --config ecspresso.yml
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] Starting deploy
Service: myService
Cluster: default
TaskDefinition: myService:3
Deployments:
PRIMARY myService:3 desired:1 pending:0 running:1
Events:
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] creating a new task definition [path:myTask.json]
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] registering a new task definition
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] task definition is registered [task_definition:myService:4]
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] updating service
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] Waiting for service deployed...(it will take a few minutes)
2024-01-01T00:00:03.000+09:00 [INFO] [myService/default] waiting for service deployment [deployment:AbCdEfGhIjKlMnOpQrStU]
2024-01-01T00:03:10.000+09:00 [INFO] [myService/default] PRIMARY myService:4 desired:1 pending:0 running:1
2024-01-01T00:03:16.000+09:00 [INFO] [myService/default] service deployment status [status:SUCCESSFUL]
2024-01-01T00:03:16.000+09:00 [INFO] [myService/default] service deployment completeddeploy commands has many options to customize the deployment behavior. See ecspresso deploy --help for more details.
--dry-run dry run
--tasks=-1 desired count of tasks
--skip-task-definition skip register a new task definition
--revision=0 revision of the task definition to run when --skip-task-definition
--force-new-deployment force a new deployment of the service
--[no-]wait wait for the deployment to complete (see --wait-until)
--wait-until="deployed" Choose whether to wait for service stable, the deployment finishes, or a
lifecycle hook pauses. For ECS deployment controller:
"(stable|deployed|paused)", or "ecs:*", this accepts a deployment
lifecycle stage (e.g., "ecs:BAKE_TIME"); For CodeDeploy deployment
controller: "codedeploy:*", this accepts CodeDeploy lifecycle event (e.g.,
"codedeploy:AfterAllowTraffic")
--suspend-auto-scaling suspend application auto-scaling attached with the ECS service
--resume-auto-scaling resume application auto-scaling attached with the ECS service
--auto-scaling-min=AUTO-SCALING-MIN set minimum capacity of application auto-scaling attached with the ECS service
--auto-scaling-max=AUTO-SCALING-MAX set maximum capacity of application auto-scaling attached with the ECS service
--rollback-events="" roll back when specified events happened
(DEPLOYMENT_FAILURE,DEPLOYMENT_STOP_ON_ALARM,DEPLOYMENT_STOP_ON_REQUEST,...)
CodeDeploy only.
--[no-]update-service update service attributes by service definition
--latest-task-definition deploy with the latest task definition without registering a new task definition
ecspresso deploy waits until the deployment completes by default. Use --no-wait to return immediately after starting the deployment, or --wait-until to choose what to wait for. This also applies when deploy creates a new service.
For the ECS deployment controller (also used when deploymentController is not set in the service definition):
deployed(default): Waits until the service deployment completes. When early success criteria is enabled, the deployment completes once the configured healthy percent of tasks is running, andecspresso deployreturns while the remaining tasks are launched in the background (and, withsourceServiceRevisionCleanup: "DEFERRED", the previous tasks are also removed in the background). When the command starts no service deployment (e.g.deploy --skip-task-definition --tasks Nchanges only the desired count), it waits until the service becomes stable instead.stable: Waits until the service becomes stable (same asaws ecs wait services-stable). Note that this waits until all tasks are running and the previous tasks are removed even if early success criteria is enabled, so ecspresso warns about this combination.paused: Waits until the deployment pauses at a lifecycle hook. See Pause lifecycle hooks.ecs:<lifecycle stage>(e.g.,ecs:BAKE_TIME): Waits until the deployment reaches the specified deployment lifecycle stage. This is useful to finish a CI job without waiting for a long bake time. Requires a traffic shifting deployment strategy (e.g.,BLUE_GREEN). Note that if a pause lifecycle hook is configured at an earlier stage, the wait continues until the deployment is resumed byecspresso continue(or times out).
For the CodeDeploy deployment controller:
codedeploy:<lifecycle event>(e.g.,codedeploy:AfterAllowTraffic): Waits until the specified CodeDeploy lifecycle event completes.- Other values wait until the CodeDeploy deployment succeeds.
In all cases, ecspresso deploy exits with a non-zero status when the deployment fails or is rolled back before the wait condition is met.
deployed is the default of every command that waits for a service deployment: deploy, refresh, rollback (stable or deployed), continue and wait (stable, deployed, or paused). scale waits until the service becomes stable, because changing the desired count starts no service deployment.
The ecspresso wait command waits for a deployment in progress without deploying, e.g. one started by ecspresso deploy --no-wait, or one being rolled back. When no deployment is in progress, --wait-until=deployed waits until the service becomes stable. ecspresso wait exits with status 0 even if the deployment is rolled back, because it does not know which result is expected.
Early success criteria completes a rolling deployment once healthyPercent of the desired tasks are running and healthy on the new service revision. The remaining tasks are launched and the previous tasks are removed outside of the deployment (sourceServiceRevisionCleanup: "DEFERRED"), or the previous tasks are removed before the deployment completes ("BLOCKING").
{
"deploymentConfiguration": {
"strategy": "ROLLING",
"minimumHealthyPercent": 50,
"earlySuccessCriteria": {
"enable": true,
"healthyPercent": 50, // between minimumHealthyPercent (default 100) and 100
"sourceServiceRevisionCleanup": "DEFERRED" // or "BLOCKING"
}
},
// ...ecspresso deploy returns as soon as the deployment completes (with the default --wait-until=deployed).
To turn it off on a service that already has it, set "enable": false explicitly. Omitting earlySuccessCriteria keeps the current setting of the service, and ECS rejects switching to another deployment strategy while it is enabled.
$ ecspresso deploy --config ecspresso.yml
...
2024-01-01T00:03:10.000+09:00 [INFO] [myService/default] TARGET 0071231069967943254 pending:2 running:2
2024-01-01T00:03:10.000+09:00 [INFO] [myService/default] service deployment completed [status:SUCCESSFUL] [reason:Service deployment met early success criteria.]
2024-01-01T00:03:10.000+09:00 [INFO] [myService/default] early success criteria is enabled; remaining tasks are launched and the previous tasks are removed in the background [healthy_percent:50] [source_service_revision_cleanup:DEFERRED]Note that the deployment circuit breaker and CloudWatch alarm rollback no longer apply after the deployment completes.
ecspresso deploy supports blue/green deployment using the ECS deployment controller. Configure ecs-service-def.json as follows. For minimal settings, you can set deploymentController.type and deploymentConfiguration.strategy as shown below.
{
"deploymentController": {
"type": "ECS"
},
"deploymentConfiguration": {
"strategy": "BLUE_GREEN"
},
// ...For more advanced settings, you can define deploymentConfiguration, loadBalancers and serviceConnectConfiguration in ecs-service-def.json. For example, using an application load balancer and set lifecycle hooks, you can use the following configuration:
{
"deploymentController": {
"type": "ECS"
},
"deploymentConfiguration": {
"bakeTimeInMinutes": 1,
"deploymentCircuitBreaker": {
"enable": false,
"rollback": false
},
"lifecycleHooks": [
{
"hookTargetArn": "arn:aws:lambda:ap-northeast-1:123456789012:function:bg-hook",
"lifecycleStages": [
"PRE_SCALE_UP",
"POST_SCALE_UP",
"TEST_TRAFFIC_SHIFT",
"POST_TEST_TRAFFIC_SHIFT",
"PRODUCTION_TRAFFIC_SHIFT",
"POST_PRODUCTION_TRAFFIC_SHIFT"
],
"roleArn": "arn:aws:iam::123456789012:role/ECSServiceRole",
"hookDetails": {
"baseUrl": "https://example.com",
"paths": ["/health_check"]
}
}
],
"maximumPercent": 200,
"minimumHealthyPercent": 100,
"strategy": "BLUE_GREEN"
},
"loadBalancers": [
{
"containerName": "app",
"containerPort": 80,
"targetGroupArn": "arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/my-target-group/1234567890abcdef"
"advancedConfiguration": {
"alternateTargetGroupArn": "arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/my-alternate-target-group/1234567890abcdef",
"productionListenerRule": "arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:listener-rule/my-production-listener-rule/1234567890abcdef",
"roleArn": "arn:aws:iam::123456789012:role/ECSServiceRole"
}
}
],
// ...hookDetails is passed to the hook target as it is. Numbers in hookDetails are handled as float64, so use a string for a value that float64 cannot represent exactly (e.g. an integer larger than 2^53).
For more details, See Amazon ECS blue/green deployments .
ecspresso deploy can deploy services using the CODE_DEPLOY deployment controller. Configure ecs-service-def.json as follows.
{
"deploymentController": {
"type": "CODE_DEPLOY"
},
// ...
}Important notes:
- ecspresso does not create or modify any CodeDeploy resources. You must separately create an application and deployment group for your ECS service in CodeDeploy.
- ecspresso automatically detects CodeDeploy deployment settings for the ECS service.
- If there are numerous CodeDeploy applications, the API calls during this detection process may cause throttling. To mitigate this, specify the CodeDeploy application_name and deployment_group_name in the config file:
# ecspresso.yml
codedeploy:
application_name: myapp
deployment_group_name: mydeployment
deployment_config_name: myDeploymentConfig # optional, override DeploymentGroup settingecspresso deploy creates a new deployment for CodeDeploy, and it continues on CodeDeploy.
$ ecspresso deploy --config ecspresso.yml --rollback-events DEPLOYMENT_FAILURE
2024-01-01T00:00:00.000+09:00 [INFO] [myService/default] Starting deploy
Service: myService
Cluster: default
TaskDefinition: myService:5
TaskSets:
PRIMARY myService:5 desired:1 pending:0 running:1
Events:
2024-01-01T00:00:01.000+09:00 [INFO] [myService/default] creating a new task definition [path:ecs-task-def.json]
2024-01-01T00:00:01.000+09:00 [INFO] [myService/default] registering a new task definition
2024-01-01T00:00:01.000+09:00 [INFO] [myService/default] task definition is registered [task_definition:myService:6]
2024-01-01T00:00:01.000+09:00 [INFO] [myService/default] desired count [count:1]
2024-01-01T00:00:02.000+09:00 [INFO] [myService/default] deployment created on CodeDeploy [deployment_id:d-XXXXXXXXX] [url:https://ap-northeast-1.console.aws.amazon.com/codesuite/codedeploy/deployments/d-XXXXXXXXX?region=ap-northeast-1]CodeDeploy appspec hooks can be defined in a config file. ecspresso automatically creates Resources and version elements in appspec on deployment:
cluster: default
service: test
service_definition: ecs-service-def.json
task_definition: ecs-task-def.json
appspec:
Hooks:
- BeforeInstall: "LambdaFunctionToValidateBeforeInstall"
- AfterInstall: "LambdaFunctionToValidateAfterTraffic"
- AfterAllowTestTraffic: "LambdaFunctionToValidateAfterTestTrafficStarts"
- BeforeAllowTraffic: "LambdaFunctionToValidateBeforeAllowingProductionTraffic"
- AfterAllowTraffic: "LambdaFunctionToValidateAfterAllowingProductionTraffic"To change the desired count of a service, specify scale --tasks.
$ ecspresso scale --tasks 10scale command is equivalent to deploy --skip-task-definition --no-update-service.
ecspresso can deploy a service using a service_definition JSON file.
$ ecspresso deploy --config ecspresso.yml
...# ecspresso.yml
service_definition: service.jsonservice.json example:
{
"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.
ecspresso rollback rolls back a service.
$ ecspresso rollback --config ecspresso.ymlBy default, ecspresso rollback stops an active deployment in progress. If no active deployment is found, it returns an error.
To rollback by deploying the previous task definition revision (legacy behavior), use --with-previous-task-definition. This finds the previous revision by listing the task definition family in descending order and deploys it regardless of active deployments.
$ ecspresso rollback --with-previous-task-definitionFor services using the CodeDeploy deployment controller, if there's an active deployment, ecspresso stops it with rollback. Otherwise, it creates a new deployment with the previous task definition.
When --count is greater than one, run waits for every task and checks the watched container in each task. If any watched container exits with a nonzero code, the command fails. --wait-until=running waits for every task to reach RUNNING, while --no-wait returns after the tasks are started. Logs of the watched container in each task are shown with the task ID, like [<task-id>] message (or a task_id field with --log-format=json).
$ ecspresso run --config ecspresso.yml --task-def=db-migrate.jsonIf --task-def is not set, ecspresso will use the task definition included in the service.
Other options for RunTask API are set by service attributes (CapacityProviderStrategy, LaunchType, PlacementConstraints, PlacementStrategy and PlatformVersion).
required_version in the configuration file is for fixing the version of ecspresso.
required_version: ">= 3.0.0, < 4"This allows ecspresso to execute if the version is greater than or equal to 3.0.0 and less than 4. If the version does not fall within this range, execution will fail.
This feature is implemented by go-version.
For ECS services using Application Auto Scaling, adjusting the minimum and maximum auto-scaling settings with the ecspresso scale command is a breeze. Simply specify either scale --auto-scaling-min or scale --auto-scaling-max to modify the settings.
$ ecspresso scale --tasks 5 --auto-scaling-min 5 --auto-scaling-max 20ecspresso deploy and scale can suspend and resume application auto scaling.
--suspend-auto-scalingsets suspended state to true.--resume-auto-scalingsets suspended state to false.
To change the suspended state, simply use ecspresso scale --suspend-auto-scaling or ecspresso scale --resume-auto-scaling. These commands will only change the suspended state without affecting other settings.
ecspresso supports the Jsonnet file format.
- v1.7 and later: Jsonnet support for service and task definitions
- v2.0 and later: Jsonnet support for the configuration file
- v2.4 and later: supports Jsonnet functions
If a file has the .jsonnet extension, ecspresso will proceed in the following order:
- process it as Jsonnet
- convert it to JSON
- load it with evaluation template syntax.
Using Template syntax in Jsonnet files may lead to syntax errors due to conflicts with Jsonnet syntax. In such cases, consider using Jsonnet functions instead.
{
cluster: 'default',
service: 'myservice',
service_definition: 'ecs-service-def.jsonnet',
task_definition: 'ecs-task-def.jsonnet',
}ecspresso includes github.com/google/go-jsonnet as a library, so a separate installation of jsonnet is not needed.
--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
}v2.4 and later supports Jsonnet native functions in Jsonnet files.
In the .jsonnet file,:
- Define
local func = std.native('func'); - Use
func()
Jsonnet functions are evaluated when rendering Jsonnet files, which helps avoid conflicts with template syntax.
env and must_env functions work the similary to template functions in JSON and YAML files. However, unlike template functions, Jsonnet functions are capable of rendering non-string values from environment variables using std.parseInt(), std.parseJson(), etc.
local env = std.native('env');
local must_env = std.native('must_env');
{
foo: env('FOO', 'default value'),
bar: must_env('BAR'),
bazNumber: std.parseInt(env('BAZ_NUMBER', '0')),
booBool: std.parseJson(env('BOO_BOOL', 'false')),
}See Plugins section.
When deploying services to Fargate, both task definitions and service definitions require specific settings.
For task definitions,
- requiresCompatibilities (requires "FARGATE")
- networkMode (requires "awsvpc")
- cpu (required)
- memory (required)
- executionRoleArn (optional)
{
"taskDefinition": {
"networkMode": "awsvpc",
"requiresCompatibilities": [
"FARGATE"
],
"cpu": "1024",
"memory": "2048",
// ...
}For service-definitions,
- launchType (requires "FARGATE")
- networkConfiguration (requires "awsvpcConfiguration")
{
"launchType": "FARGATE",
"networkConfiguration": {
"awsvpcConfiguration": {
"subnets": [
"subnet-aaaaaaaa",
"subnet-bbbbbbbb"
],
"securityGroups": [
"sg-11111111"
],
"assignPublicIp": "ENABLED"
}
},
// ...
}- Set
capacityProvidersanddefaultCapacityProviderStrategyfor the ECS cluster. - To migrate an existing service to use Fargate Spot, define
capacityProviderStrategyin the service definition as shown below. Useecspresso deploy --update-serviceto apply the settings to the service.
{
"capacityProviderStrategy": [
{
"base": 1,
"capacityProvider": "FARGATE",
"weight": 1
},
{
"base": 0,
"capacityProvider": "FARGATE_SPOT",
"weight": 1
}
],
// ...ecspresso supports ECS Service Connect.
To configure, define serviceConnectConfiguration in service definitions and portMappings in task definitions.
For more details, see Service Connect parameters
ecspresso supports Amazon EBS Volumes.
To configure, define volumeConfigurations in service definitions, and mountPoints and volumes in task definitions.
// ecs-service-def.json
"volumeConfigurations": [
{
"managedEBSVolume": {
"filesystemType": "ext4",
"roleArn": "arn:aws:iam::123456789012:role/ecsInfrastructureRole",
"sizeInGiB": 10,
"tagSpecifications": [
{
"propagateTags": "SERVICE",
"resourceType": "volume"
}
],
"volumeType": "gp3"
},
"name": "ebs"
}
]// ecs-task-def.json
// containerDefinitions[].mountPoints
"mountPoints": [
{
"containerPath": "/mnt/ebs",
"sourceVolume": "ebs"
}
]
// volumes
"volumes": [
{
"name": "ebs",
"configuredAtLaunch": true
}
]ecspresso run command supports EBS volumes too.
By default, EBS volumes attached to standalone tasks are deleted when the task stops. Use the --no-ebs-delete-on-termination option to preserve volumes.
$ ecspresso run --no-ebs-delete-on-terminationFor tasks run by ECS services, EBS volumes are always deleted when the task stops. This is an ECS specification that ecspresso cannot override.
ecspresso supports Amazon S3 Files volumes.
To configure, define mountPoints and volumes with s3filesVolumeConfiguration in task definitions.
// ecs-task-def.json
// containerDefinitions[].mountPoints
"mountPoints": [
{
"containerPath": "/mnt/s3",
"sourceVolume": "s3files"
}
]
// volumes
"volumes": [
{
"name": "s3files",
"s3filesVolumeConfiguration": {
"fileSystemArn": "arn:aws:s3files:ap-northeast-1:123456789012:file-system/fs-01234567890abcdef",
"rootDirectory": "/"
}
}
]See Prerequisites for S3 Files for IAM role and security group configuration required for S3 Files mount targets.
ecspresso supports VPC Lattice integration.
- Define
portMappingsin the task definition. Thenamefield is required.
{
"containerDefinitions": [
{
"name": "webserver",
"portMappings": [
{
"name": "web-80-tcp",
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp",
"appProtocol": "http"
}
],- Define
vpcLatticeConfigurationsin the service definition. TheportName,roleArn, andtargetGroupArnfields are required.`
- The
portNamemust match thenamefield of theportMappingsin the task definition. - The
roleArnis the IAM role that the ECS service assumes to call the VPC Lattice API.- The role must have the
ecs.amazonaws.comservice principal. - The role should have the
AmazonECSInfrastructureRolePolicyForVpcLatticepolicy or equivalent permissions.
- The role must have the
- The
targetGroupArnis the ARN of the VPC Lattice target group.
{
"vpcLatticeConfigurations": [
{
"portName": "web-80-tcp",
"roleArn": "arn:aws:iam::123456789012:role/ecsInfrastructureRole",
"targetGroupArn": "arn:aws:vpc-lattice:ap-northeast-1:123456789012:targetgroup/tg-009147df264a0bacb"
}
],ecspresso doesn't create or modify any VPC Lattice resources. You must create and associate a VPC Lattice target group with the ECS service.
See also Use Amazon VPC Lattice to connect, observe, and secure your Amazon ECS services.
ecspresso supports connecting a service to Amazon ECS Gateway, a managed ingress that provisions shared Application Load Balancers for ECS services.
-
Define
portMappingswith thenamefield in the task definition. The task definition must use theawsvpcnetwork mode. -
Define
gatewayConnectorsin the service definition. A service supports at most one gateway connector, and theportNamefield is required.
{
"gatewayConnectors": [
{
"portName": "web-80-tcp",
"filters": {
"accessTypes": ["PRIVATE"]
},
"healthCheck": {
"healthCheckPath": "/health"
}
}
],- The
portNamemust match thenamefield of theportMappingsin the task definition. filters.accessTypes(optional) limits the gateways the service connects to (PUBLIC,PRIVATE, or both). A service that must not be reachable from the internet should setPRIVATE.healthCheck(optional) configures the target group health check. A health check change replaces the target group, so it cannot be applied to a service using theROLLINGdeployment strategy.
When gatewayConnectors is not defined in the service definition, ecspresso deploy disconnects the service from all gateways, in the same way as loadBalancers and vpcLatticeConfigurations. A gateway connected again later gives the service a new hostname, so if the connector was added outside of ecspresso, run ecspresso diff to check before deploying.
gatewayConnectors is read from the current service revision (DescribeServiceRevisions), like monitoring.
ecspresso doesn't create or modify gateways or their cluster associations. You must create a gateway and associate it with the cluster before connecting the service. ecspresso verify checks that an ACTIVE gateway is associated with the cluster (requires ecs:ListGatewayClusterAssociations).
gatewayConnectors is not supported with the CODE_DEPLOY deployment controller or in Express mode.
ecspresso supports high resolution CloudWatch metrics for ECS services.
To configure, define monitoring in the service definition. The metricConfigurations field specifies which metrics to collect and at what resolution.
{
"monitoring": {
"metricConfigurations": [
{
"metricNames": ["CPUUtilization", "MemoryUtilization"],
"resolutionSeconds": 20
}
]
}
}metricNames: The metrics to configure. Supported values areCPUUtilizationandMemoryUtilization.resolutionSeconds: The resolution in seconds. Valid values are20(high resolution) and60(default).
When not specified, Amazon ECS uses the default resolution of 60 seconds. High resolution metrics enable faster auto scaling responses.
monitoring is not returned by DescribeServices, so ecspresso reads it from the current service revision by DescribeServiceRevisions. The IAM principal that runs ecspresso needs ecs:DescribeServiceRevisions on the service revision ARN (arn:aws:ecs:<region>:<account>:service-revision/<cluster>/<service>/*). If the call fails, commands that describe the service (deploy, diff, status, etc.) fail instead of treating the attribute as unset.
ecspresso supports pause lifecycle hooks for ECS service deployments.
Pause hooks are available for blue/green, linear, and canary deployment strategies (not rolling).
To configure, define lifecycleHooks with targetType: PAUSE in deploymentConfiguration in the service definition.
{
"deploymentConfiguration": {
"strategy": "BLUE_GREEN",
"lifecycleHooks": [
{
"lifecycleStages": ["POST_TEST_TRAFFIC_SHIFT"],
"targetType": "PAUSE",
"timeoutConfiguration": {
"timeoutInMinutes": 60,
"action": "ROLLBACK"
}
}
]
}
}Use --wait-until=paused with ecspresso deploy to wait until the deployment pauses at the lifecycle hook.
$ ecspresso deploy --wait-until=pausedAfter reviewing the deployment, use ecspresso continue to proceed or ecspresso rollback to roll back.
# Continue the deployment to the next stage
$ ecspresso continue
# Or roll back the deployment
$ ecspresso rollbackecspresso continue also accepts --wait-until to wait after continuing (default: deployed). Use --wait-until=paused to wait for the next pause hook if multiple hooks are configured.
For linear and canary deployments, pause hooks at PRE_PRODUCTION_TRAFFIC_SHIFT are invoked at each traffic shift step. Each step generates a unique hookId, so you need to run ecspresso continue --wait-until=paused repeatedly for each step.
Use --wait-until=ecs:<lifecycle stage> (e.g., ecs:BAKE_TIME) with ecspresso deploy to return when the deployment reaches the specified lifecycle stage, instead of waiting for the whole deployment to finish. This is useful to finish a CI job without waiting for a long bake time.
$ ecspresso deploy --wait-until=ecs:BAKE_TIMEThis option requires a traffic shifting deployment strategy (blue/green, linear, or canary). If the deployment is rolled back before reaching the target stage, ecspresso deploy exits with a non-zero status.
ecspresso supports ECS Express mode, which provides a simplified way to deploy ECS services with a single definition file instead of separate task and service definitions.
The following commands work with Express mode:
init --express- Import an existing Express service into definition filesdeploy- Create or update Express servicesdiff- Show differences between local and remote Express definitionsrender expressdef- Render an Express definition filedelete- Delete an Express servicestatus- Show Express service status including ingress pathsrollback- Partial support (works only during active deployments)verify- Verify resources in Express definitionexec,refresh,tasks,wait- Also supported
Some commands do not work with Express mode: scale, run, revisions, register, deregister, appspec.
To use Express mode, specify express_definition instead of task_definition and service_definition in your config file:
# ecspresso.yml
region: ap-northeast-1
cluster: ecspresso
service: myservice
express_definition: ecs-express-def.json{
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
"infrastructureRoleArn": "arn:aws:iam::123456789012:role/ecsInfrastructureRoleForExpressServices",
"primaryContainer": {
"image": "nginx:latest"
}
}// ecs-express-def.jsonnet
{
cpu: '256',
memory: '512',
executionRoleArn: 'arn:aws:iam::123456789012:role/ecsTaskExecutionRole',
taskRoleArn: 'arn:aws:iam::123456789012:role/ecsTaskRole',
infrastructureRoleArn: 'arn:aws:iam::123456789012:role/ecsInfrastructureRoleForExpressServices',
healthCheckPath: '/',
networkConfiguration: {
securityGroups: ['sg-00123456789abcdef'],
subnets: ['subnet-00123456789abcdef', 'subnet-0123456789abcdef0'],
},
primaryContainer: {
image: 'nginx:latest',
containerPort: 80,
environment: [
{ name: 'ENV', value: 'production' },
],
awsLogsConfiguration: {
logGroup: '/aws/ecs/myservice',
logStreamPrefix: 'ecs',
},
},
scalingTarget: {
autoScalingMetric: 'AVERAGE_CPU',
autoScalingTargetValue: 60,
minTaskCount: 1,
maxTaskCount: 10,
},
tags: [
{ key: 'Environment', value: 'production' },
],
}Existing ECS Express services can be imported as non-express (normal) mode by ecspresso init --no-express. This creates standard definition files (ecspresso.yml, ecs-service-def.json, and ecs-task-def.json).
Note: ECS Express mode cannot update deploymentConfiguration and loadBalancers in a service definition. ecspresso init --no-express also omits these fields.
ecspresso supports diff and verify commands.
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": {v2.4 or later, ecspresso diff --external can invoke an external command. You can use the "diff" command you like.
For example, use difftastic (difft) command.
$ ecspresso diff --external "difft --color=always"
$ ECSPRESSO_DIFF_COMMAND="difft --color=always" ecspresso diffThe command should exit with status 0. If it exits with a non-zero status when two files differ (for example, diff(1)), you need to write a wrapper command.
ecspresso diff --jsonnet renders the diff output in Jsonnet format instead of JSON. This is useful when you manage definitions in Jsonnet files.
$ ecspresso diff --jsonnetecspresso diff --without-service skips the diff of the service definition and only shows the diff of the task definition.
$ ecspresso diff --without-serviceecspresso diff --exit-code exits with status 2 when there are differences, and 0 when there are none. Status 1 is an error, as with the other commands.
$ ecspresso diff --exit-code || echo "exit status: $?"Verify resources related with service/task definitions.
For example it checks if,
- 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 ecs-tasks.amazonaws.com.
- Container images exist at the URL defined in task definitions. (Checks only for ECR, ECR Public or DockerHub public images.)
- Secrets in task definitions exist and are readable.
- Log streams can be created and messages can be put into the specified CloudWatch log groups streams.
ecspresso verify checks what the AWS APIs do not report when deploy calls them, such as a missing resource that makes tasks fail to start after the deployment has begun. It does not validate the definitions against the rules of the ECS API (allowed values, required fields, or combinations of settings). ECS reports them when you deploy.
ecspresso verify tries to assume the task execution role defined in task definitions to verify these items. If it fails to assume the role, it continues to verify with the current session.
For images on Amazon ECR Public (public.ecr.aws), ecspresso verify gets an authorization token with the current session to avoid the low rate limit of anonymous pulls. This requires the ecr-public:GetAuthorizationToken and sts:GetServiceBearerToken permissions. If it fails to get the token, it continues to verify anonymously.
$ ecspresso verify
2024-01-01T00:00:00.000+09:00 [INFO] [nginx-local/ecspresso-test] Starting verify
TaskDefinition
ExecutionRole[arn:aws:iam::123456789012:role/ecsTaskRole]
--> [OK]
TaskRole[arn:aws:iam::123456789012:role/ecsTaskRole]
--> [OK]
ContainerDefinition[nginx]
Image[nginx:alpine]
--> [OK]
LogConfiguration[awslogs]
--> [OK]
--> [OK]
--> [OK]
ServiceDefinition
--> [OK]
Cluster
--> [OK]
2024-01-01T00:00:04.000+09:00 [INFO] [nginx-local/ecspresso-test] Verify OK!ecspresso can manipulate ECS tasks using the tasks and exec commands.
After v2.0, These operations are provided by ecsta as a library. The ecsta CLI can manipulate any ECS tasks, not limited to those deployed by ecspresso.
Consider using ecsta as a CLI command.
The tasks command lists tasks related to the ecspresso configuration. When service is configured, it lists tasks belonging to the service plus standalone tasks of the same family (typically launched by ecspresso run). Tasks of other services that share the task definition family are excluded. When service is not configured, it lists tasks of the task definition family.
Usage: ecspresso tasks <command> [flags]
Common flags:
--id= task ID
--output=table output format (table, json, tsv)
Commands:
tasks list list tasks (default)
tasks find find a task from tasks list and dump it as JSON
tasks stop stop a task
tasks trace trace a task
tasks logs show logs of a task
The find subcommand enables task selection from a list and displays it as JSON.
The ECSPRESSO_FILTER_COMMAND environment variable can be set to specify a command for filtering tasks, such as peco, fzf, etc.
$ ECSPRESSO_FILTER_COMMAND=peco ecspresso tasks findThe stop subcommand allows for task selection and stopping from a list.
$ ecspresso tasks stop --forceFlags:
--force=false stop the task without confirmation
The logs subcommand shows CloudWatch Logs of the task.
$ ecspresso tasks logs -f -d 5m --container appFlags:
-f, --follow=false follow logs
-d, --duration=1m duration of logs
-s, --start-time= start time of logs
--container= container name
Use --follow to follow logs in real time, --duration to specify the time range, and --start-time to specify an absolute start time. When --log-format json is set, logs are output as JSON lines.
The exec command executes a command on a task.
session-manager-plugin is required in PATH.
Usage: ecspresso exec <command> [flags]
Common flags:
--id= task ID
--container= container name
Commands:
exec run execute command on task (default)
exec portforward port forwarding to a task
exec cp <src> <dest> copy files between local and task
If --id is not set, the command shows a list of tasks to select a task to execute.
The ECSPRESSO_FILTER_COMMAND environment variable works the same as with the tasks command.
See also the official documentation Using Amazon ECS Exec for debugging.
The run subcommand (default) executes a command on a task interactively.
$ ecspresso exec run --command "ls -la"Flags:
--command=sh command to execute
The portforward subcommand enables port forwarding from a local port to an ECS task's port.
$ ecspresso exec portforward --port 80 --local-port 8080Flags:
--local-port=0 local port number
--port=0 remote port number
--host= remote host
-L short expression of local-port:host:port
If --id is not set, the command shows a list of tasks to select for port forwarding.
When --local-port is not specified, an ephemeral port is used as the local port.
The -L option is a short expression for local-port:host:port. For example, -L 8080:example.com:80 is equivalent to --local-port 8080 --host example.com --port 80.
$ ecspresso exec portforward -L 8080:example.com:80The cp subcommand copies files between local and a running ECS task.
The source and destination arguments use taskID:/path format for the remote side. Use _ as the task ID to select a task interactively.
# Copy a local file to the task
$ ecspresso exec cp /local/file.txt _:/remote/file.txt
# Copy a file from the task to local
$ ecspresso exec cp _:/remote/file.txt /local/file.txt
# Specify a task ID directly
$ ecspresso exec cp /local/file.txt abcdef1234567890:/remote/file.txtFlags:
--port=12345 port number for file transfer
--[no-]progress show progress bar (default true)
The docs command shows the embedded documentation (this README and migration guides) directly from the ecspresso binary. This command does not require AWS credentials or a configuration file.
Flags:
--article="readme" article name to display
--list list available articles
--index show table of contents
--search="" search keyword in documents
--json output in JSON format
Show the full README:
$ ecspresso docsShow the table of contents with section headings and line numbers:
$ ecspresso docs --indexSearch for sections containing a keyword (case-insensitive):
$ ecspresso docs --search "fargate"Output in JSON format (useful for LLM agents and other tools):
$ ecspresso docs --search "deploy" --jsonThe JSON output contains structured sections with level, title, content, and line fields, making it easy for automated tools and LLM agents to consume ecspresso documentation programmatically.
List available articles:
$ ecspresso docs --list
readme ecspresso README
v1-v2 Migration guide from v1 to v2
v2-v3 Migration guide from v2 to v3Show a migration guide:
$ ecspresso docs --article v2-v3ecspresso provides an Agent Skill for LLM agents (Claude Code, GitHub Copilot, OpenAI Codex, etc.) to use ecspresso effectively. The skill covers common workflows, command usage patterns, and best practices. Powered by Songmu/skillsmith.
Install the skill for your user:
$ ecspresso skills installThis installs the skill to ~/.agents/skills/ecspresso/SKILL.md. Compatible LLM agents automatically discover skills in this directory — no additional configuration is needed.
To share the skill with your team via the repository, use --scope repo:
$ ecspresso skills install --scope repoThis installs to .agents/skills/ in the repository root. Commit this directory so that team members' agents can use the skill without installing it individually.
Other skills operations:
$ ecspresso skills list # List available skills
$ ecspresso skills status # Show installation status
$ ecspresso skills update # Update installed skills
$ ecspresso skills uninstall # Remove installed skills
$ ecspresso skills reinstall # Reinstall all managed skillsecspresso supports plugins to extend template functions and Jsonnet native functions.
The tfstate plugin introduces the tfstate and tfstatef template functions.
ecspresso.yml
region: ap-northeast-1
cluster: default
service: test
service_definition: ecs-service-def.json
task_definition: ecs-task-def.json
plugins:
- name: tfstate
config:
url: s3://my-bucket/terraform.tfstate
# or path: terraform.tfstate # path to local fileecs-service-def.json
{
"networkConfiguration": {
"awsvpcConfiguration": {
"subnets": [
"{{ tfstatef `aws_subnet.private['%s'].id` `az-a` }}"
],
"securityGroups": [
"{{ tfstate `data.aws_security_group.default.id` }}"
]
}
}
}{{ tfstate "resource_type.resource_name.attr" }} will expand to the 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 for build a resource addresses with environment variables.
{{ tfstatef `aws_subnet.ecs['%s'].id` (must_env `SERVICE`) }}
tfstate Jsonnet function works the same as template function in JSON and YAML files.
tfstatef Jsonnet function is not provided. Use std.format() or interpolation instead.
local tfstate = std.native('tfstate');
{
networkConfiguration: {
awsvpcConfiguration: {
subnets: [
tfstate('aws_subnet.private["%s"].id' % 'az-z'),
tfstate(std.format('aws_subnet.private["%s"].id', 'az-b')),
],
securityGroups: [
sg.id for sg in std.objectValues(tfstate('data.aws_security_group.default'))
// data.aws_security_group.default["first"].id
// data.aws_security_group.default["second"].id
]
}
}
}When the tfstate includes count/for_each resources, so the resource address can be specified with an index.
local tfstate = std.native('tfstate');
tfstate('aws_subnet.private["%s"].id' % 'az-a') // aws_subnet.private["az-a"].idTo fetch all resources of count/for_each resources, use std.objectValues().
local tfstate = std.native('tfstate');
{
subnets: [
subnet.id for subnet in std.objectValues(tfstate('aws_subnet.private'))
// aws_subnet.private["az-a"].id
// aws_subnet.private["az-b"].id
// aws_subnet.private["az-c"].id
],
}- Local file
file://path/to/terraform.tfstate - HTTP/HTTPS
https://example.com/terraform.tfstate - Amazon S3
s3://{bucket}/{key} - Terraform Cloud
remote://api.terraform.io/{organization}/{workspaces}TFE_TOKENenvironment variable is required.
- Google Cloud Storage
gs://{bucket}/{key} - Azure Blog Storage
azurerm://{resource_group_name}/{storage_account_name}/{container_name}/{blob_name}
This plugin uses tfstate-lookup to load tfstate.
func_prefix adds prefixes to template function names for each plugin configuration, enabling support for multiple tfstate files.
# 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_In templates, functions are called with the specified prefixes.
[
"{{ first_tfstate `aws_s3_bucket.main.arn` }}",
"{{ second_tfstate `aws_s3_bucket.main.arn` }}"
]Similar features are also supported for Jsonnet.
local first_tfstate = std.native('first_tfstate'); // func_prefix: first_
local second_tfstate = std.native('second_tfstate'); // func_prefix: second_
[
first_tfstate('aws_s3_bucket.main.arn'),
second_tfstate('aws_s3_bucket.main.arn'),
]The cloudformation plugin introduces the cfn_output and cfn_export template functions.
An example of a CloudFormation stack template defining Outputs and Exports.
# StackName: ECS-ecspresso
Outputs:
SubnetAz1:
Value: !Ref PublicSubnetAz1
SubnetAz2:
Value: !Ref PublicSubnetAz2
EcsSecurityGroupId:
Value: !Ref EcsSecurityGroup
Export:
Name: !Sub ${AWS::StackName}-EcsSecurityGroupIdLoad the cloudformation plugin in a config file.
ecspresso.yml
# ...
plugins:
- name: cloudformationcfn_output StackName OutputKey looks up the OutputValue of OutputKey in the StackName.
cfn_export ExportName looks up the exported value by name.
ecs-service-def.json
{
"networkConfiguration": {
"awsvpcConfiguration": {
"subnets": [
"{{ cfn_output `ECS-ecspresso` `SubnetAz1` }}",
"{{ cfn_output `ECS-ecspresso` `SubnetAz2` }}"
],
"securityGroups": [
"{{ cfn_export `ECS-ecspresso-EcsSecurityGroupId` }}"
]
}
}
}Similar features are also supported for Jsonnet.
local cfn_output = std.native('cfn_output');
local cfn_export = std.native('cfn_export');
{
subnets: [
cfn_output('ECS-ecspresso', 'SubnetAz1'),
cfn_output('ECS-ecspresso', 'SubnetAz2'),
],
securityGroups: [
cfn_export('ECS-ecspresso-EcsSecurityGroupId'),
],
}The ssm template function reads parameters from AWS Systems Manager (SSM) Parameter Store.
Given 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"
This template,
{
"string": "{{ ssm `/path/to/string` }}",
"stringlist": "{{ ssm `/path/to/stringlist` 1 }}", *1
"securestring": "{{ ssm `/path/to/securestring` }}"
}will be rendered as:
{
"string": "ImString",
"stringlist": "ImStringList1",
"securestring": "ImSecureString"
}The ssm function works the same as template function. For string list parameters, use ssm_list to specify the index.
local ssm = std.native('ssm');
local ssm_list = std.native('ssm_list');
{
string: ssm('/path/to/string'),
stringlist: ssm_list('/path/to/stringlist', 1),
securestring: ssm('/path/to/securestring'),
}The secretsmanager_arn template function resolves the Secrets Manager secret ARN by secret name.
"secrets": [
{
"name": "FOO",
"valueFrom": "{{ secretsmanager_arn `foo` }}"
}
]will be rendered as:
"secrets": [
{
"name": "FOO",
"valueFrom": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:foo-06XQOH"
}
]The secretsmanager_arn function works the same as template function.
local secretsmanager_arn = std.native('secretsmanager_arn');
{
secrets: [
{
name: "FOO",
valueFrom: secretsmanager_arn('foo'),
}
]
}The external plugin introduces functions to execute any external commands.
For example, jq -n "{ Now: now | todateiso8601" } returns the current date in ISO8601 format as a JSON object.
$ jq -n "{ Now: now | todateiso8601 }"
{
"Now": "2024-10-25T16:13:22Z"
}You can use this command as a template function in the definition files.
First, define the plugin in the configuration file.
ecspresso.yml
plugins:
- name: external
config:
name: jq
command: ["jq", "-n"]
num_args: 1
timeout: 5The config section defines the following parameters:
name: template function namecommand: external command and arguments (array)- The command must return a JSON string or any strings to stdout.
num_args: number of arguments (optional, default 0)parser: parser type "json" or "string" (optional, default "json")timeout: command execution timeout (optional, default never timeout). Accepts a duration string ("30s","5m","1h") or a bare number / digit string interpreted as seconds (30→ 30 seconds).mode: execution mode "exec" or "jsonrpc" (optional, default "exec")exec: the command is launched once per template function call (default)jsonrpc: the command is launched once on the first call and kept running; subsequent calls communicate over stdin/stdout using JSON RPC 2.0. Useful for commands with high startup cost.
And use the template function in the definition files as follows.
local jq = std.native('jq');
{
today: jq('{ Now: now | todateiso8601 }').Now,
}{
"today": "{{ (jq `{Now: now | todateiso8601}`).Now }}"
}When mode: jsonrpc is set, ecspresso launches the command once and keeps it running. Each template function call sends a JSON RPC 2.0 request to the process's stdin and reads the response from stdout.
The external process must read newline-delimited JSON requests from stdin and write newline-delimited JSON responses to stdout.
Request format:
{"jsonrpc":"2.0","method":"<name>","params":["arg0","arg1"],"id":1}Response format (success):
{"jsonrpc":"2.0","result":<any JSON value>,"id":1}Response format (error):
{"jsonrpc":"2.0","error":{"code":-32600,"message":"error message"},"id":1}methodis thenamefield from the plugin config.paramsis an array of string arguments passed to the template function.- The
idfield correlates a request with its response. A response whoseiddoes not match the request is treated as an error. timeoutapplies per call. A call that times out fails immediately, the same asexecmode. The process is killed so a stalled command does not linger.- The process is also terminated when ecspresso exits (its stdin is closed, then SIGTERM/SIGKILL).
Example configuration using a long-running Python server:
plugins:
- name: external
config:
name: lookup
command: ["python3", "lookup_server.py"]
num_args: 1
mode: jsonrpc
timeout: 10MIT
KAYAC Inc.