Task definitions

This page was generated from content adapted from the AWS Developer Guide

Task definition parameters

Note Task-level CPU and memory parameters are ignored for Windows containers. We recommend specifying container-level resources for Windows containers.
Note Starting April 15, 2023, AWS will not onboard new customers to Amazon Elastic Inference (EI), and will help current customers migrate their workloads to options that offer better price and performance. After April 15, 2023, new customers will not be able to launch instances with Amazon EI accelerators in Amazon SageMaker, Amazon ECS, or Amazon EC2. However, customers who have used Amazon EI at least once during the past 30-day period are considered current customers and will be able to continue using the service.
Important Don't add personally identifiable information or other confidential or sensitive information in tags. Tags are accessible to many AWS services, including billing. Tags aren't intended to be used for private or sensitive data.
Note This parameter is not supported for Windows containers or tasks using the Fargate launch type.
Note This parameter is not supported for Windows containers or tasks using the Fargate launch type.

Working with GPUs on Amazon ECS

Important If your GPU requirements aren't specified in the task definition, the task uses the default Docker runtime.

Using video transcoding on Amazon ECS

Note For instructions on how to run video transcoding workloads in containers other than Amazon ECS, see the Xilinx documentation.
Important If the task definition lists devices that the EC2 instance doesn't have, the task fails to run. When the task fails, the following error message appears in the stoppedReason: CannotStartContainerError: Error response from daemon: error gathering device information while adding custom device "/dev/dri/renderD130": no such file or directory.

Task networking

Important If you're using Amazon ECS tasks hosted on AWS Fargate, see Fargate task networking in the Amazon Elastic Container Service User Guide for AWS Fargate for networking information that's relevant to your instances.

Using the awslogs log driver

Note The type of information that is logged by the containers in your task depends mostly on their ENTRYPOINT command. By default, the logs that are captured show the command output that you typically might see in an interactive terminal if you ran the container locally, which are the STDOUT and STDERR I/O streams. The awslogs log driver simply passes these logs from Docker to CloudWatch Logs. For more information about how Docker logs are processed, including alternative ways to capture different file data or streams, see View logs for a container or service in the Docker documentation.
Note If you aren't using the Amazon ECS optimized AMI (with at least version 1.9.0-1 of the ecs-init package) for your container instances, you also need to specify that the awslogs logging driver is available on the container instance when you start the agent by using the following environment variable in your docker run statement or environment variable file. For more information, see Installing the Amazon ECS container agent.
Note To use the awslogs-create-group option to have your log group created, your task execution IAM role policy or EC2 instance role policy must include the logs:CreateLogGroup permission.

Private registry authentication for tasks

Important If your task definition references an image that's stored in Amazon ECR, this topic doesn't apply. For more information, see Using Amazon ECR Images with Amazon ECS in the Amazon Elastic Container Registry User Guide.
Note When using the Amazon ECS API, AWS CLI, or AWS SDK, if the secret exists in the same AWS Region as the task that you're launching then you can use either the full ARN or name of the secret. If the secret exists in a different account, the full ARN of the secret must be specified. When using the AWS Management Console, the full ARN of the secret must be specified always.
Note Another method of enabling private registry authentication uses Amazon ECS container agent environment variables to authenticate to private registries. This method is only supported for tasks hosted on Amazon EC2 instances. For more information, see Private registry authentication for container instances.

Passing environment variables

Important We recommend storing your sensitive data in either AWS Secrets Manager secrets or AWS Systems Manager Parameter Store parameters. For more information, see Passing sensitive data to a container. Environment variables specified in the task definition are readable by all users and roles that are allowed the DescribeTaskDefinition action for the task definition. Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply. See the below section Required IAM permissions.

PreviousClusters NextAccount settings

Last updated 1 year ago

Was this helpful?

Task definition parameters

Note Task-level CPU and memory parameters are ignored for Windows containers. We recommend specifying container-level resources for Windows containers.

Note Starting April 15, 2023, AWS will not onboard new customers to Amazon Elastic Inference (EI), and will help current customers migrate their workloads to options that offer better price and performance. After April 15, 2023, new customers will not be able to launch instances with Amazon EI accelerators in Amazon SageMaker, Amazon ECS, or Amazon EC2. However, customers who have used Amazon EI at least once during the past 30-day period are considered current customers and will be able to continue using the service.

Important Don't add personally identifiable information or other confidential or sensitive information in tags. Tags are accessible to many AWS services, including billing. Tags aren't intended to be used for private or sensitive data.

Note This parameter is not supported for Windows containers or tasks using the Fargate launch type.

Using video transcoding on Amazon ECS

Note For instructions on how to run video transcoding workloads in containers other than Amazon ECS, see the Xilinx documentation.

Important If the task definition lists devices that the EC2 instance doesn't have, the task fails to run. When the task fails, the following error message appears in the stoppedReason: CannotStartContainerError: Error response from daemon: error gathering device information while adding custom device "/dev/dri/renderD130": no such file or directory.

Using the awslogs log driver

Note The type of information that is logged by the containers in your task depends mostly on their ENTRYPOINT command. By default, the logs that are captured show the command output that you typically might see in an interactive terminal if you ran the container locally, which are the STDOUT and STDERR I/O streams. The awslogs log driver simply passes these logs from Docker to CloudWatch Logs. For more information about how Docker logs are processed, including alternative ways to capture different file data or streams, see View logs for a container or service in the Docker documentation.

Note If you aren't using the Amazon ECS optimized AMI (with at least version 1.9.0-1 of the ecs-init package) for your container instances, you also need to specify that the awslogs logging driver is available on the container instance when you start the agent by using the following environment variable in your docker run statement or environment variable file. For more information, see Installing the Amazon ECS container agent.

Note To use the awslogs-create-group option to have your log group created, your task execution IAM role policy or EC2 instance role policy must include the logs:CreateLogGroup permission.

Private registry authentication for tasks

Important If your task definition references an image that's stored in Amazon ECR, this topic doesn't apply. For more information, see Using Amazon ECR Images with Amazon ECS in the Amazon Elastic Container Registry User Guide.

Note When using the Amazon ECS API, AWS CLI, or AWS SDK, if the secret exists in the same AWS Region as the task that you're launching then you can use either the full ARN or name of the secret. If the secret exists in a different account, the full ARN of the secret must be specified. When using the AWS Management Console, the full ARN of the secret must be specified always.

Note Another method of enabling private registry authentication uses Amazon ECS container agent environment variables to authenticate to private registries. This method is only supported for tasks hosted on Amazon EC2 instances. For more information, see Private registry authentication for container instances.

Passing environment variables

Important We recommend storing your sensitive data in either AWS Secrets Manager secrets or AWS Systems Manager Parameter Store parameters. For more information, see Passing sensitive data to a container. Environment variables specified in the task definition are readable by all users and roles that are allowed the DescribeTaskDefinition action for the task definition. Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply. See the below section Required IAM permissions.