Skip to content
koducathome

ECS Task Definition to .env Converter

Extract environment variables from an AWS ECS task definition and generate a clean .env file — multiple containers, SSM and Secrets Manager references kept as references, never as values.

How to use this tool

Steps for using the ECS Task Definition to .env.

  1. Paste a task definition into Get ECS Task Definition JSON, click Upload File, or Load Example. Both a plain task definition and the full output of aws ecs describe-task-definition (with its taskDefinition wrapper) work.
  2. Optionally switch to ECS — Live from AWS, enter a region and temporary read-only credentials, then pick a family and revision (or a cluster and service) and press Load from AWS. Your browser calls AWS directly.
  3. Under Container selection, tick the containers you want. Choose One combined .env file or A separate file per container, and turn on Prefix keys with container name to get API_PORT instead of PORT.
  4. Pick how Duplicate keys are handled — keep the first value (the default, with a warning), keep the last, prefix duplicates with the container, or write separate files. Nothing is overwritten silently: every duplicate is listed under Checks.
  5. Choose Secret handling: keep each secrets entry as a reference such as <SSM_PARAMETER:/my-service/db-password>, or write CHANGE_ME placeholders.
  6. Review the .env Output, By Container, Environment Variables, Secrets or Preview tab, then Copy, Download the current view, or Download .env.

Example

Environment variables and an SSM secret reference

Task definition JSON
{
  "family": "my-service",
  "containerDefinitions": [
    {
      "name": "api",
      "environment": [
        { "name": "NODE_ENV", "value": "production" },
        { "name": "PORT", "value": "3000" }
      ],
      "secrets": [
        {
          "name": "DB_PASSWORD",
          "valueFrom": "arn:aws:ssm:ap-south-1:123456789012:parameter/my-service/db-password"
        }
      ]
    }
  ]
}
.env (defaults)
# Generated from AWS ECS task definition my-service
# Containers: api
# Variables: 3 (environment: 2, secrets: 1)
# Secret values are references, not real values — resolve them in your deployment or with the AWS CLI.

NODE_ENV=production
PORT=3000
# DB_PASSWORD ← SSM parameter /my-service/db-password (arn:aws:ssm:ap-south-1:123456789012:parameter/my-service/db-password)
DB_PASSWORD=<SSM_PARAMETER:/my-service/db-password>

Common use cases

  • Running a service locally with the same configuration as its ECS deployment.
  • Auditing which environment variables and secrets each container in a task receives.
  • Moving a service from ECS to Docker Compose, Kubernetes or another platform.
  • Comparing two task definition revisions by converting both and diffing the .env output.

Where ECS keeps environment variables, and how they become a .env file

An ECS task definition describes one or more containers in its containerDefinitions array. Each container can declare plain variables in environment — a list of { "name", "value" } pairs stored in the task definition itself — and sensitive ones in secrets, where valueFrom points to an SSM Parameter Store parameter or a Secrets Manager secret. ECS resolves those references with the task execution role when the container starts, so the real value never appears in the task definition.

The converter reads only those two arrays. Other settings such as the image, port mappings, roles and log configuration are shown for context but never turned into variables. environmentFiles (.env files in S3) are listed as a warning because their contents are not part of the JSON. Values are written with the same quoting rules as the Env Formatter: plain values stay bare, values with spaces or # get single quotes, and values with newlines, single quotes or backslashes get double quotes with escapes. Empty values become KEY="".

Secrets go through a separate path, so a reference can never be mistaken for a value. By default DB_PASSWORD becomes <SSM_PARAMETER:/my-service/db-password> or <SECRETS_MANAGER:my-service/api-key> (the random six-character suffix of a Secrets Manager ARN is dropped, and a selected JSON key is kept), with the full ARN in a comment above it. A file like that is a map of what to fetch, not a working configuration — resolve each reference with your deployment tooling or the AWS CLI before running the app.

Variable names must contain only letters, digits and underscores and must not start with a digit. Other characters are replaced with _ and each rename is noted in the output and the preview. When two containers define the same name in one combined file, the default keeps the first value, comments the skipped one and lists the collision; you can instead keep the last value, prefix the duplicates with their container ({container}_{KEY}, configurable), or write one file per container.

Limitations

  • Secret values are never fetched — secrets entries become references or CHANGE_ME placeholders.
  • Variables in environmentFiles stored in S3 are not included, because the task definition only contains the file's location.
  • ECR, CloudFormation and Terraform sources are not available yet; paste the task definition JSON instead.
  • Live from AWS needs credentials with the read-only ECS permissions listed in the tool, and a browser that can reach ecs.<region>.amazonaws.com.

Frequently asked questions

How do I convert an ECS task definition to a .env file?

Get the JSON with aws ecs describe-task-definition --task-definition my-service (or copy it from the ECS console's JSON tab), paste it into the tool and download the result. Each environment entry becomes NAME=value; secrets entries become references. Choose which containers to include and whether to prefix keys with the container name.

Where are ECS environment variables stored?

In the task definition: each container definition has an environment array of name/value pairs, a secrets array of references to SSM Parameter Store or Secrets Manager, and optionally environmentFiles that point to .env files in S3. Services and tasks can also override environment variables at launch, which the task definition does not show.

What is the difference between environment and secrets in ECS?

environment values are stored in plain text in the task definition and visible to anyone who can describe it. secrets hold only a reference in valueFrom; ECS fetches the real value with the task execution role when the container starts and injects it as an environment variable, so the value never appears in the task definition.

Can I retrieve the actual value from a Secrets Manager ARN?

Not with this tool — it never fetches secret values. With permission you can run aws secretsmanager get-secret-value --secret-id <arn> or, for SSM, aws ssm get-parameter --name <name> --with-decryption. Keep resolved secrets out of version control.

How do I handle multiple ECS containers?

All containers are detected automatically. Pick the ones you need, then write one combined file — optionally with container prefixes such as API_PORT and WORKER_PORT — or a separate file per container. Duplicate names are listed under Checks and handled with the strategy you choose; none are dropped silently.

Is my task definition JSON uploaded to a server?

No. Pasted or uploaded JSON is converted in your browser and is not sent to Koducat or stored. The optional Live from AWS source sends requests from your browser directly to the AWS ECS API using the credentials you enter; they are kept in memory only and never sent to Koducat.