Amazon ECS task metadata endpoint version 4 - Amazon Elastic Container Service
Task metadata endpoint version 4 paths
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon ECS task metadata endpoint version 4

The Amazon ECS container agent injects an environment variable into each container, referred to as the task metadata endpoint which provides various task metadata and Docker stats to the container.

The task metadata and network rate stats are sent to CloudWatch Container Insights and can be viewed in the Amazon Web Services Management Console. For more information, see Monitor Amazon ECS containers using Container Insights with enhanced observability.

Note

Amazon ECS provides earlier versions of the task metadata endpoint. To avoid the need to create new task metadata endpoint versions in the future, additional metadata may be added to the version 4 output. We will not remove any existing metadata or change the metadata field names.

The environment variable is injected by default into the containers of Amazon ECS tasks launched on Amazon EC2 Linux instances that are running at least version 1.39.0 of the Amazon ECS container agent. For Amazon EC2 Windows instances that use awsvpc network mode, the Amazon ECS container agent must be at least version 1.54.0. For more information, see Amazon ECS Linux container instance management.

Note

You can add support for this feature on Amazon EC2 instances using older versions of the Amazon ECS container agent by updating the agent to the latest version. For more information, see Updating the Amazon ECS container agent.

Task metadata endpoint version 4 paths

The following task metadata endpoint paths are available to containers.

${ECS_CONTAINER_METADATA_URI_V4}

This path returns metadata for the container.

${ECS_CONTAINER_METADATA_URI_V4}/task

This path returns metadata for the task, including a list of the container IDs and names for all of the containers associated with the task. For more information about the response for this endpoint, see Amazon ECS task metadata V4 JSON response.

${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags

This path returns the metadata for the task included in the /task endpoint in addition to the task and container instance tags that can be retrieved using the ListTagsForResource API. Any errors received when retrieving the tag metadata will be included in the Errors field in the response.

Note

The Errors field is only in the response for tasks hosted on Amazon EC2 Linux instances running at least version 1.50.0 of the container agent. For Amazon EC2 Windows instances that use awsvpc network mode, the Amazon ECS container agent must be at least version 1.54.0

This endpoint requires the ecs.ListTagsForResource permission.

${ECS_CONTAINER_METADATA_URI_V4}/stats

This path returns Docker stats for the specific container. For more information about each of the returned stats, see ContainerStats in the Docker API documentation.

For Amazon ECS tasks that use the awsvpc or bridge network modes hosted on Amazon EC2 Linux instances running at least version 1.43.0 of the container agent, there will be additional network rate stats included in the response. For all other tasks, the response will only include the cumulative network stats.

${ECS_CONTAINER_METADATA_URI_V4}/task/stats

This path returns Docker stats for all of the containers associated with the task. This can be used by sidecar containers to extract network metrics. For more information about each of the returned stats, see ContainerStats in the Docker API documentation.

For Amazon ECS tasks that use the awsvpc or bridge network modes hosted on Amazon EC2 Linux instances running at least version 1.43.0 of the container agent, there will be additional network rate stats included in the response. For all other tasks, the response will only include the cumulative network stats.