Creating a task definition using the
classic console
Amazon ECS has provided a new console experience for creating task definitions. For
more information, see Creating a task definition using the new
console.
You must use the new console to create a task definition for Windows containers on
Fargate with the WINDOWS_SERVER_2022_FULL, or
WINDOWS_SERVER_2022_CORE operating system.
Before running Docker containers on Amazon ECS, you must first create a task definition.
When you create a task definition, you can use it to define multiple containers and data
volumes. For more information about the available parameters for task definitions, see
Task definition parameters.
To create a new task definition (Classic Amazon ECS console)
Open the Amazon ECS console at
https://console.aws.amazon.com/ecs/.
-
In the navigation pane, choose task definitions,
Create new task definition.
-
On the Select compatibilities page, select the launch
type that your task is to use and choose Next step.
-
Follow the steps under one of the following tabs, according to the launch type
that you chose.
- Fargate launch type
-
Using the Fargate launch type compatibility
template
If you chose Fargate, complete the
following steps:
-
(Optional) If you have a JSON representation of your task
definition, complete the following steps:
-
On the Configure task and container
definitions page, scroll to the bottom of the
page and choose Configure via
JSON.
-
Paste your task definition JSON into the text area and
choose Save.
-
Verify your information and choose
Create.
Scroll to the bottom of the page and choose Configure
via JSON.
-
For Task Definition Name, type a name for
your task definition. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
-
(Optional) For Task Role, choose an IAM
role that provides permissions for containers in your task to make
calls to AWS API operations on your behalf. For more information, see IAM roles for tasks.
-
For Operating system family, choose the container operating system.
-
For Task execution IAM role, either select
your task execution role or choose Create new
role so that the console can create one for you. For more
information, see Amazon ECS task execution IAM role.
-
For Task size, choose a value for
Task memory (GB) and Task CPU
(vCPU). The table below shows the valid
combinations.
|
CPU value
|
Memory value
|
Operating systems supported for
AWS Fargate
|
|
256 (.25 vCPU)
|
512 MiB, 1 GB, 2 GB
|
Linux
|
|
512 (.5 vCPU)
|
1 GB, 2 GB, 3 GB, 4 GB
|
Linux
|
|
1024 (1 vCPU)
|
2 GB, 3 GB, 4 GB, 5 GB, 6 GB, 7 GB, 8 GB
|
Linux, Windows
|
|
2048 (2 vCPU)
|
Between 4 GB and 16 GB in 1 GB increments
|
Linux, Windows
|
|
4096 (4 vCPU)
|
Between 8 GB and 30 GB in 1 GB increments
|
Linux, Windows
|
|
8192 (8 vCPU)
This option requires Linux platform 1.4.0 or
later. |
Between 16 GB and 60 GB in 4 GB increments
|
Linux
|
|
16384 (16vCPU)
This option requires Linux platform 1.4.0 or
later. |
Between 32 GB and 120 GB in 8 GB increments
|
Linux
|
-
For each container in your task definition, complete the following
steps:
-
Choose Add container.
-
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.
-
Choose Add to add your container to
the task definition.
-
(Optional) For Service Integration, to configure the parameters for App Mesh integration, choose Enable App Mesh integration and then do the following:
-
For Mesh name, choose the existing App Mesh service mesh to use. If you don't see any meshes listed, then you need to create one first. For more information, see Service meshes in the AWS App Mesh User Guide.
This option is not available for Windows containers on Fargate.
-
For App Mesh endpoints, select one of the following options.
-
For Envoy image, enter 840364872350.dkr.ecr.us-west-2.amazonaws.com/aws-appmesh-envoy:v1.15.1.0-prod for all regions except me-south-1 and ap-east-1. You can replace us-west-2 with any Region except me-south-1 and ap-east-1.
If your application is in one of these regions, then you also need to replace 840364872350 with the appropriate value for your Region. For more information, see
Envoy image in the AWS App Mesh User Guide.
-
Choose Apply and then choose Confirm. This will add an Envoy proxy container to the task definition, as well as the settings to support it. If you selected Virtual node, it will also auto-populate
the App Mesh Proxy Configuration settings for the next step. If you selected Virtual gateway, then the Proxy Configuration is disabled, because it's not used for a virtual gateway.
-
(Optional) If you selected Virtual node in Service Integration, then for Proxy Configuration, verify all of the pre-populated values. For more information about these fields, see the JSON tab
in Update services.
-
(Optional) For Log Router Integration, you can add a
custom log routing configuration. Choose Enable FireLens
integration and then do the following:
-
For Type, choose the log router type to
use.
-
For Image, type the image URI for your
log router container. If you chose the fluentbit log router
type, the Image field
pre-populates with the AWS for Fluent Bit image. For more
information, see Using the AWS for Fluent Bit
image.
-
Choose Apply. This creates a new log
router container to the task definition named
log_router, and applies the settings to support
it. If you make changes to the log router integration fields,
choose Apply again to update the
FireLens container.
-
(Optional) To define data volumes for your task, choose
Add volume. For more information, see Using data volumes in tasks.
-
For Name, type a name for your
volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
-
In the Tags section, specify the key and value
for each tag to associate with the task definition. For more information,
see Tagging Your Amazon ECS Resources.
-
Choose Create.
- EC2 launch type
-
Using the
EC2 launch type compatibility template
If you chose EC2, complete the
following steps:
-
(Optional) If you have a JSON representation of your task
definition, complete the following steps:
-
On the Configure task and container
definitions page, scroll to the bottom of the
page and choose Configure via
JSON.
-
Paste your task definition JSON into the text area and
choose Save.
-
Verify your information and choose
Create.
Scroll to the bottom of the page and choose Configure
via JSON.
-
For task definition Name, type a name for
your task definition. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
-
(Optional) For Task Role, 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.
For tasks that use the EC2 launch type, these
permissions are usually granted by the Amazon ECS Container Instance
IAM role. For more information, see Amazon ECS container instance IAM role.
-
(Optional) For Network Mode, choose the
Docker network mode to use for the containers in your task. The
available network modes correspond to those that are described in
Network
settings in the Docker run reference. If you select
Enable App Mesh integration in a following
step, then you must select awsvpc.
The default Docker network mode is bridge. If the
network mode is set to none, you can't specify port
mappings in your container definitions. Moreover, the task's
containers don't have external connectivity. If the network mode is
awsvpc, the task is provided with an elastic
network interface. The host and awsvpc
network modes offer the highest networking performance for
containers. This is because they use the Amazon EC2 network stack,
instead of the virtualized network stack that's provided by the
bridge mode. However, exposed container ports are
mapped directly to the corresponding host port. Therefore, if port
mappings are used, you can't use dynamic host port mappings or run
multiple instantiations of the same task on a single container
instance.
-
(Optional) For Task execution role, choose an
IAM role that provides permissions for containers in your task to
make calls to AWS APIs on your behalf.
For tasks that use the EC2 launch type, these
permissions are usually granted by the Amazon ECS Container Instance
IAM role. This role is specified earlier as the Task
Role. There's no need to specify a task execution
role. For more information, seeAmazon ECS task execution IAM role.
-
(Optional) For Task size, choose a value for
Task memory (GB) and Task CPU
(vCPU). The Task CPU (vCPU) values that
are supported are between 128 CPU units (0.125 vCPUs) and 10240 CPU
units (10 vCPUs).
Task-level CPU and memory parameters are ignored for Windows
containers. We recommend specifying container-level resources
for Windows containers.
-
For each container in your task definition, complete the following
steps.
-
Choose Add container.
-
Enter each of the required fields 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.
-
Choose Add to add your container to
the task definition.
-
(Optional) For Constraint, you define how
tasks that are created from this task definition are placed in your
cluster. For tasks that use the EC2 launch type, you
can use constraints to place tasks based on Availability Zone,
instance type, or custom attributes. For more information, see Amazon ECS task placement
constraints.
-
(Optional) For Service Integration, to configure the parameters for App Mesh integration, choose Enable App Mesh integration and then do the following:
-
For Mesh name, choose the existing App Mesh service mesh to use. If you don't see any meshes listed, then you need to create one first. For more information, see Service meshes in the AWS App Mesh User Guide.
This option is not available for Windows containers on Fargate.
-
For App Mesh endpoints, select one of the following options.
-
For Envoy image, enter 840364872350.dkr.ecr.us-west-2.amazonaws.com/aws-appmesh-envoy:v1.15.1.0-prod for all regions except me-south-1 and ap-east-1. You can replace us-west-2 with any Region except me-south-1 and ap-east-1.
If your application is in one of these regions, then you also need to replace 840364872350 with the appropriate value for your Region. For more information, see
Envoy image in the AWS App Mesh User Guide.
-
Choose Apply and then choose Confirm. This will add an Envoy proxy container to the task definition, as well as the settings to support it. If you selected Virtual node, it will also auto-populate
the App Mesh Proxy Configuration settings for the next step. If you selected Virtual gateway, then the Proxy Configuration is disabled, because it's not used for a virtual gateway.
-
(Optional) If you selected Virtual node in Service Integration, then for Proxy Configuration, verify all of the pre-populated values. For more information about these fields, see the JSON tab
in Update services.
-
(Optional) For Log Router Integration, you can add a
custom log routing configuration. Choose Enable FireLens
integration and then do the following:
-
For Type, choose the log router type to
use.
-
For Image, type the image URI for your
log router container. If you chose the fluentbit log router
type, the Image field
pre-populates with the AWS for Fluent Bit image. For more
information, see Using the AWS for Fluent Bit
image.
-
Choose Apply. This creates a new log
router container to the task definition named
log_router, and applies the settings to support
it. If you make changes to the log router integration fields,
choose Apply again to update the
FireLens container.
-
(Optional) To define data volumes for your task, choose
Add volume. You can create either a bind
mount or Docker volume. For more information, see Using data volumes in tasks.
-
For Name, type a name for your
volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
-
(Optional) To create a bind mount volume, for
Source path, enter the path on the
host container instance to present to the container. If you
leave this field empty, the Docker daemon assigns a host
path for you. If you specify a source path, the data volume
persists at the specified location on the host container
instance until you delete it manually. If the source path
doesn't 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.
-
To create a Docker volume, select Specify a
volume driver.
-
For Driver, choose the Docker
volume driver to use. The driver value must match
the driver name provided by Docker. Use docker
plugin ls on your container instance to
retrieve the driver name.
-
For Scope, choose the option
that determines the lifecycle of the Docker volume.
Docker volumes that are scoped to a
task are automatically provisioned
when the task starts and destroyed when the task
stops. Docker volumes that are scoped as
shared persist after the task
stops.
-
Select Enable
auto-provisioning to have the Docker
volume created if it doesn't already exist. This
option is only available for volumes that specify
the shared scope.
-
For Driver options, specify
the driver-specific key values to use.
-
For Volume labels, specify
the custom metadata to add to your Docker
volume.
-
In the Tags section, specify the key and value
for each tag to associate with the task definition. For more information,
see Tagging Your Amazon ECS Resources.
-
Choose Create.
- External instance launch type
-
Using the external
instance launch type
If you chose External, complete the following
steps:
-
(Optional) If you have a JSON representation of your task
definition, complete the following steps:
-
On the Configure task and container
definitions page, scroll to the bottom of the
page and choose Configure via
JSON.
-
Paste your task definition JSON file into the text area
and choose Save.
-
Verify your information and choose
Create.
Scroll to the bottom of the page and choose Configure
via JSON.
-
For task definition Name, enter a name for
your task definition. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
-
(Optional) For Task Role, 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 and
IAM permissions for Amazon ECS Anywhere.
-
(Optional) For Network Mode, choose the
Docker network mode to use for the containers in your task. The
available network modes correspond to those that are 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 can't specify port
mappings in your container definitions, and the task's containers
don't have external connectivity. If the network mode is
awsvpc, the task is allocated an elastic network
interface. The host and awsvpc network
modes offer the highest networking performance for containers. This
is because they use the Amazon EC2 network stack, instead of the
virtualized network stack that's provided by the bridge
mode. However, exposed container ports are mapped directly to the
corresponding host port. Therefore, you can't use dynamic host port
mappings or run multiple instantiations of the same task on a single
container instance if port mappings are used.
-
(Optional) For Task execution role, choose an
IAM role that provides permissions for containers in your task to
make calls to AWS APIs on your behalf.
-
(Optional) For Task size, choose a value for
Task memory (GB) and Task CPU
(vCPU). Supported Task CPU (vCPU) values
are between 128 CPU units (0.125 vCPUs) and 10240 CPU units (10
vCPUs).
Task-level CPU and memory parameters are ignored for Windows
containers. We recommend specifying container-level resources
for Windows containers.
-
For each container in your task definition, complete the following
steps.
-
Choose Add container.
-
Enter each of the required fields 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.
-
Choose Add to add your container to
the task definition.
-
(Optional) For Constraint, you define how
tasks that are created from this task definition are placed in your
cluster. For more information, see Amazon ECS task placement
constraints.
-
(Optional) For Log Router Integration, you can add a
custom log routing configuration. Choose Enable FireLens
integration and then do the following:
-
For Type, choose the log router type to
use.
-
For Image, type the image URI for your
log router container. If you chose the fluentbit log router
type, the Image field
pre-populates with the AWS for Fluent Bit image. For more
information, see Using the AWS for Fluent Bit
image.
-
Choose Apply. This creates a new log
router container to the task definition named
log_router, and applies the settings to support
it. If you make changes to the log router integration fields,
choose Apply again to update the
FireLens container.
-
(Optional) To define data volumes for your task, choose
Add volume. You can create either a bind
mount or Docker volume. For more information, see Using data volumes in tasks.
-
For Name, type a name for your
volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
-
(Optional) To create a bind mount volume, for
Source path, enter the path on the
host container instance to present to the container. If you
leave this field empty, the Docker daemon assigns a host
path for you. If you specify a source path, the data volume
persists at the specified location on the host container
instance until you delete it manually. If the source path
doesn't 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.
-
To create a Docker volume, select Specify a
volume driver.
-
For Driver, choose the Docker
volume driver to use. The driver value must match
the driver name provided by Docker. Use docker
plugin ls on your container instance to
retrieve the driver name.
-
For Scope, choose the option
that determines the lifecycle of the Docker volume.
Docker volumes that are scoped to a
task are automatically provisioned
when the task starts and destroyed when the task
stops. Docker volumes that are scoped as
shared persist after the task
stops.
-
Select Enable
auto-provisioning to have the Docker
volume created if it does not already exist. This
option is only available for volumes that specify
the shared scope.
-
For Driver options, specify
the driver-specific key values to use.
-
For Volume labels, specify
the custom metadata to add to your Docker
volume.
-
In the Tags section, specify the key and value
for each tag to associate with the task definition. For more information,
see Tagging Your Amazon ECS Resources.
-
Choose Create.
To create a new task definition (AWS CLI)
Task definition template
An empty task definition template is shown as follows. 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, see Task definition parameters.
{
"family": "",
"taskRoleArn": "",
"executionRoleArn": "",
"networkMode": "none",
"containerDefinitions": [
{
"name": "",
"image": "",
"repositoryCredentials": {
"credentialsParameter": ""
},
"cpu": 0,
"memory": 0,
"memoryReservation": 0,
"links": [
""
],
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"protocol": "tcp"
}
],
"essential": true,
"entryPoint": [
""
],
"command": [
""
],
"environment": [
{
"name": "",
"value": ""
}
],
"environmentFiles": [
{
"value": "",
"type": "s3"
}
],
"mountPoints": [
{
"sourceVolume": "",
"containerPath": "",
"readOnly": true
}
],
"volumesFrom": [
{
"sourceContainer": "",
"readOnly": true
}
],
"linuxParameters": {
"capabilities": {
"add": [
""
],
"drop": [
""
]
},
"devices": [
{
"hostPath": "",
"containerPath": "",
"permissions": [
"mknod"
]
}
],
"initProcessEnabled": true,
"sharedMemorySize": 0,
"tmpfs": [
{
"containerPath": "",
"size": 0,
"mountOptions": [
""
]
}
],
"maxSwap": 0,
"swappiness": 0
},
"secrets": [
{
"name": "",
"valueFrom": ""
}
],
"dependsOn": [
{
"containerName": "",
"condition": "COMPLETE"
}
],
"startTimeout": 0,
"stopTimeout": 0,
"hostname": "",
"user": "",
"workingDirectory": "",
"disableNetworking": true,
"privileged": true,
"readonlyRootFilesystem": true,
"dnsServers": [
""
],
"dnsSearchDomains": [
""
],
"extraHosts": [
{
"hostname": "",
"ipAddress": ""
}
],
"dockerSecurityOptions": [
""
],
"interactive": true,
"pseudoTerminal": true,
"dockerLabels": {
"KeyName": ""
},
"ulimits": [
{
"name": "nofile",
"softLimit": 0,
"hardLimit": 0
}
],
"logConfiguration": {
"logDriver": "splunk",
"options": {
"KeyName": ""
},
"secretOptions": [
{
"name": "",
"valueFrom": ""
}
]
},
"healthCheck": {
"command": [
""
],
"interval": 0,
"timeout": 0,
"retries": 0,
"startPeriod": 0
},
"systemControls": [
{
"namespace": "",
"value": ""
}
],
"resourceRequirements": [
{
"value": "",
"type": "InferenceAccelerator"
}
],
"firelensConfiguration": {
"type": "fluentd",
"options": {
"KeyName": ""
}
}
}
],
"volumes": [
{
"name": "",
"host": {
"sourcePath": ""
},
"dockerVolumeConfiguration": {
"scope": "shared",
"autoprovision": true,
"driver": "",
"driverOpts": {
"KeyName": ""
},
"labels": {
"KeyName": ""
}
},
"efsVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"transitEncryption": "DISABLED",
"transitEncryptionPort": 0,
"authorizationConfig": {
"accessPointId": "",
"iam": "ENABLED"
}
},
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"authorizationConfig": {
"credentialsParameter": "",
"domain": ""
}
}
}
],
"placementConstraints": [
{
"type": "memberOf",
"expression": ""
}
],
"requiresCompatibilities": [
"EC2"
],
"cpu": "",
"memory": "",
"tags": [
{
"key": "",
"value": ""
}
],
"pidMode": "task",
"ipcMode": "task",
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "",
"properties": [
{
"name": "",
"value": ""
}
]
},
"inferenceAccelerators": [
{
"deviceName": "",
"deviceType": ""
}
],
"ephemeralStorage": {
"sizeInGiB": 0
},
"runtimePlatform": {
"cpuArchitecture": "X86_64",
"operatingSystemFamily": "WINDOWS_SERVER_20H2_CORE"
}
}
You can generate this task definition template using the following AWS CLI
command.
aws ecs register-task-definition --generate-cli-skeleton
