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

Creating a Task Definition

Before you can run Docker containers on Amazon ECS, you need to create a task definition.

To create a new task definition

  1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.

  2. From the navigation bar, choose the region to register your task definition in.

  3. In the navigation pane, choose Task Definitions.

  4. On the Task Definitions page, select Create new Task Definition.

  5. (Optional) If you have a JSON representation of your task definition that you would like to use, complete the following steps:

    1. On the Create a Task Definition page, scroll to the bottom of the page and choose Configure via JSON.

    2. Paste your task definition JSON into the text area and choose Save.

    3. Verify your information and select Create.

  6. In the Task Definition Name field, enter a name for your task definition. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

  7. (Optional) In the Task Role field, choose an IAM role that provides permissions for containers in your task to make calls to AWS APIs on your behalf. For more information, see IAM Roles for Tasks.

    Note

    Only roles that have the Amazon EC2 Container Service Task Role trust relationship are shown here. For help creating an IAM role for your tasks, see Creating an IAM Role and Policy for your Tasks.

  8. (Optional) In the Network Mode field, choose the Docker network mode that you would like to use for the containers in your task. The available network modes correspond to those described in Network settings in the Docker run reference.

    The default Docker network mode is bridge. If the network mode is set to none, you cannot specify port mappings in your container definitions, and the task's containers do not have external connectivity. The host network mode offers the highest networking performance for containers because they use the host network stack instead of the virtualized network stack provided by the bridge mode; however, exposed container ports are mapped directly to the corresponding host port, so you cannot take advantage of dynamic host port mappings or run multiple instantiations of the same task on a single container instance if port mappings are used.

  9. For each container in your task definition, complete the following steps.

    1. Choose Add container.

    2. Fill out each required field and any optional fields to use in your container definitions (more container definition parameters are available in the Advanced container configuration menu). For more information, see Task Definition Parameters.

    3. Select Add to add your container to the task definition.

  10. (Optional) To define data volumes for your task, choose Add volume. For more information, see Using Data Volumes in Tasks.

    1. In the Name field, enter a name for your volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

    2. (Optional) In the Source Path field, enter the path on the host container instance to present to the container. If this you leave this field empty, then the Docker daemon assigns a host path for you. If you specify a source path, then the data volume persists at the specified location on the host container instance until you delete it manually. If the source path 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 to the container.

  11. Choose Create to finish.

Task Definition Template

An empty task definition template is shown below. You can use this template to create your task definition which can then be pasted into the console JSON input area or saved to a file and used with the AWS CLI --cli-input-json option. For more information about these parameters, see Task Definition Parameters.

{
    "family": "",
    "taskRoleArn": "",
    "networkMode": "",
    "containerDefinitions": [
        {
            "name": "",
            "image": "",
            "cpu": 0,
            "memory": 0,
            "memoryReservation": 0,
            "links": [
                ""
            ],
            "portMappings": [
                {
                    "containerPort": 0,
                    "hostPort": 0,
                    "protocol": ""
                }
            ],
            "essential": true,
            "entryPoint": [
                ""
            ],
            "command": [
                ""
            ],
            "environment": [
                {
                    "name": "",
                    "value": ""
                }
            ],
            "mountPoints": [
                {
                    "sourceVolume": "",
                    "containerPath": "",
                    "readOnly": true
                }
            ],
            "volumesFrom": [
                {
                    "sourceContainer": "",
                    "readOnly": true
                }
            ],
            "hostname": "",
            "user": "",
            "workingDirectory": "",
            "disableNetworking": true,
            "privileged": true,
            "readonlyRootFilesystem": true,
            "dnsServers": [
                ""
            ],
            "dnsSearchDomains": [
                ""
            ],
            "extraHosts": [
                {
                    "hostname": "",
                    "ipAddress": ""
                }
            ],
            "dockerSecurityOptions": [
                ""
            ],
            "dockerLabels": {
                "KeyName": ""
            },
            "ulimits": [
                {
                    "name": "",
                    "softLimit": 0,
                    "hardLimit": 0
                }
            ],
            "logConfiguration": {
                "logDriver": "",
                "options": {
                    "KeyName": ""
                }
            }
        }
    ],
    "volumes": [
        {
            "name": "",
            "host": {
                "sourcePath": ""
            }
        }
    ]
}

Note

You can generate the above task definition template with the following AWS CLI command.

$ aws ecs register-task-definition --generate-cli-skeleton