How to Use AWS Secrets Manager With ECS Fargate

Getting a secret into a Fargate container takes three things that live in different places: the secret in Secrets Manager, a secrets block in the task definition, and a permission on the task execution role. Miss the permission and the task fails to start with an access error. Get all three right and the next surprise is rotation: the secret changes in Secrets Manager, and the running tasks keep using the old value.

This guide covers the task definition setup, the IAM it needs, what happens on rotation, and the alternative of reading secrets at runtime, starting with the option where the secret is declared in code: Encore.

Secrets on Fargate at a glance

Each option is covered below, starting with Encore.

Declaring secrets in code with Encore

Encore combines an open source infrastructure SDK for TypeScript and Go with a platform that provisions and deploys into your own AWS or GCP account. A secret is a field in a secrets struct, and Encore loads it before your code runs:

// email/email.go
package email

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"encore.dev/beta/errs"
)

// Encore loads these at startup. On AWS the values live in Secrets Manager.
var secrets struct {
	PostmarkServerToken string
}

type SendParams struct {
	To      string
	Subject string
	Body    string
}

//encore:api private method=POST path=/email/send
func Send(ctx context.Context, p *SendParams) error {
	payload, _ := json.Marshal(map[string]string{
		"From":     "app@example.com",
		"To":       p.To,
		"Subject":  p.Subject,
		"TextBody": p.Body,
	})
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.postmarkapp.com/email", bytes.NewReader(payload))
	if err != nil {
		return err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("X-Postmark-Server-Token", secrets.PostmarkServerToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return &errs.Error{Code: errs.Unavailable, Message: fmt.Sprintf("postmark returned %d", resp.StatusCode)}
	}
	return nil
}

Set the value per environment type from the CLI. The values are stored per environment, and on AWS Encore replicates them into Secrets Manager in your account and injects them into the container as secret environment variables:

The secret is declared where it is used, with no task definition JSON or ARN to copy. Encore provisions an IAM role for the service, so there is no execution role policy to write. And a cloud deploy fails if a secret the code declares has no value for that environment, so a forgotten secret stops the release instead of a task that starts with an empty variable.

Local development uses the same declaration: encore run makes the local values available, and a .secrets.local.cue file can override one for your machine only. Shared values are never stored in the repository or in a .env file, so an AI coding agent working in the codebase sees which secrets a service declares but never sees the values in the files it works with, and encore secret list only shows which environments have a value; a .secrets.local.cue override is the exception, since it is a plaintext file in the app directory. Teams whose secrets must stay in an existing store can reference them through external vaults.

Option 1: the task definition secrets block

The standard way to inject a secret as an environment variable. Create the secret:

aws secretsmanager create-secret \
  --name prod/email \
  --secret-string file://secret.json

secret.json holds the JSON value, for example {"postmark_token":"..."}. Reading it from a file keeps the token out of shell history and the process list. Create the file outside the repository with owner-only permissions (umask 077), and delete it once the secret exists.

Reference it in the container definition. The key name after the ARN selects one field of a JSON secret, and the two trailing colons leave the version stage and version id at their defaults (the current version):

"secrets": [
  {
    "name": "POSTMARK_SERVER_TOKEN",
    "valueFrom": "arn:aws:secretsmanager:eu-west-1:123456789012:secret:prod/email-AbCdEf:postmark_token::"
  }
]

Then grant the task execution role access. The execution role is the one ECS uses to start the task, not the task role your code runs with:

{
  "Effect": "Allow",
  "Action": "secretsmanager:GetSecretValue",
  "Resource": "arn:aws:secretsmanager:eu-west-1:123456789012:secret:prod/email-*"
}

Add kms:Decrypt on the key if the secret uses a customer managed KMS key instead of the default aws/secretsmanager key. The wildcard after the name covers the six random characters Secrets Manager appends to every secret ARN.

Rotation is the limitation, because ECS resolves the value once, when the task starts. After a rotation, the running tasks keep the old value until you launch new ones, typically with aws ecs update-service --force-new-deployment. For database passwords rotated by Secrets Manager, that means a window where running tasks hold a password that may stop working, unless the rotation strategy keeps the previous one valid.

Option 2: read the secret at runtime

For secrets that rotate on their own schedule, read them from the application with the AWS SDK and cache the value for a few minutes. The task role, not the execution role, then needs secretsmanager:GetSecretValue. AWS also publishes caching clients for several languages that handle the refresh.

The cost is more code in every service, a dependency on Secrets Manager being reachable at runtime, an API charge per refresh, and AWS credentials on every developer laptop to run the service locally.

Good to know

• Secrets Manager costs $0.40 per secret per month plus $0.05 per 10,000 API calls, per the pricing page. Grouping related values into one JSON secret reduces the per-secret cost.
• Values set through the task definition show up as plain environment variables inside the container, so anything that logs the environment logs the secret.
• For non-secret configuration, plain environment entries in the task definition are free and easier to review.

How to choose

Use Encore when you want secrets declared next to the code that uses them, with the IAM role created for each service, deploys that fail on a missing value, and the same declaration working locally and in your own AWS account. Use the task definition secrets block for an existing ECS setup, and runtime reads with caching when a service must follow rotations without a restart.

Related guides

• How to manage secrets on AWS with an AI coding agent
• What is Amazon ECS?
• What is AWS Fargate?
• How to deploy to AWS without Kubernetes