Skip to content

aws.ecs-task-definition resource

Description

TaskDefinition manages one revision of an ECS task definition. A revision is registered whole by a single RegisterTaskDefinition call and is immutable afterward: every input except tags is fixed at registration, so any other change replaces the resource by registering a new revision of the family. Registering a family again never conflicts; the revision number auto-increments and is never reused. Deleting deregisters the revision, which makes it INACTIVE; tasks and services already running it keep working.

Family is required and must match ^[0-9A-Za-z_-]{1,255}$, a regular-expression and byte-length check enforced in Create rather than a declarative constraint. Cpu and memory are strings in the API, expressed as CPU units or vCPUs (for example "256", "0.5 vCPU") and MiB or GB (for example "1024", "1GB"); both are required for Fargate. The execution-role and task-role inputs take role ARNs.

Source: internal/service/ecs/task_definition_rsrc.go:44

Example usage:

imports: {
  aws: 'github.com/cloudboss/unobin-library-aws'
}

resources: {
  example: aws.ecs-task-definition {
    # Set input fields here.
  }
}

Inputs

family

string

required

container-definitions

list(object) 
list(
  object({
    name: string
    image: string
    environment: optional(map(string))
    command: optional(list(string))
    cpu: optional(integer)
    credential-specs: optional(list(string))
    depends-on: optional(
      list(
        object({
          condition: string
          container-name: string
        })
      )
    )
    disable-networking: optional(boolean)
    dns-search-domains: optional(list(string))
    dns-servers: optional(list(string))
    docker-labels: optional(map(string))
    docker-security-options: optional(list(string))
    entry-point: optional(list(string))
    environment-files: optional(
      list(
        object({
          type: string
          value: string
        })
      )
    )
    essential: optional(boolean)
    extra-hosts: optional(
      list(
        object({
          hostname: string
          ip-address: string
        })
      )
    )
    firelens-configuration: optional(
      object({
        type: string
        options: optional(map(string))
      })
    )
    health-check: optional(
      object({
        command: list(string)
        interval: optional(integer)
        retries: optional(integer)
        start-period: optional(integer)
        timeout: optional(integer)
      })
    )
    hostname: optional(string)
    interactive: optional(boolean)
    links: optional(list(string))
    linux-parameters: optional(
      object({
        capabilities: optional(
          object({
            add: optional(list(string))
            drop: optional(list(string))
          })
        )
        devices: optional(
          list(
            object({
              host-path: string
              container-path: optional(string)
              permissions: optional(list(string))
            })
          )
        )
        init-process-enabled: optional(boolean)
        max-swap: optional(integer)
        shared-memory-size: optional(integer)
        swappiness: optional(integer)
        tmpfs: optional(
          list(
            object({
              container-path: string
              size: integer
              mount-options: optional(list(string))
            })
          )
        )
      })
    )
    log-configuration: optional(
      object({
        log-driver: string
        options: optional(map(string))
        secret-options: optional(
          list(
            object({
              name: string
              value-from: string
            })
          )
        )
      })
    )
    memory: optional(integer)
    memory-reservation: optional(integer)
    mount-points: optional(
      list(
        object({
          container-path: optional(string)
          read-only: optional(boolean)
          source-volume: optional(string)
        })
      )
    )
    port-mappings: optional(
      list(
        object({
          app-protocol: optional(string)
          container-port: optional(integer)
          container-port-range: optional(string)
          host-port: optional(integer)
          name: optional(string)
          protocol: optional(string)
        })
      )
    )
    privileged: optional(boolean)
    pseudo-terminal: optional(boolean)
    readonly-root-filesystem: optional(boolean)
    repository-credentials: optional(
      object({
        credentials-parameter: string
      })
    )
    resource-requirements: optional(
      list(
        object({
          type: string
          value: string
        })
      )
    )
    restart-policy: optional(
      object({
        enabled: boolean
        ignored-exit-codes: optional(list(integer))
        restart-attempt-period: optional(integer)
      })
    )
    secrets: optional(
      list(
        object({
          name: string
          value-from: string
        })
      )
    )
    start-timeout: optional(integer)
    stop-timeout: optional(integer)
    system-controls: optional(
      list(
        object({
          namespace: optional(string)
          value: optional(string)
        })
      )
    )
    ulimits: optional(
      list(
        object({
          hard-limit: integer
          name: string
          soft-limit: integer
        })
      )
    )
    user: optional(string)
    version-consistency: optional(string)
    volumes-from: optional(
      list(
        object({
          read-only: optional(boolean)
          source-container: optional(string)
        })
      )
    )
    working-directory: optional(string)
  })
)

