Menu
Amazon EC2 Container Service
Developer Guide (API Version 2014-11-13)

Task Definition Parameters

Task definitions are split into four basic parts: the task family, the IAM task role, container definitions, and volumes. The family is the name of the task, and each family can have multiple revisions. The IAM task role specifies the permissions that containers in the task should have. Container definitions specify which image to use, how much CPU and memory the container are allocated, and many more options. Volumes allow you to share data between containers and even persist the data on the container instance when the containers are no longer running. The family and container definitions are required in a task definition, while volumes are optional.

Family

When you register a task definition, you give it a family, which is similar to a name for multiple versions of the task definition, specified with a revision number. The first task definition that is registered into a particular family is given a revision of 1, and any task definitions registered after that are given a later sequential revision number.

Task Role

When you register a task definition, you can provide a task role for an IAM role that allows the containers in the task permission to call the AWS APIs that are specified in its associated policies on your behalf. For more information, see IAM Roles for Tasks.

Container Definitions

When you register a task definition, you must specify a list of container definitions that are passed to the Docker daemon on a container instance. The following parameters are allowed in a container definition.

Standard Container Definition Parameters

The following task definition parameters are either required or used in most container definitions.

name

Type: string

Required: yes

The name of a container. If you are linking multiple containers together in a task definition, the name of one container can be entered in the links of another container to connect the containers. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed. This parameter maps to name in the Create a container section of the Docker Remote API and the --name option to docker run.

image

Type: string

Required: yes

The image used to start a container. This string is passed directly to the Docker daemon. Images in the Docker Hub registry are available by default. You can also specify other repositories with repository-url/image:tag. Up to 255 letters (uppercase and lowercase), numbers, hyphens, underscores, colons, periods, forward slashes, and number signs are allowed. This parameter maps to Image in the Create a container section of the Docker Remote API and the IMAGE parameter of docker run.

  • Images in Amazon ECR repositories use the full registry/repository:tag naming convention. For example, aws_account_id.dkr.ecr.us-east-1.amazonaws.com/my-web-app:latest

  • Images in official repositories on Docker Hub use a single name (for example, ubuntu or mongo).

  • Images in other repositories on Docker Hub are qualified with an organization name (for example, amazon/amazon-ecs-agent).

  • Images in other online repositories are qualified further by a domain name (for example, quay.io/assemblyline/ubuntu).

memory

Type: integer

Required: yes

The number of MiB of memory to reserve for the container. You must specify a non-zero integer for this parameter; the Docker daemon reserves a minimum of 4 MiB of memory for a container, so you should not specify fewer than 4 MiB of memory for your containers. If your container attempts to exceed the memory allocated here, the container is killed. This parameter maps to Memory in the Create a container section of the Docker Remote API and the --memory option to docker run.

portMappings

Type: object array

Required: no

Port mappings allow containers to access ports on the host container instance to send or receive traffic. This parameter maps to PortBindings in the Create a container section of the Docker Remote API and the --publish option to docker run.

Note

After a task reaches the RUNNING status, manual and automatic host and container port assignments are visible in the Network Bindings section of a container description of a selected task in the Amazon ECS console, or the networkBindings section of describe-tasks AWS CLI command output or DescribeTasks API responses.

hostPort

Type: integer

Required: no

The port number on the container instance to reserve for your container. You can specify a non-reserved host port for your container port mapping, or you can omit the hostPort (or set it to 0) while specifying a containerPort and your container will automatically receive a port in the ephemeral port range for your container instance operating system and Docker version.

The default ephemeral port range is 49153 to 65535, and this range is used for Docker versions prior to 1.6.0. For Docker version 1.6.0 and later, the Docker daemon tries to read the ephemeral port range from /proc/sys/net/ipv4/ip_local_port_range (which is 32768 to 61000 on the latest Amazon ECS-optimized AMI); if this kernel parameter is unavailable, the default ephemeral port range is used. You should not attempt to specify a host port in the ephemeral port range, since these are reserved for automatic assignment. In general, ports below 32768 are outside of the ephemeral port range.

The default reserved ports are 22 for SSH, the Docker ports 2375 and 2376, and the Amazon ECS container agent port 51678. Any host port that was previously user-specified for a running task is also reserved while the task is running (after a task stops, the host port is released). The current reserved ports are displayed in the remainingResources of describe-container-instances output, and a container instance may have up to 100 reserved ports at a time, including the default reserved ports (automatically assigned ports do not count toward the 100 reserved ports limit).

containerPort

Type: integer

Required: yes, when portMappings are used

The port number on the container that is bound to the user-specified or automatically assigned host port. If you specify a container port and not a host port, your container automatically receives a host port in the ephemeral port range (for more information, see hostPort). Port mappings that are automatically assigned in this way do not count toward the 100 reserved ports limit of a container instance.

