Environment & Secrets in ECS
Inject config as environment variables and secrets pulled securely from SSM or Secrets Manager.
Your container needs configuration: database URLs, API keys, feature flags. Never bake these into the image. Instead, ECS injects them at runtime.
Two kinds of config
- Plain env vars — non-sensitive values via the
environmentblock. - Secrets — sensitive values via the
secretsblock, which pulls from SSM Parameter Store or Secrets Manager at task start. The value never appears in the task definition or logs.
The task's execution role must have permission to read those parameters. This keeps secrets out of your codebase entirely.
Example
"containerDefinitions": [{
"name": "web",
"image": "...ecr.../myapp:abc123",
"environment": [
{ "name": "NODE_ENV", "value": "production" },
{ "name": "PORT", "value": "3000" }
],
"secrets": [
{
"name": "DATABASE_URL",
"valueFrom": "arn:aws:ssm:us-east-1:123456789012:parameter/myapp/prod/db-url"
}
]
}When to use it
- A team injects the database password into a Fargate task from Secrets Manager so the credential never appears in the image or task definition in plaintext.
- An app reads its feature flags from SSM Parameter Store environment variables so the same image can run in dev and prod with different configs.
- A CI pipeline retrieves an API key from Secrets Manager and passes it to a Fargate task so it never touches the pipeline logs.
More examples
Store a secret in Secrets Manager
Creates a named secret in Secrets Manager that the ECS task execution role can retrieve at container startup.
aws secretsmanager create-secret \
--name prod/myapp/db-password \
--secret-string 'SuperSecretP@ss!'Reference secret in task definition
Shows how to mix plain environment variables with secrets pulled from Secrets Manager into a container definition.
{
"name": "myapp",
"image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest",
"environment": [
{ "name": "APP_ENV", "value": "production" }
],
"secrets": [
{
"name": "DB_PASSWORD",
"valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/myapp/db-password"
}
]
}Grant task execution role access
Grants the ECS task execution role permission to read secrets so Fargate can inject them at container startup.
aws iam attach-role-policy \
--role-name ecsTaskExecutionRole \
--policy-arn arn:aws:iam::aws:policy/SecretsManagerReadWrite
# Or scope it tightly with an inline policy:
# secretsmanager:GetSecretValue on the specific secret ARN
Discussion