required

cpu

optional(string)

enable-fault-injection

optional(boolean)

ephemeral-storage

optional(object) 
optional(
  object({
    size-in-gib: integer
  })
)

execution-role-arn

optional(string)

ipc-mode

optional(string)

memory

optional(string)

network-mode

optional(string)

pid-mode

optional(string)

placement-constraints

list(object) 
list(
  object({
    type: string
    expression: optional(string)
  })
)

proxy-configuration

optional(object) 
optional(
  object({
    container-name: string
    properties: optional(map(string))
    type: optional(string)
  })
)

requires-compatibilities

list(string)

runtime-platform

optional(object) 
optional(
  object({
    cpu-architecture: optional(string)
    operating-system-family: optional(string)
  })
)

task-role-arn

optional(string)

volumes

list(object) 
list(
  object({
    name: string
    configured-at-launch: optional(boolean)
    host: optional(
      object({
        source-path: optional(string)
      })
    )
    docker-volume-configuration: optional(
      object({
        autoprovision: optional(boolean)
        driver: optional(string)
        driver-opts: optional(map(string))
        labels: optional(map(string))
        scope: optional(string)
      })
    )
    efs-volume-configuration: optional(
      object({
        file-system-id: string
        authorization-config: optional(
          object({
            access-point-id: optional(string)
            iam: optional(string)
          })
        )
        root-directory: optional(string)
        transit-encryption: optional(string)
        transit-encryption-port: optional(integer)
      })
    )
    fsx-windows-file-server-volume-configuration: optional(
      object({
        file-system-id: string
        root-directory: string
        authorization-config: optional(
          object({
            credentials-parameter: string
            domain: string
          })
        )
      })
    )
    s3files-volume-configuration: optional(
      object({
        file-system-arn: string
        access-point-arn: optional(string)
        root-directory: optional(string)
        transit-encryption-port: optional(integer)
      })
    )
  })
)

tags

map(string)

Input Constraints

Network mode rules

network-mode must be bridge, host, awsvpc, or none.

Rule logic
When
input.network-mode != null
Require
input.network-mode == 'bridge'
|| input.network-mode == 'host'
|| input.network-mode == 'awsvpc'
|| input.network-mode == 'none'

Ipc mode rules

ipc-mode must be host, task, or none.

Rule logic
When
input.ipc-mode != null
Require
input.ipc-mode == 'host'
|| input.ipc-mode == 'task'
|| input.ipc-mode == 'none'

Pid mode rules

pid-mode must be host or task.

Rule logic
When
input.pid-mode != null
Require
input.pid-mode == 'host'
|| input.pid-mode == 'task'

Requires compatibilities rules

a compatibility must be EC2, FARGATE, EXTERNAL, or MANAGED_INSTANCES.

Rule logic
For each
input.requires-compatibilities
Require
@each.value == 'EC2'
|| @each.value == 'FARGATE'
|| @each.value == 'EXTERNAL'
|| @each.value == 'MANAGED_INSTANCES'

Ephemeral storage rules

ephemeral-storage size-in-gib must be between 21 and 200.

Rule logic
When
input.ephemeral-storage.size-in-gib != null
Require
(input.ephemeral-storage.size-in-gib == null || input.ephemeral-storage.size-in-gib >= 21)
&& (input.ephemeral-storage.size-in-gib == null || input.ephemeral-storage.size-in-gib <= 200)