protocol

Type: string

Required: no

The protocol used for the port mapping. Valid values are tcp and udp. The default is tcp.

Important

UDP support is only available on container instances that were launched with version 1.2.0 of the Amazon ECS container agent (such as the amzn-ami-2015.03.c-amazon-ecs-optimized AMI) or later, or with container agents that have been updated to version 1.3.0 or later. To update your container agent to the latest version, see Updating the Amazon ECS Container Agent.

If you are specifying a host port, use the following syntax:

"portMappings": [
    {
        "containerPort": integer,
        "hostPort": integer
    }
    ...
]

If you want an automatically assigned host port, use the following syntax:

"portMappings": [
    {
        "containerPort": integer
    }
    ...
]

Advanced Container Definition Parameters

The following advanced container definition parameters provide extended capabilities to the docker run command that is used to launch containers on your Amazon ECS container instances.

Environment

cpu

Type: integer

Required: no

The number of cpu units to reserve for the container. A container instance has 1,024 cpu units for every CPU core. This parameter specifies the minimum amount of CPU to reserve for a container, and containers share unallocated CPU units with other containers on the instance with the same ratio as their allocated amount. This parameter maps to CpuShares in the Create a container section of the Docker Remote API and the --cpu-shares option to docker run.

Note

You can determine the number of CPU units that are available per Amazon EC2 instance type by multiplying the vCPUs listed for that instance type on the Amazon EC2 Instances detail page by 1,024.

For example, if you run a single-container task on a single-core instance type with 512 CPU units specified for that container, and that is the only task running on the container instance, that container could use the full 1,024 CPU unit share at any given time. However, if you launched another copy of the same task on that container instance, each task would be guaranteed a minimum of 512 CPU units when needed, and each container could float to higher CPU usage if the other container was not using it, but if both tasks were 100% active all of the time, they would be limited to 512 CPU units.

The Docker daemon on the container instance uses the CPU value to calculate the relative CPU share ratios for running containers. For more information, see CPU share constraint in the Docker documentation. The minimum valid CPU share value that the Linux kernel will allow is 2; however, the CPU parameter is not required, and you can use CPU values below 2 in your container definitions. For CPU values below 2 (including null), the behavior varies based on your Amazon ECS container agent version:

  • Agent versions <= 1.1.0: Null and zero CPU values are passed to Docker as 0, which Docker then converts to 1,024 CPU shares. CPU values of 1 are passed to Docker as 1, which the Linux kernel converts to 2 CPU shares.

  • Agent versions >= 1.2.0: Null, zero, and CPU values of 1 are passed to Docker as 2.

essential

Type: Boolean

Required: no

If the essential parameter of a container is marked as true, and that container fails or stops for any reason, all other containers that are part of the task are stopped. If the essential parameter of a container is marked as false, then its failure does not affect the rest of the containers in a task. If this parameter is omitted, a container is assumed to be essential.

All tasks must have at least one essential container. If you have an application that is composed of multiple containers, you should group containers that are used for a common purpose into components, and separate the different components into multiple task definitions. For more information, see Application Architecture.

"essential": true|false
entryPoint

Important

Early versions of the Amazon ECS container agent do not properly handle entryPoint parameters. If you have problems using entryPoint , update your container agent or enter your commands and arguments as command array items instead.

Type: string array

Required: no

The entry point that is passed to the container. This parameter maps to Entrypoint in the Create a container section of the Docker Remote API and the --entrypoint option to docker run. For more information about the Docker ENTRYPOINT parameter, go to https://docs.docker.com/reference/builder/#entrypoint.

"entryPoint": ["string", ...]
command

Type: string array

Required: no

The command that is passed to the container. This parameter maps to Cmd in the Create a container section of the Docker Remote API and the COMMAND parameter to docker run. For more information about the Docker CMD parameter, go to https://docs.docker.com/reference/builder/#cmd.

"command": ["string", ...]
workingDirectory

Type: string

Required: no

The working directory in which to run commands inside the container. This parameter maps to WorkingDir in the Create a container section of the Docker Remote API and the --workdir option to docker run.

"workingDirectory": "string"
environment

Type: object array

Required: no

The environment variables to pass to a container. This parameter maps to Env in the Create a container section of the Docker Remote API and the --env option to docker run.

Important

We do not recommend using plain text environment variables for sensitive information, such as credential data.

name

Type: string

Required: yes, when environment is used

The name of the environment variable.

value

Type: string

Required: yes, when environment is used

The value of the environment variable.

"environment" : [
    { "name" : "string", "value" : "string" },
    { "name" : "string", "value" : "string" }
]

Network Settings

disableNetworking

