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

create_cloudwatch_log_group

bool

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

CloudWatch Log Group

cloudwatch_log_group_name

string

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

cloudwatch_log_group_use_name_prefix

bool

Use log group name as prefix. Default: false.

cloudwatch_log_group_retention_in_days

number

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

cloudwatch_log_group_kms_key_id

string

KMS Key ARN for log encryption. Default: null.

cloudwatch_log_group_class

string

Log class: STANDARD or INFREQUENT_ACCESS. Default: null.

Container Definition

name

string

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

image

string

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

cpu

number

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

memory

number

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

memoryReservation

number

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

essential

bool

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

command

list(string)

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

entrypoint

list(string)

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

workingDirectory

string

Working directory for commands. Default: null.

user

string

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

environment

list(object)

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

environmentFiles

list(object)

S3 files containing environment variables. Default: null.

secrets

list(object)

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

portMappings

list(object)

Port mappings for the container.

Show properties

containerPort

number

Container port number.

hostPort

number

Host port (leave blank for awsvpc mode).

protocol

string

tcp or udp.

name

string

Named port for Service Connect.

appProtocol

string

Application protocol for Service Connect.

containerPortRange

string

Port range for dynamic host port mapping.

Default: null.

mountPoints

list(object)

Volume mount points.

Show properties

sourceVolume

string

Volume name from task definition.

containerPath

string

Mount path in the container.

readOnly

bool

Mount as read-only.

Default: null.

volumesFrom

list(object)

Mount volumes from another container. Default: null.

Logging

enable_cloudwatch_logging

bool

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

enable_execute_command

bool

Enable ECS Exec for this container. Default: false.

logConfiguration

object

Custom log configuration (overrides CloudWatch default).

Show properties

logDriver

string

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

options

map(string)

Driver-specific options.

secretOptions

list(object)

Secrets for the log driver.

Default: {}.

firelensConfiguration

object

FireLens log router configuration.

Show properties

type

string

fluentd or fluentbit.

options

map(string)

FireLens router options.

Default: null.

Health Check

healthCheck

object

Container health check configuration.

Show properties

command

list(string)

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

interval

number

Seconds between checks. Default: 30.

timeout

number

Seconds to wait for a response. Default: 5.

retries

number

Failures before unhealthy. Default: 3.

startPeriod

number

Grace period for container startup (seconds).

Default: null.

Restart Policy

restartPolicy

object

Container restart policy.

Show properties

enabled

bool

Enable automatic restart. Default: true.

ignoredExitCodes

list(number)

Exit codes that should not trigger restart.

restartAttemptPeriod

number

Seconds to track restart attempts.

Default: { enabled = true }.

Resource Requirements

resourceRequirements

list(object)

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

Networking

hostname

string

Container hostname. Default: null.

dnsServers

list(string)

DNS server IP addresses. Default: null.

dnsSearchDomains

list(string)

DNS search domains. Default: null.

extraHosts

list(object)

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

links

list(string)

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

disableNetworking

bool

Disable networking within the container. Default: null.

Security

readonlyRootFilesystem

bool

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

privileged

bool

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

dockerSecurityOptions

list(string)

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

credentialSpecs

list(string)

gMSA credential specs for Windows containers. Default: null.

repositoryCredentials

object

Private registry credentials from Secrets Manager.

Show properties

credentialsParameter

string

Secrets Manager ARN containing registry credentials.

Default: null.

Container Behavior

dependsOn

list(object)

Container dependency conditions.

Show properties

containerName

string

required

Dependent container name.

condition

string

required

START, COMPLETE, SUCCESS, or HEALTHY.

Default: null.

startTimeout

number

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

stopTimeout

number

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

interactive

bool

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

pseudoTerminal

bool

Allocate a TTY. Default: false.

versionConsistency

string

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

Linux Parameters

linuxParameters

object

Linux kernel capabilities and configuration.

Show properties

capabilities

object

Add/drop Linux capabilities.

devices

list(object)

Host devices to expose.

initProcessEnabled

bool

Run an init process as PID 1.

maxSwap

number

Maximum swap memory in MiB.

sharedMemorySize

number

/dev/shm size in MiB.

swappiness

number

Swappiness (0–100).

tmpfs

list(object)

tmpfs mount configurations.

Default: {}.

ulimits

list(object)

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

systemControls

list(object)

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

Docker Labels

dockerLabels

map(string)

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

Context

service

string

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

operating_system_family

string

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

region

string

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

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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

Module Controls

CloudWatch Log Group

Container Definition

Logging

Health Check

Restart Policy

Resource Requirements

Networking

Security

Container Behavior

Linux Parameters

Docker Labels

Context