Proxy configuration rules

proxy-configuration type must be APPMESH.

Rule logic
When
input.proxy-configuration.type != null
Require
input.proxy-configuration.type == 'APPMESH'

Runtime platform rules

runtime-platform cpu-architecture must be X86_64 or ARM64.

Rule logic
When
input.runtime-platform.cpu-architecture != null
Require
input.runtime-platform.cpu-architecture == 'X86_64'
|| input.runtime-platform.cpu-architecture == 'ARM64'

runtime-platform operating-system-family must be LINUX or a WINDOWS_SERVER family.

Rule logic
When
input.runtime-platform.operating-system-family != null
Require
input.runtime-platform.operating-system-family == 'LINUX'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2016_FULL'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2019_CORE'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2019_FULL'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2004_CORE'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2022_CORE'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2022_FULL'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2025_CORE'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_2025_FULL'
|| input.runtime-platform.operating-system-family == 'WINDOWS_SERVER_20H2_CORE'

Placement constraints rules

placement-constraints allows at most 10 entries.

Rule logic
Require
input.placement-constraints == null
|| @core.length(input.placement-constraints) <= 10

a task definition placement constraint type must be memberOf.

Rule logic
For each
input.placement-constraints
Require
@each.value.type == 'memberOf'

a memberOf placement constraint requires an expression.

Rule logic
For each
input.placement-constraints
When
@each.value.type == 'memberOf'
Require
@each.value.expression != null

Container definitions rules

version-consistency must be enabled or disabled.

Rule logic
For each
input.container-definitions
When
@each.value.version-consistency != null
Require
@each.value.version-consistency == 'enabled'
|| @each.value.version-consistency == 'disabled'

Volumes rules

a docker volume scope must be task or shared.

Rule logic
For each
input.volumes
When
@each.value.docker-volume-configuration.scope != null
Require
@each.value.docker-volume-configuration.scope == 'task'
|| @each.value.docker-volume-configuration.scope == 'shared'

efs transit-encryption must be ENABLED or DISABLED.

Rule logic
For each
input.volumes
When
@each.value.efs-volume-configuration.transit-encryption != null
Require
@each.value.efs-volume-configuration.transit-encryption == 'ENABLED'
|| @each.value.efs-volume-configuration.transit-encryption == 'DISABLED'

efs transit-encryption-port must be between 1 and 65535.

Rule logic
For each
input.volumes
When
@each.value.efs-volume-configuration.transit-encryption-port != null
Require
(@each.value.efs-volume-configuration.transit-encryption-port == null || @each.value.efs-volume-configuration.transit-encryption-port >= 1)
&& (@each.value.efs-volume-configuration.transit-encryption-port == null || @each.value.efs-volume-configuration.transit-encryption-port <= 65535)

efs authorization-config iam must be ENABLED or DISABLED.

Rule logic
For each
input.volumes
When
@each.value.efs-volume-configuration.authorization-config.iam != null
Require
@each.value.efs-volume-configuration.authorization-config.iam == 'ENABLED'
|| @each.value.efs-volume-configuration.authorization-config.iam == 'DISABLED'

an fsx-windows-file-server volume requires authorization-config.

Rule logic
For each
input.volumes
When
@each.value.fsx-windows-file-server-volume-configuration != null
Require
@each.value.fsx-windows-file-server-volume-configuration.authorization-config != null

s3files transit-encryption-port must be between 1 and 65535.

Rule logic
For each
input.volumes
When
@each.value.s3files-volume-configuration.transit-encryption-port != null
Require
(@each.value.s3files-volume-configuration.transit-encryption-port == null || @each.value.s3files-volume-configuration.transit-encryption-port >= 1)
&& (@each.value.s3files-volume-configuration.transit-encryption-port == null || @each.value.s3files-volume-configuration.transit-encryption-port <= 65535)

Outputs

arn

string

revision

integer

arn-without-revision

string