Type: Boolean

Required: no

When this parameter is true, networking is disabled within the container. This parameter maps to NetworkDisabled in the Create a container section of the Docker Remote API.

"disableNetworking": true|false
links

Type: string array

Required: no

The link parameter allows containers to communicate with each other without the need for port mappings. The name:internalName construct is analogous to name:alias in Docker links. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed. For more information about linking Docker containers, go to https://docs.docker.com/userguide/dockerlinks/. This parameter maps to Links in the Create a container section of the Docker Remote API and the --link option to docker run.

Important

Containers that are collocated on a single container instance may be able to communicate with each other without requiring links or host port mappings. Network isolation is achieved on the container instance using security groups and VPC settings.

"links": ["name:internalName", ...]
hostname

Type: string

Required: no

The hostname to use for your container. This parameter maps to Hostname in the Create a container section of the Docker Remote API and the --hostname option to docker run.

"hostname": "string"
dnsServers

Type: Boolean

Required: no

A list of DNS servers that are presented to the container. This parameter maps to Dns in the Create a container section of the Docker Remote API and the --dns option to docker run.

Type: string array

Required: no

"dnsServers": ["string", ...]
dnsSearchDomains

Type: string array

Required: no

A list of DNS search domains that are presented to the container. This parameter maps to DnsSearch in the Create a container section of the Docker Remote API and the --dns-search option to docker run.

"dnsSearchDomains": ["string", ...]
extraHosts

Type: object array

Required: no

A list of hostnames and IP address mappings to append to the /etc/hosts file on the container. This parameter maps to ExtraHosts in the Create a container section of the Docker Remote API and the --add-host option to docker run.

"extraHosts": [
      {
        "hostname": "string",
        "ipAddress": "string"
      }
      ...
    ]
hostname

Type: string

Required: yes, when extraHosts are used

The hostname to use in the /etc/hosts entry.

ipAddress

Type: string

Required: yes, when extraHosts are used

The IP address to use in the /etc/hosts entry.

Storage and Logging

readonlyRootFilesystem

Type: Boolean

Required: no

When this parameter is true, the container is given read-only access to its root file system. This parameter maps to ReadonlyRootfs in the Create a container section of the Docker Remote API and the --read-only option to docker run.

"readonlyRootFilesystem": true|false
mountPoints

Type: object array

Required: no

The mount points for data volumes in your container. This parameter maps to Volumes in the Create a container section of the Docker Remote API and the --volume option to docker run.

sourceVolume

Type: string

Required: yes, when mountPoints are used

The name of the volume to mount.

containerPath

Type: string

Required: yes, when mountPoints are used

The path on the container to mount the host volume at.

readOnly

Type: boolean

Required: no

If this value is true, the container has read-only access to the volume. If this value is false, then the container can write to the volume. The default value is false.

"mountPoints": [
                {
                  "sourceVolume": "string",
                  "containerPath": "string",
                  "readOnly": true|false
                }
              ]
volumesFrom

Type: object array

Required: no

Data volumes to mount from another container. This parameter maps to VolumesFrom in the Create a container section of the Docker Remote API and the --volumes-from option to docker run.

sourceContainer

Type: string

Required: yes, when volumesFrom is used

The name of the container to mount volumes from.

readOnly

Type: Boolean

Required: no

If this value is true, the container has read-only access to the volume. If this value is false, then the container can write to the volume. The default value is false.

"volumesFrom": [
                {
                  "sourceContainer": "string",
                  "readOnly": true|false
                }
              ]
logConfiguration

Type: LogConfiguration object

Required: no

The log configuration specification for the container. This parameter maps to LogConfig in the Create a container section of the Docker Remote API and the --log-driver option to docker run. By default, containers use the same logging driver that the Docker daemon uses; however the container may use a different logging driver than the Docker daemon by specifying a log driver with this parameter in the container definition. To use a different logging driver for a container, the log system must be configured properly on the container instance (or on a different log server for remote logging options). For more information on the options for different supported log drivers, see Configure logging drivers in the Docker documentation.

For more information on using the awslogs log driver in task definitions to send your container logs to CloudWatch Logs, see Using the awslogs Log Driver.

Note

Amazon ECS currently supports a subset of the logging drivers available to the Docker daemon (shown in the valid values below). Currently unsupported log drivers may be available in future releases of the Amazon ECS container agent.

This parameter requires version 1.18 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command:

$ sudo docker version | grep "Server API version"

Note

The Amazon ECS container agent running on a container instance must register the logging drivers available on that instance with the ECS_AVAILABLE_LOGGING_DRIVERS environment variable before containers placed on that instance can use these log configuration options. For more information, see Amazon ECS Container Agent Configuration.

