Environment Variables

Pass configuration into containers with plain environment variables.

Use environment for non-sensitive config, and environmentFiles to load many variables from a file in S3.

Guidelines

  • Keep secrets OUT of environment — anyone with read access can see them.
  • Use environmentFiles for large, shared config.

Example

Example · json
{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "app:1",
      "environment": [
        {
          "name": "NODE_ENV",
          "value": "production"
        },
        {
          "name": "LOG_LEVEL",
          "value": "info"
        }
      ],
      "environmentFiles": [
        {
          "type": "s3",
          "value": "arn:aws:s3:::my-config/app.env"
        }
      ]
    }
  ]
}

When to use it

  • A developer passes the DATABASE_URL as an environment variable to a container so the app reads its connection string without any code changes.
  • A team sets the LOG_LEVEL environment variable to DEBUG in the staging task definition and ERROR in production to control verbosity per environment.
  • An ops engineer bulk-injects configuration from an S3 environment file so the container definition stays clean with no long list of key-value pairs.

More examples

Inline Environment Variables

Injects three plain-text environment variables into the container at task launch; suitable for non-sensitive configuration.

Example · json
{
  "name": "api",
  "image": "my-api:latest",
  "environment": [
    {"name": "LOG_LEVEL", "value": "info"},
    {"name": "PORT", "value": "8080"},
    {"name": "REGION", "value": "us-east-1"}
  ]
}

Load Variables from S3 env File

Loads a .env-format file from S3 at task startup, injecting all KEY=VALUE pairs as environment variables without listing them in the task definition.

Example · json
{
  "name": "worker",
  "image": "my-worker:latest",
  "environmentFiles": [
    {
      "value": "arn:aws:s3:::my-config-bucket/prod.env",
      "type": "s3"
    }
  ]
}

Override Env Var at run-task Time

Overrides a single environment variable at runtime to pass a unique job ID to a task without creating a new task definition revision.

Example · bash
aws ecs run-task \
  --cluster prod \
  --task-definition worker:5 \
  --launch-type FARGATE \
  --network-configuration 'awsvpcConfiguration={subnets=[subnet-a],securityGroups=[sg-w],assignPublicIp=DISABLED}' \
  --overrides '{"containerOverrides":[{"name":"worker","environment":[{"name":"JOB_ID","value":"run-42"}]}]}'

Related

ecs td secrets

Discussion

  • Be the first to comment on this lesson.