Container Definition Module Inputs

The container definition sub-module creates a single container definition for use within a task definition. It also manages the associated CloudWatch log group.

module "ecs_container_definition" {
  source  = "terraform-aws-modules/ecs/aws//modules/container-definition"
  version = "~> 7.0"

  name      = "my-app"
  cpu       = 512
  memory    = 1024
  essential = true
  image     = "public.ecr.aws/aws-containers/ecsdemo-frontend:776fd50"

  portMappings = [
    {
      name          = "my-app"
      containerPort = 80
      protocol      = "tcp"
    }
  ]

  tags = { Environment = "dev" }
}

This module is used internally by the service module for each container in container_definitions. You can also use it standalone to generate container definition JSON.

Module Controls

bool

Create a CloudWatch log group for this container. Default: true.

CloudWatch Log Group

string

Custom log group name. Default: null (auto-generated).

bool

Use log group name as prefix. Default: false.

number

Log retention in days. Set to 0 to keep logs indefinitely. Default: 14.

string

KMS Key ARN for log encryption. Default: null.

string

Log class: STANDARD or INFREQUENT_ACCESS. Default: null.

Container Definition

string

Container name (up to 255 letters, numbers, underscores, hyphens). Default: null.

string

Docker image URI. Supports Docker Hub, ECR, and any registry in repository-url/image:tag or repository-url/image@digest format. Default: null.

number

CPU units to reserve. Optional for Fargate tasks (task-level CPU is required). Default: null.

number

Hard memory limit in MiB. Container is killed if exceeded. Default: null.

number

Soft memory limit in MiB. Docker tries to maintain this but allows burst. Default: null.

bool

If true, all other containers stop when this container fails. Default: null.

list(string)

Command passed to the container (overrides Docker CMD). Default: null.

list(string)

Entry point (overrides Docker ENTRYPOINT). Default: null.

string

Working directory for commands. Default: null.

string

User to run as inside the container. Formats: user, user:group, uid, uid:gid. Default: null.

list(object)

Environment variables as a list of { name, value } objects. Default: null.

list(object)

S3 files containing environment variables. Default: null.

list(object)

Secrets from Secrets Manager or SSM Parameter Store. Each entry has name and valueFrom. Default: null.

list(object)

Port mappings for the container.

Show properties

number

Container port number.

number

Host port (leave blank for awsvpc mode).

string

tcp or udp.

string

Named port for Service Connect.

string

Application protocol for Service Connect.

string

Port range for dynamic host port mapping.

Default: null.

list(object)

Volume mount points.

Show properties

string

Volume name from task definition.

string

Mount path in the container.

bool

Mount as read-only.

Default: null.

list(object)

Mount volumes from another container. Default: null.

Logging

bool

Configure CloudWatch logging for this container. Set to false when using FireLens or other log drivers. Default: true.

bool

Enable ECS Exec for this container. Default: false.

object

Custom log configuration (overrides CloudWatch default).

Show properties

string

Log driver (e.g., awslogs, awsfirelens, splunk).

map(string)

Driver-specific options.

list(object)

Secrets for the log driver.

Default: {}.

object

FireLens log router configuration.

Show properties

string

fluentd or fluentbit.

map(string)

FireLens router options.

Default: null.

Health Check

object

Container health check configuration.

Show properties

list(string)

Health check command (e.g., ["CMD-SHELL", "curl -f http://localhost/health"]). Default: [].

number

Seconds between checks. Default: 30.

number

Seconds to wait for a response. Default: 5.

number

Failures before unhealthy. Default: 3.

number

Grace period for container startup (seconds).

Default: null.

Restart Policy

object

Container restart policy.

Show properties

bool

Enable automatic restart. Default: true.

list(number)

Exit codes that should not trigger restart.

number

Seconds to track restart attempts.

Default: { enabled = true }.

Resource Requirements

list(object)

GPU resource requirements. Each entry has type (always GPU) and value (number of GPUs). Default: null.

Networking

string

Container hostname. Default: null.

list(string)

DNS server IP addresses. Default: null.

list(string)

DNS search domains. Default: null.

list(object)

Additional /etc/hosts entries with hostname and ipAddress. Default: null.

list(string)

Container links (bridge network mode only). Default: null.

bool

Disable networking within the container. Default: null.

Security

bool

Give container read-only access to root filesystem. Default: true.

bool

Give container elevated host privileges (similar to root). Default: false.

list(string)

SELinux/AppArmor labels (not valid for Fargate). Default: null.

list(string)

gMSA credential specs for Windows containers. Default: null.

object

Private registry credentials from Secrets Manager.

Show properties

string

Secrets Manager ARN containing registry credentials.

Default: null.

Container Behavior

list(object)

Container dependency conditions.

Show properties

string

required

Dependent container name.

string

required

START, COMPLETE, SUCCESS, or HEALTHY.

Default: null.

number

Seconds to wait before giving up on dependency resolution. Default: 30.

number

Seconds to wait before forcefully killing the container on stop. Default: 120.

bool

Allocate stdin/tty (for interactive applications). Default: false.

bool

Allocate a TTY. Default: false.

string

Whether ECS resolves image tags to digests: enabled or disabled. Default: "disabled".

Linux Parameters

object

Linux kernel capabilities and configuration.

Show properties

object

Add/drop Linux capabilities.

list(object)

Host devices to expose.

bool

Run an init process as PID 1.

number

Maximum swap memory in MiB.

number

/dev/shm size in MiB.

number

Swappiness (0–100).

list(object)

tmpfs mount configurations.

Default: {}.

list(object)

Container ulimit settings (name, softLimit, hardLimit). Default: null.

list(object)

Namespaced kernel parameters (namespace, value). Default: null.

Docker Labels

map(string)

Key/value labels to add to the container. Default: null.

Context

string

Service name associated with this container definition. Used in auto-generated CloudWatch log group names. Default: null.

string

OS family for the task: LINUX or WINDOWS_SERVER_*. Default: "LINUX".

string

AWS region. Defaults to provider region. Default: null.

map(string)

Tags for all resources. Default: {}.

Root Module

Cluster Module

Service Module

Container Definition Module

Express Service Module

Module Controls

CloudWatch Log Group

Container Definition

Logging

Health Check

Restart Policy

Resource Requirements

Networking

Security

Container Behavior

Linux Parameters

Docker Labels

Context

​Module Controls

​CloudWatch Log Group

​Container Definition

​Logging

​Health Check

​Restart Policy

​Resource Requirements

​Networking

​Security

​Container Behavior

​Linux Parameters

​Docker Labels

​Context

Module Controls

CloudWatch Log Group

Container Definition

Logging

Health Check

Restart Policy

Resource Requirements

Networking

Security

Container Behavior

Linux Parameters

Docker Labels

Context