Introduction

In ECS, environment-related configuration in a task definition usually falls into three buckets: plain environment variables, secret-backed environment variables, and environment files. The right choice depends on whether the value is sensitive and how you want to manage it operationally.

Option 1: Plain environment

If the value is not sensitive, put it directly in the container definition under environment:

1{
2  "containerDefinitions": [
3    {
4      "name": "app",
5      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest",
6      "environment": [
7        { "name": "APP_ENV", "value": "production" },
8        { "name": "LOG_LEVEL", "value": "info" }
9      ]
10    }
11  ],
12  "family": "my-task"
13}

This is simple and explicit, but the values are visible in the task definition, so do not use this for secrets.

Option 2: secrets for Sensitive Values

For passwords, tokens, and similar sensitive values, use the secrets field and reference AWS Secrets Manager or Systems Manager Parameter Store.

1{
2  "containerDefinitions": [
3    {
4      "name": "app",
5      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest",
6      "secrets": [
7        {
8          "name": "DB_PASSWORD",
9          "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:db-password"
10        }
11      ]
12    }
13  ],
14  "family": "my-task"
15}

This lets ECS inject the secret as an environment variable at runtime without storing the raw value directly in the task definition JSON.

Option 3: environmentFiles

If you want to provide many non-sensitive variables from a file, ECS also supports environment files:

1{
2  "containerDefinitions": [
3    {
4      "name": "app",
5      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest",
6      "environmentFiles": [
7        {
8          "value": "arn:aws:s3:::my-config-bucket/app.env",
9          "type": "s3"
10        }
11      ]
12    }
13  ],
14  "family": "my-task"
15}

This is useful when you want Docker-style env-file management rather than listing many variables inline.

Which One Should You Use

A good rule is:

• ordinary config: environment
• secrets: secrets
• many file-based variables: environmentFiles

Do not put secrets into plain environment unless you are intentionally accepting that exposure risk.

IAM Permissions Matter

If you use secrets or environment files, the task execution role must have permission to read the referenced secret or file.

That typically means:

• permission to access the Secrets Manager secret or Parameter Store parameter
• permission to read the S3 object if using environmentFiles

If permissions are wrong, the task may fail to start or the variables may not resolve as expected.

Region and ARN Details

For secrets and parameters, AWS documentation allows full ARNs, and in some same-region cases names can be used. In practice, full ARNs are the clearest option because they remove ambiguity.

That is especially helpful when you work across:

• multiple regions
• multiple accounts
• multiple deployment environments

ECS Console Versus JSON

You can define these settings in the ECS console, but the underlying task definition still becomes JSON with the same fields:

• 'environment'
• 'secrets'
• 'environmentFiles'

For infrastructure-as-code, those same concepts appear in CloudFormation, CDK, Terraform, or raw registration JSON.

Common Pitfalls

The biggest mistake is putting secrets into plain environment instead of using the secrets field.

Another mistake is forgetting IAM permissions on the task execution role. The task definition can be syntactically correct and still fail at runtime because ECS cannot retrieve the referenced secret or file.

People also confuse the task role and the task execution role. Secret retrieval for container startup commonly depends on the execution role configuration.

Finally, if you use many variables, think about maintainability. Large inline environment lists become hard to review, which is where environment files or a better config strategy help.

Summary

• Use environment for ordinary non-sensitive variables.
• Use secrets for values from Secrets Manager or Parameter Store.
• Use environmentFiles when file-based env configuration fits better.
• Make sure the task execution role can read the referenced secret or file.
• Prefer clear, reviewable configuration over large hardcoded secret-filled task definitions.