"logConfiguration": {
      "logDriver": "json-file"|"syslog"|"journald"|"gelf"|"fluentd"|"awslogs",
      "options": {"string": "string"
        ...}
logDriver

Type: string

Valid values: "json-file" | "syslog" | "journald" | "gelf" | "fluentd" | "awslogs"

Required: yes, when logConfiguration is used

The log driver to use for the container. The valid values listed above are log drivers that the Amazon ECS container agent can communicate with by default.

Note

If you have a custom driver that is not listed above that you would like to work with the Amazon ECS container agent, you can fork the Amazon ECS container agent project that is available on GitHub and customize it to work with that driver. We encourage you to submit pull requests for changes that you would like to have included. However, Amazon Web Services does not currently provide support for running modified copies of this software.

This parameter requires version 1.18 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command:

$ sudo docker version | grep "Server API version"
options

Type: string to string map

Required: no

The configuration options to send to the log driver. This parameter requires version 1.19 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command:

$ sudo docker version | grep "Server API version"

Security

privileged

Type: Boolean

Required: no

When this parameter is true, the container is given elevated privileges on the host container instance (similar to the root user). This parameter maps to Privileged in the Create a container section of the Docker Remote API and the --privileged option to docker run.

"privileged": true|false
user

Type: string

Required: no

The user name to use inside the container. This parameter maps to User in the Create a container section of the Docker Remote API and the --user option to docker run.

"user": "string"
dockerSecurityOptions

Type: string array

Required: no

A list of strings to provide custom labels for SELinux and AppArmor multi-level security systems. This parameter maps to SecurityOpt in the Create a container section of the Docker Remote API and the --security-opt option to docker run.

"dockerSecurityOptions": ["string", ...]

Note

The Amazon ECS container agent running on a container instance must register with the ECS_SELINUX_CAPABLE=true or ECS_APPARMOR_CAPABLE=true environment variables before containers placed on that instance can use these security options. For more information, see Amazon ECS Container Agent Configuration.

Resource Limits

ulimits

Type: object array

Required: no

A list of ulimits to set in the container. This parameter maps to Ulimits in the Create a container section of the Docker Remote API and the --ulimit option to docker run. This parameter requires version 1.18 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command:

$ sudo docker version | grep "Server API version"
"ulimits": [
      {
        "name": "core"|"cpu"|"data"|"fsize"|"locks"|"memlock"|"msgqueue"|"nice"|"nofile"|"nproc"|"rss"|"rtprio"|"rttime"|"sigpending"|"stack",
        "softLimit": integer,
        "hardLimit": integer
      }
      ...
    ]
name

Type: string

Valid values: "core" | "cpu" | "data" | "fsize" | "locks" | "memlock" | "msgqueue" | "nice" | "nofile" | "nproc" | "rss" | "rtprio" | "rttime" | "sigpending" | "stack"

Required: yes, when ulimits are used

The type of the ulimit.

hardLimit

Type: integer

Required: yes, when ulimits are used

The hard limit for the ulimit type.

softLimit

Type: integer

Required: yes, when ulimits are used

The soft limit for the ulimit type.

Docker Labels

dockerLabels

Type: string to string map

Required: no

A key/value map of labels to add to the container. This parameter maps to Labels in the Create a container section of the Docker Remote API and the --label option to docker run. This parameter requires version 1.18 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command:

$ sudo docker version | grep "Server API version"
"dockerLabels": {"string": "string"
      ...}

Volumes

When you register a task definition, you can optionally specify a list of volumes that will be passed to the Docker daemon on a container instance and become available for other containers on the same container instance to access. For more information, see Using Data Volumes in Tasks. The following parameters are allowed in a container definition:

name

Type: string

Required: yes

The name of the volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed. This name is referenced in the sourceVolume parameter of container definition mountPoints.

host

Type: string

Required: no

The contents of the host parameter determine whether your data volume persists on the host container instance and where it is stored. If the host parameter is empty, then the Docker daemon assigns a host path for your data volume, but the data is not guaranteed to persist after the containers associated with it stop running.

By default, Docker-managed volumes are created in /var/lib/docker/vfs/dir/. You can change this default location by writing OPTIONS="-g=/my/path/for/docker/volumes" to /etc/sysconfig/docker on the container instance.

sourcePath

Type: string

Required: no

The path on the host container instance that is presented to the container. If this parameter is empty, then the Docker daemon assigns a host path for you.

If the host parameter contains a sourcePath file location, then the data volume persists at the specified location on the host container instance until you delete it manually. If the sourcePath value does not exist on the host container instance, the Docker daemon creates it. If the location does exist, the contents of the source path folder are exported.

[
  {
    "name": "string",
    "host": {
      "sourcePath": "string"
    }
  }
]