# Task metadata available for Amazon ECS tasks on EC2 The Amazon ECS container agent provides a method to retrieve various task metadata and [Docker stats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats). This is referred to as the task metadata endpoint. The following versions are available: + Task metadata endpoint version 4 – Provides a variety of metadata and Docker stats to containers. Can also provide network rate data. Available for Amazon ECS tasks launched on Amazon EC2 Linux instances 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 task metadata endpoint version 4](task-metadata-endpoint-v4.md). + Task metadata endpoint version 3 – Provides a variety of metadata and Docker stats to containers. Available for Amazon ECS tasks launched on Amazon EC2 Linux instances running at least version `1.21.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 task metadata endpoint version 3](task-metadata-endpoint-v3.md). + Task metadata endpoint version 2 – Available for Amazon ECS tasks launched on Amazon EC2 Linux instances running at least version `1.17.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 task metadata endpoint version 2](task-metadata-endpoint-v2.md). If your Amazon ECS task is hosted on Amazon EC2, or if your task uses the `host` network mode and is hosted on Amazon ECS Managed Instances, you can also access task host metadata using the [Instance Metadata Service (IMDS) endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). The following command, when run from within the instance hosting the task, lists the ID of the host instance. ``` curl http://169.254.169.254/latest/meta-data/instance-id ``` If your Amazon ECS task is hosted on Amazon EC2 and in an IPv6-only configuration, you can access task host metadata using the IPv6 IMDS endpoint. The following command, when run from within the instance hosting the task, lists the ID of the host instance over IPv6. ``` curl http://[fd00:ec2::254]/latest/meta-data/instance-id ``` To access the IPv6 IMDS endpoint, enable the IPv6 IMDS endpoint on your container instance and also configure the metadata service endpoint mode using the IMDS credential provider for your chosen SDK to `IPv6`. For more information about enabling the IPv6 IMDS endpoint for your container instance, see [Configure the Instance Metadata Service options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html) in *Amazon EC2 User Guide*. For more information about IMDS credential provider for SDKs, see [IMDS credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html) in the *AWS SDKs and Tools Reference Guide*. **Note** The IPv6 IMDS endpoint is not accessible when the `awsvpcTrunking` account setting is enabled. To access container instance IAM role credentials when `awsvpcTrunking` is enabled, you can use a task IAM role instead. For more information about task IAM roles, see [Amazon ECS task IAM role](task-iam-roles.md). The information you can obtain from the endpoint is divided into categories such as `instance-id`. For more information about the different categories of host instance metadata you can obtain using the endpoint, see [Instance metadata categories ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html#instancedata-data-categories). # 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](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats) to the container. The task metadata and network rate stats are sent to CloudWatch Container Insights and can be viewed in the AWS Management Console. For more information, see [Monitor Amazon ECS containers using Container Insights with enhanced observability](cloudwatch-container-insights.md). **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](manage-linux.md). **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](ecs-agent-update.md). For task metadata example output, see [Amazon ECS task metadata v4 examples](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-examples.html). ## 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](task-metadata-endpoint-v4-response.md). `${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. 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. When using the `${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags` endpoint, be aware that each call makes up to two API requests to `ecs:ListTagsForResource` (one for container instance tags and one for task tags) and that any sidecar containers in the task may make these calls on your behalf. Frequent endpoint calls can result in API throttling. Consider implementing caching or batching strategies to reduce the frequency of calls, especially in high-traffic applications, and debugging API throttling issues using AWS CloudTrail. For information about throttling limits for the `ListTagsForResource` API, see [Request throttling for the Amazon ECS API](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/request-throttling.html) in the *Amazon Elastic Container Service API Reference*. For more information about debugging Amazon ECS API calls using AWS CloudTrail, see [Log Amazon ECS API calls using AWS CloudTrail](logging-using-cloudtrail.md). `${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](https://docs.docker.com/engine/api/v1.30/#operation/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](https://docs.docker.com/engine/api/v1.30/#operation/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. # Amazon ECS task metadata V4 JSON response The following information is returned from the task metadata endpoint (`${ECS_CONTAINER_METADATA_URI_V4}/task`) JSON response. This includes metadata associated with the task in addition to the metadata for each container within the task. `Cluster` The Amazon Resource Name (ARN) or short name of the Amazon ECS cluster to which the task belongs. `ServiceName` The name of the service to which the task belongs. ServiceName will appear for Amazon EC2 and Amazon ECS Anywhere container instances if the task is associated with a service. The `ServiceName` metadata is only included when using Amazon ECS container agent version `1.63.1` or later. `VPCID` The VPC ID of the Amazon EC2 container instance. This field only appears for Amazon EC2 instances. The `VPCID` metadata is only included when using Amazon ECS container agent version `1.63.1` or later. `TaskARN` The Amazon Resource Name (ARN) of the task to which the container belongs. `Family` The family of the Amazon ECS task definition for the task. `Revision` The revision of the Amazon ECS task definition for the task. `DesiredStatus` The desired status for the task from Amazon ECS. `KnownStatus` The known status for the task from Amazon ECS. `Limits` The resource limits specified at the task level, such as CPU (expressed in vCPUs) and memory. This parameter is omitted if no resource limits are defined. `PullStartedAt` The timestamp for when the first container image pull began. `PullStoppedAt` The timestamp for when the last container image pull finished. `AvailabilityZone` The Availability Zone the task is in. The Availability Zone metadata is only available for Fargate tasks using platform version 1.4 or later (Linux) or 1.0.0 (Windows). `LaunchType` The launch type the task is using. When using cluster capacity providers, this indicates whether the task is using Fargate or EC2 infrastructure. This `LaunchType` metadata is only included when using Amazon ECS Linux container agent version `1.45.0` or later (Linux) or 1.0.0 or later (Windows). `Containers` A list of container metadata for each container associated with the task. `DockerId` The Docker ID for the container. When you use Fargate, the id is a 32-digit hex followed by a 10 digit number. `Name` The name of the container as specified in the task definition. `DockerName` The name of the container supplied to Docker. The Amazon ECS container agent generates a unique name for the container to avoid name collisions when multiple copies of the same task definition are run on a single instance. `Image` The image for the container. `ImageID` The SHA-256 digest of the image manifest. This is the digest that can be used to pull the image using the format `repository-url/image@sha256:digest`. `Ports` Any ports exposed for the container. This parameter is omitted if there are no exposed ports. `Labels` Any labels applied to the container. This parameter is omitted if there are no labels applied. `DesiredStatus` The desired status for the container from Amazon ECS. `KnownStatus` The known status for the container from Amazon ECS. `ExitCode` The exit code for the container. This parameter is omitted if the container has not exited. `Limits` The resource limits specified at the container level, such as CPU (expressed in CPU units) and memory. This parameter is omitted if no resource limits are defined. `CreatedAt` The time stamp for when the container was created. This parameter is omitted if the container has not been created yet. `StartedAt` The time stamp for when the container started. This parameter is omitted if the container has not started yet. `FinishedAt` The time stamp for when the container stopped. This parameter is omitted if the container has not stopped yet. `Type` The type of the container. Containers that are specified in your task definition are of type `NORMAL`. You can ignore other container types, which are used for internal task resource provisioning by the Amazon ECS container agent. `LogDriver` The log driver the container is using. This `LogDriver` metadata is only included when using Amazon ECS Linux container agent version `1.45.0` or later. `LogOptions` The log driver options defined for the container. This `LogOptions` metadata is only included when using Amazon ECS Linux container agent version `1.45.0` or later. `ContainerARN` The Amazon Resource Name (ARN) of the container. This `ContainerARN` metadata is only included when using Amazon ECS Linux container agent version `1.45.0` or later. `Networks` The network information for the container, such as the network mode and IP address. This parameter is omitted if no network information is defined. `RestartCount` The number of times the container has been restarted. The `RestartCount` metadata is included only if a restart policy is enabled for the container. For more information, see [Restart individual containers in Amazon ECS tasks with container restart policies](container-restart-policy.md). `ExecutionStoppedAt` The time stamp for when the tasks `DesiredStatus` moved to `STOPPED`. This occurs when an essential container moves to `STOPPED`. # Amazon ECS task metadata v4 examples The following examples show example outputs from each of the task metadata endpoints. ## Example container metadata response When querying the `${ECS_CONTAINER_METADATA_URI_V4}` endpoint you are returned only metadata about the container itself. The following is an example output from a task that runs as part of a service (MyService). ``` { "DockerId": "ea32192c8553fbff06c9340478a2ff089b2bb5646fb718b4ee206641c9086d66", "Name": "curl", "DockerName": "ecs-curltest-24-curl-cca48e8dcadd97805600", "Image": "111122223333.dkr.ecr.us-west-2.amazonaws.com/curltest:latest", "ImageID": "sha256:d691691e9652791a60114e67b365688d20d19940dde7c4736ea30e660d8d3553", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/8f03e41243824aea923aca126495f665", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "24" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 10, "Memory": 128 }, "CreatedAt": "2020-10-02T00:15:07.620912337Z", "StartedAt": "2020-10-02T00:15:08.062559351Z", "Type": "NORMAL", "LogDriver": "awslogs", "LogOptions": { "awslogs-create-group": "true", "awslogs-group": "/ecs/metadata", "awslogs-region": "us-west-2", "awslogs-stream": "ecs/curl/8f03e41243824aea923aca126495f665" }, "ContainerARN": "arn:aws:ecs:us-west-2:111122223333:container/0206b271-b33f-47ab-86c6-a0ba208a70a9", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.100" ], "AttachmentIndex": 0, "MACAddress": "0e:9e:32:c7:48:85", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-100.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] } ``` ## Example task metadata response When querying the `${ECS_CONTAINER_METADATA_URI_V4}/task` endpoint you are returned metadata about the task the container is part of in addition to the metadata for each container within the task. The following is an example output. ``` { "Cluster": "default", "TaskARN": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "Family": "curltest", "ServiceName": "MyService", "Revision": "26", "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "PullStartedAt": "2020-10-02T00:43:06.202617438Z", "PullStoppedAt": "2020-10-02T00:43:06.31288465Z", "AvailabilityZone": "us-west-2d", "VPCID": "vpc-1234567890abcdef0", "LaunchType": "EC2", "Containers": [ { "DockerId": "598cba581fe3f939459eaba1e071d5c93bb2c49b7d1ba7db6bb19deeb70d8e38", "Name": "~internal~ecs~pause", "DockerName": "ecs-curltest-26-internalecspause-e292d586b6f9dade4a00", "Image": "amazon/amazon-ecs-pause:0.1.0", "ImageID": "", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "~internal~ecs~pause", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "26" }, "DesiredStatus": "RESOURCES_PROVISIONED", "KnownStatus": "RESOURCES_PROVISIONED", "Limits": { "CPU": 0, "Memory": 0 }, "CreatedAt": "2020-10-02T00:43:05.602352471Z", "StartedAt": "2020-10-02T00:43:06.076707576Z", "Type": "CNI_PAUSE", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.61" ], "AttachmentIndex": 0, "MACAddress": "0e:10:e2:01:bd:91", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] }, { "DockerId": "ee08638adaaf009d78c248913f629e38299471d45fe7dc944d1039077e3424ca", "Name": "curl", "DockerName": "ecs-curltest-26-curl-a0e7dba5aca6d8cb2e00", "Image": "111122223333.dkr.ecr.us-west-2.amazonaws.com/curltest:latest", "ImageID": "sha256:d691691e9652791a60114e67b365688d20d19940dde7c4736ea30e660d8d3553", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "26" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 10, "Memory": 128 }, "CreatedAt": "2020-10-02T00:43:06.326590752Z", "StartedAt": "2020-10-02T00:43:06.767535449Z", "Type": "NORMAL", "LogDriver": "awslogs", "LogOptions": { "awslogs-create-group": "true", "awslogs-group": "/ecs/metadata", "awslogs-region": "us-west-2", "awslogs-stream": "ecs/curl/158d1c8083dd49d6b527399fd6414f5c" }, "ContainerARN": "arn:aws:ecs:us-west-2:111122223333:container/abb51bdd-11b4-467f-8f6c-adcfe1fe059d", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.61" ], "AttachmentIndex": 0, "MACAddress": "0e:10:e2:01:bd:91", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] } ] } ``` ## Example task with tags metadata response When querying the `${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags` endpoint you are returned metadata about the task, including the task and container instance tags. The following is an example output. ``` { "Cluster": "default", "TaskARN": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "Family": "curltest", "ServiceName": "MyService", "Revision": "26", "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "PullStartedAt": "2020-10-02T00:43:06.202617438Z", "PullStoppedAt": "2020-10-02T00:43:06.31288465Z", "AvailabilityZone": "us-west-2d", "VPCID": "vpc-1234567890abcdef0", "TaskTags": { "tag-use": "task-metadata-endpoint-test" }, "ContainerInstanceTags":{ "tag_key":"tag_value" }, "LaunchType": "EC2", "Containers": [ { "DockerId": "598cba581fe3f939459eaba1e071d5c93bb2c49b7d1ba7db6bb19deeb70d8e38", "Name": "~internal~ecs~pause", "DockerName": "ecs-curltest-26-internalecspause-e292d586b6f9dade4a00", "Image": "amazon/amazon-ecs-pause:0.1.0", "ImageID": "", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "~internal~ecs~pause", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "26" }, "DesiredStatus": "RESOURCES_PROVISIONED", "KnownStatus": "RESOURCES_PROVISIONED", "Limits": { "CPU": 0, "Memory": 0 }, "CreatedAt": "2020-10-02T00:43:05.602352471Z", "StartedAt": "2020-10-02T00:43:06.076707576Z", "Type": "CNI_PAUSE", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.61" ], "AttachmentIndex": 0, "MACAddress": "0e:10:e2:01:bd:91", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] }, { "DockerId": "ee08638adaaf009d78c248913f629e38299471d45fe7dc944d1039077e3424ca", "Name": "curl", "DockerName": "ecs-curltest-26-curl-a0e7dba5aca6d8cb2e00", "Image": "111122223333.dkr.ecr.us-west-2.amazonaws.com/curltest:latest", "ImageID": "sha256:d691691e9652791a60114e67b365688d20d19940dde7c4736ea30e660d8d3553", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "26" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 10, "Memory": 128 }, "CreatedAt": "2020-10-02T00:43:06.326590752Z", "StartedAt": "2020-10-02T00:43:06.767535449Z", "Type": "NORMAL", "LogDriver": "awslogs", "LogOptions": { "awslogs-create-group": "true", "awslogs-group": "/ecs/metadata", "awslogs-region": "us-west-2", "awslogs-stream": "ecs/curl/158d1c8083dd49d6b527399fd6414f5c" }, "ContainerARN": "arn:aws:ecs:us-west-2:111122223333:container/abb51bdd-11b4-467f-8f6c-adcfe1fe059d", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.61" ], "AttachmentIndex": 0, "MACAddress": "0e:10:e2:01:bd:91", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] } ] } ``` ## Example task with tags with an error metadata response When querying the `${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags` endpoint you are returned metadata about the task, including the task and container instance tags. If there is an error retrieving the tagging data, the error is returned in the response. The following is an example output for when the IAM role associated with the container instance doesn't have the `ecs:ListTagsForResource` permission allowed. ``` { "Cluster": "default", "TaskARN": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "Family": "curltest", "ServiceName": "MyService", "Revision": "26", "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "PullStartedAt": "2020-10-02T00:43:06.202617438Z", "PullStoppedAt": "2020-10-02T00:43:06.31288465Z", "AvailabilityZone": "us-west-2d", "VPCID": "vpc-1234567890abcdef0", "Errors": [ { "ErrorField": "ContainerInstanceTags", "ErrorCode": "AccessDeniedException", "ErrorMessage": "User: arn:aws:sts::111122223333:assumed-role/ecsInstanceRole/i-0744a608689EXAMPLE is not authorized to perform: ecs:ListTagsForResource on resource: arn:aws:ecs:us-west-2:111122223333:container-instance/default/2dd1b186f39845a584488d2ef155c131", "StatusCode": 400, "RequestId": "cd597ef0-272b-4643-9bd2-1de469870fa6", "ResourceARN": "arn:aws:ecs:us-west-2:111122223333:container-instance/default/2dd1b186f39845a584488d2ef155c131" }, { "ErrorField": "TaskTags", "ErrorCode": "AccessDeniedException", "ErrorMessage": "User: arn:aws:sts::111122223333:assumed-role/ecsInstanceRole/i-0744a608689EXAMPLE is not authorized to perform: ecs:ListTagsForResource on resource: arn:aws:ecs:us-west-2:111122223333:task/default/9ef30e4b7aa44d0db562749cff4983f3", "StatusCode": 400, "RequestId": "862c5986-6cd2-4aa6-87cc-70be395531e1", "ResourceARN": "arn:aws:ecs:us-west-2:111122223333:task/default/9ef30e4b7aa44d0db562749cff4983f3" } ], "LaunchType": "EC2", "Containers": [ { "DockerId": "598cba581fe3f939459eaba1e071d5c93bb2c49b7d1ba7db6bb19deeb70d8e38", "Name": "~internal~ecs~pause", "DockerName": "ecs-curltest-26-internalecspause-e292d586b6f9dade4a00", "Image": "amazon/amazon-ecs-pause:0.1.0", "ImageID": "", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "~internal~ecs~pause", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "26" }, "DesiredStatus": "RESOURCES_PROVISIONED", "KnownStatus": "RESOURCES_PROVISIONED", "Limits": { "CPU": 0, "Memory": 0 }, "CreatedAt": "2020-10-02T00:43:05.602352471Z", "StartedAt": "2020-10-02T00:43:06.076707576Z", "Type": "CNI_PAUSE", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.61" ], "AttachmentIndex": 0, "MACAddress": "0e:10:e2:01:bd:91", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] }, { "DockerId": "ee08638adaaf009d78c248913f629e38299471d45fe7dc944d1039077e3424ca", "Name": "curl", "DockerName": "ecs-curltest-26-curl-a0e7dba5aca6d8cb2e00", "Image": "111122223333.dkr.ecr.us-west-2.amazonaws.com/curltest:latest", "ImageID": "sha256:d691691e9652791a60114e67b365688d20d19940dde7c4736ea30e660d8d3553", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/158d1c8083dd49d6b527399fd6414f5c", "com.amazonaws.ecs.task-definition-family": "curltest", "com.amazonaws.ecs.task-definition-version": "26" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 10, "Memory": 128 }, "CreatedAt": "2020-10-02T00:43:06.326590752Z", "StartedAt": "2020-10-02T00:43:06.767535449Z", "Type": "NORMAL", "LogDriver": "awslogs", "LogOptions": { "awslogs-create-group": "true", "awslogs-group": "/ecs/metadata", "awslogs-region": "us-west-2", "awslogs-stream": "ecs/curl/158d1c8083dd49d6b527399fd6414f5c" }, "ContainerARN": "arn:aws:ecs:us-west-2:111122223333:container/abb51bdd-11b4-467f-8f6c-adcfe1fe059d", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.61" ], "AttachmentIndex": 0, "MACAddress": "0e:10:e2:01:bd:91", "IPv4SubnetCIDRBlock": "10.0.2.0/24", "PrivateDNSName": "ip-10-0-2-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "10.0.2.1/24" } ] } ] } ``` ## Example container stats response When querying the `${ECS_CONTAINER_METADATA_URI_V4}/stats` endpoint you are returned network metrics for the container. For Amazon ECS tasks that use the `awsvpc` or `bridge` network modes hosted on Amazon EC2 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. The following is an example output from an Amazon ECS task on Amazon EC2 that uses the `bridge` network mode. ``` { "read": "2020-10-02T00:51:13.410254284Z", "preread": "2020-10-02T00:51:12.406202398Z", "pids_stats": { "current": 3 }, "blkio_stats": { "io_service_bytes_recursive": [ ], "io_serviced_recursive": [ ], "io_queue_recursive": [ ], "io_service_time_recursive": [ ], "io_wait_time_recursive": [ ], "io_merged_recursive": [ ], "io_time_recursive": [ ], "sectors_recursive": [ ] }, "num_procs": 0, "storage_stats": { }, "cpu_stats": { "cpu_usage": { "total_usage": 360968065, "percpu_usage": [ 182359190, 178608875 ], "usage_in_kernelmode": 40000000, "usage_in_usermode": 290000000 }, "system_cpu_usage": 13939680000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "precpu_stats": { "cpu_usage": { "total_usage": 360968065, "percpu_usage": [ 182359190, 178608875 ], "usage_in_kernelmode": 40000000, "usage_in_usermode": 290000000 }, "system_cpu_usage": 13937670000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "memory_stats": { "usage": 1806336, "max_usage": 6299648, "stats": { "active_anon": 606208, "active_file": 0, "cache": 0, "dirty": 0, "hierarchical_memory_limit": 134217728, "hierarchical_memsw_limit": 268435456, "inactive_anon": 0, "inactive_file": 0, "mapped_file": 0, "pgfault": 4185, "pgmajfault": 0, "pgpgin": 2926, "pgpgout": 2778, "rss": 606208, "rss_huge": 0, "total_active_anon": 606208, "total_active_file": 0, "total_cache": 0, "total_dirty": 0, "total_inactive_anon": 0, "total_inactive_file": 0, "total_mapped_file": 0, "total_pgfault": 4185, "total_pgmajfault": 0, "total_pgpgin": 2926, "total_pgpgout": 2778, "total_rss": 606208, "total_rss_huge": 0, "total_unevictable": 0, "total_writeback": 0, "unevictable": 0, "writeback": 0 }, "limit": 134217728 }, "name": "/ecs-curltest-26-curl-c2e5f6e0cf91b0bead01", "id": "5fc21e5b015f899d22618f8aede80b6d70d71b2a75465ea49d9462c8f3d2d3af", "networks": { "eth0": { "rx_bytes": 84, "rx_packets": 2, "rx_errors": 0, "rx_dropped": 0, "tx_bytes": 84, "tx_packets": 2, "tx_errors": 0, "tx_dropped": 0 } }, "network_rate_stats": { "rx_bytes_per_sec": 0, "tx_bytes_per_sec": 0 } } ``` ## Example task stats response When querying the `${ECS_CONTAINER_METADATA_URI_V4}/task/stats` endpoint you are returned network metrics about the task the container is part of. The following is an example output. ``` { "01999f2e5c6cf4df3873f28950e6278813408f281c54778efec860d0caad4854": { "read": "2020-10-02T00:51:32.51467703Z", "preread": "2020-10-02T00:51:31.50860463Z", "pids_stats": { "current": 1 }, "blkio_stats": { "io_service_bytes_recursive": [ ], "io_serviced_recursive": [ ], "io_queue_recursive": [ ], "io_service_time_recursive": [ ], "io_wait_time_recursive": [ ], "io_merged_recursive": [ ], "io_time_recursive": [ ], "sectors_recursive": [ ] }, "num_procs": 0, "storage_stats": { }, "cpu_stats": { "cpu_usage": { "total_usage": 177232665, "percpu_usage": [ 13376224, 163856441 ], "usage_in_kernelmode": 0, "usage_in_usermode": 160000000 }, "system_cpu_usage": 13977820000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "precpu_stats": { "cpu_usage": { "total_usage": 177232665, "percpu_usage": [ 13376224, 163856441 ], "usage_in_kernelmode": 0, "usage_in_usermode": 160000000 }, "system_cpu_usage": 13975800000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "memory_stats": { "usage": 532480, "max_usage": 6279168, "stats": { "active_anon": 40960, "active_file": 0, "cache": 0, "dirty": 0, "hierarchical_memory_limit": 9223372036854771712, "hierarchical_memsw_limit": 9223372036854771712, "inactive_anon": 0, "inactive_file": 0, "mapped_file": 0, "pgfault": 2033, "pgmajfault": 0, "pgpgin": 1734, "pgpgout": 1724, "rss": 40960, "rss_huge": 0, "total_active_anon": 40960, "total_active_file": 0, "total_cache": 0, "total_dirty": 0, "total_inactive_anon": 0, "total_inactive_file": 0, "total_mapped_file": 0, "total_pgfault": 2033, "total_pgmajfault": 0, "total_pgpgin": 1734, "total_pgpgout": 1724, "total_rss": 40960, "total_rss_huge": 0, "total_unevictable": 0, "total_writeback": 0, "unevictable": 0, "writeback": 0 }, "limit": 4073377792 }, "name": "/ecs-curltest-26-internalecspause-a6bcc3dbadfacfe85300", "id": "01999f2e5c6cf4df3873f28950e6278813408f281c54778efec860d0caad4854", "networks": { "eth0": { "rx_bytes": 84, "rx_packets": 2, "rx_errors": 0, "rx_dropped": 0, "tx_bytes": 84, "tx_packets": 2, "tx_errors": 0, "tx_dropped": 0 } }, "network_rate_stats": { "rx_bytes_per_sec": 0, "tx_bytes_per_sec": 0 } }, "5fc21e5b015f899d22618f8aede80b6d70d71b2a75465ea49d9462c8f3d2d3af": { "read": "2020-10-02T00:51:32.512771349Z", "preread": "2020-10-02T00:51:31.510597736Z", "pids_stats": { "current": 3 }, "blkio_stats": { "io_service_bytes_recursive": [ ], "io_serviced_recursive": [ ], "io_queue_recursive": [ ], "io_service_time_recursive": [ ], "io_wait_time_recursive": [ ], "io_merged_recursive": [ ], "io_time_recursive": [ ], "sectors_recursive": [ ] }, "num_procs": 0, "storage_stats": { }, "cpu_stats": { "cpu_usage": { "total_usage": 379075681, "percpu_usage": [ 191355275, 187720406 ], "usage_in_kernelmode": 60000000, "usage_in_usermode": 310000000 }, "system_cpu_usage": 13977800000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "precpu_stats": { "cpu_usage": { "total_usage": 378825197, "percpu_usage": [ 191104791, 187720406 ], "usage_in_kernelmode": 60000000, "usage_in_usermode": 310000000 }, "system_cpu_usage": 13975800000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "memory_stats": { "usage": 1814528, "max_usage": 6299648, "stats": { "active_anon": 606208, "active_file": 0, "cache": 0, "dirty": 0, "hierarchical_memory_limit": 134217728, "hierarchical_memsw_limit": 268435456, "inactive_anon": 0, "inactive_file": 0, "mapped_file": 0, "pgfault": 5377, "pgmajfault": 0, "pgpgin": 3613, "pgpgout": 3465, "rss": 606208, "rss_huge": 0, "total_active_anon": 606208, "total_active_file": 0, "total_cache": 0, "total_dirty": 0, "total_inactive_anon": 0, "total_inactive_file": 0, "total_mapped_file": 0, "total_pgfault": 5377, "total_pgmajfault": 0, "total_pgpgin": 3613, "total_pgpgout": 3465, "total_rss": 606208, "total_rss_huge": 0, "total_unevictable": 0, "total_writeback": 0, "unevictable": 0, "writeback": 0 }, "limit": 134217728 }, "name": "/ecs-curltest-26-curl-c2e5f6e0cf91b0bead01", "id": "5fc21e5b015f899d22618f8aede80b6d70d71b2a75465ea49d9462c8f3d2d3af", "networks": { "eth0": { "rx_bytes": 84, "rx_packets": 2, "rx_errors": 0, "rx_dropped": 0, "tx_bytes": 84, "tx_packets": 2, "tx_errors": 0, "tx_dropped": 0 } }, "network_rate_stats": { "rx_bytes_per_sec": 0, "tx_bytes_per_sec": 0 } } } ``` # Amazon ECS task metadata endpoint version 3 **Important** The task metadata version 3 endpoint is no longer being actively maintained. We recommend that you update the task metadata version 4 endpoint to get the latest metadata endpoint information. For more information, see [Amazon ECS task metadata endpoint version 4](task-metadata-endpoint-v4.md). If you are using Amazon ECS tasks hosted on AWS Fargate, see [Amazon ECS task metadata endpoint version 3 for tasks on Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v3-fargate.html). Beginning with version 1.21.0 of the Amazon ECS container agent, the agent injects an environment variable called `ECS_CONTAINER_METADATA_URI` into each container in a task. When you query the task metadata version 3 endpoint, various task metadata and [Docker stats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) are available to tasks. For tasks that use the `bridge` network mode, network metrics are available when querying the `/stats` endpoints. The task metadata endpoint version 3 feature is enabled by default for tasks that use Fargate on platform version v1.3.0 or later and tasks that use EC2 and are launched on Amazon EC2 Linux infrastructure running at least version 1.21.0 of the Amazon ECS container agent or on Amazon EC2 Windows infrastructure running at least version `1.54.0` of the Amazon ECS container agent and use `awsvpc` network mode. For more information, see [Amazon ECS Linux container instance management](manage-linux.md). You can add support for this feature on older container instances by updating the agent to the latest version. For more information, see [Updating the Amazon ECS container agent](ecs-agent-update.md). **Important** For tasks using Fargate and platform versions prior to v1.3.0, the task metadata version 2 endpoint is supported. For more information, see [Amazon ECS task metadata endpoint version 2](task-metadata-endpoint-v2.md). ## Task Metadata endpoint version 3 paths The following task metadata endpoints are available to containers: `${ECS_CONTAINER_METADATA_URI}` This path returns metadata JSON for the container. `${ECS_CONTAINER_METADATA_URI}/task` This path returns metadata JSON 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 v3 JSON response](task-metadata-endpoint-v3-response.md). `${ECS_CONTAINER_METADATA_URI}/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. `${ECS_CONTAINER_METADATA_URI}/stats` This path returns Docker stats JSON for the specific Docker container. For more information about each of the returned stats, see [ContainerStats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) in the Docker API documentation. `${ECS_CONTAINER_METADATA_URI}/task/stats` This path returns Docker stats JSON for all of the containers associated with the task. For more information about each of the returned stats, see [ContainerStats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) in the Docker API documentation. # Amazon ECS task metadata v3 JSON response The following information is returned from the task metadata endpoint (`${ECS_CONTAINER_METADATA_URI}/task`) JSON response. `Cluster` The Amazon Resource Name (ARN) or short name of the Amazon ECS cluster to which the task belongs. `TaskARN` The Amazon Resource Name (ARN) of the task to which the container belongs. `Family` The family of the Amazon ECS task definition for the task. `Revision` The revision of the Amazon ECS task definition for the task. `DesiredStatus` The desired status for the task from Amazon ECS. `KnownStatus` The known status for the task from Amazon ECS. `Limits` The resource limits specified at the task level, such as CPU (expressed in vCPUs) and memory. This parameter is omitted if no resource limits are defined. `PullStartedAt` The timestamp for when the first container image pull began. `PullStoppedAt` The timestamp for when the last container image pull finished. `AvailabilityZone` The Availability Zone the task is in. The Availability Zone metadata is only available for Fargate tasks using platform version 1.4 or later (Linux) or 1.0.0 or later (Windows). `Containers` A list of container metadata for each container associated with the task. `DockerId` The Docker ID for the container. `Name` The name of the container as specified in the task definition. `DockerName` The name of the container supplied to Docker. The Amazon ECS container agent generates a unique name for the container to avoid name collisions when multiple copies of the same task definition are run on a single instance. `Image` The image for the container. `ImageID` The SHA-256 digest of the image manifest. This is the digest that can be used to pull the image using the format `repository-url/image@sha256:digest`. `Ports` Any ports exposed for the container. This parameter is omitted if there are no exposed ports. `Labels` Any labels applied to the container. This parameter is omitted if there are no labels applied. `DesiredStatus` The desired status for the container from Amazon ECS. `KnownStatus` The known status for the container from Amazon ECS. `ExitCode` The exit code for the container. This parameter is omitted if the container has not exited. `Limits` The resource limits specified at the container level, such as CPU (expressed in CPU units) and memory. This parameter is omitted if no resource limits are defined. `CreatedAt` The time stamp for when the container was created. This parameter is omitted if the container has not been created yet. `StartedAt` The time stamp for when the container started. This parameter is omitted if the container has not started yet. `FinishedAt` The time stamp for when the container stopped. This parameter is omitted if the container has not stopped yet. `Type` The type of the container. Containers that are specified in your task definition are of type `NORMAL`. You can ignore other container types, which are used for internal task resource provisioning by the Amazon ECS container agent. `Networks` The network information for the container, such as the network mode and IP address. This parameter is omitted if no network information is defined. `ClockDrift` The information about the difference between the reference time and the system time. This applies to the Linux operating system. This capability uses Amazon Time Sync Service to measure clock accuracy and provide the clock error bound for containers. For more information, see [Set the time for your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html) in the *Amazon EC2 User Guide for Linux instances*. `ReferenceTime` The basis of clock accuracy. Amazon ECS uses the Coordinated Universal Time (UTC) global standard through NTP, for example `2021-09-07T16:57:44Z`. `ClockErrorBound` The measure of clock error, defined as the offset to UTC. This error is the difference in milliseconds between the reference time and the system time. `ClockSynchronizationStatus` Indicates whether the most recent synchronization attempt between the system time and the reference time was successful. The valid values are `SYNCHRONIZED` and ` NOT_SYNCHRONIZED`. `ExecutionStoppedAt` The time stamp for when the tasks `DesiredStatus` moved to `STOPPED`. This occurs when an essential container moves to `STOPPED`. # Amazon ECS task metadata v3 examples The following examples show sample outputs from the task metadata endpoints. ## Example Container Metadata Response When querying the `${ECS_CONTAINER_METADATA_URI}` endpoint you are returned only metadata about the container itself. The following is an example output. ``` { "DockerId": "43481a6ce4842eec8fe72fc28500c6b52edcc0917f105b83379f88cac1ff3946", "Name": "nginx-curl", "DockerName": "ecs-nginx-5-nginx-curl-ccccb9f49db0dfe0d901", "Image": "nrdlngr/nginx-curl", "ImageID": "sha256:2e00ae64383cfc865ba0a2ba37f61b50a120d2d9378559dcd458dc0de47bc165", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "nginx-curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "com.amazonaws.ecs.task-definition-family": "nginx", "com.amazonaws.ecs.task-definition-version": "5" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 512, "Memory": 512 }, "CreatedAt": "2018-02-01T20:55:10.554941919Z", "StartedAt": "2018-02-01T20:55:11.064236631Z", "Type": "NORMAL", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.106" ] } ] } ``` ## Example task metadata response When querying the `${ECS_CONTAINER_METADATA_URI}/task` endpoint you are returned metadata about the task the container is part of. The following is an example output. The following JSON response is for a single-container task. ``` { "Cluster": "default", "TaskARN": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "Family": "nginx", "Revision": "5", "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Containers": [ { "DockerId": "731a0d6a3b4210e2448339bc7015aaa79bfe4fa256384f4102db86ef94cbbc4c", "Name": "~internal~ecs~pause", "DockerName": "ecs-nginx-5-internalecspause-acc699c0cbf2d6d11700", "Image": "amazon/amazon-ecs-pause:0.1.0", "ImageID": "", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "~internal~ecs~pause", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "com.amazonaws.ecs.task-definition-family": "nginx", "com.amazonaws.ecs.task-definition-version": "5" }, "DesiredStatus": "RESOURCES_PROVISIONED", "KnownStatus": "RESOURCES_PROVISIONED", "Limits": { "CPU": 0, "Memory": 0 }, "CreatedAt": "2018-02-01T20:55:08.366329616Z", "StartedAt": "2018-02-01T20:55:09.058354915Z", "Type": "CNI_PAUSE", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.106" ] } ] }, { "DockerId": "43481a6ce4842eec8fe72fc28500c6b52edcc0917f105b83379f88cac1ff3946", "Name": "nginx-curl", "DockerName": "ecs-nginx-5-nginx-curl-ccccb9f49db0dfe0d901", "Image": "nrdlngr/nginx-curl", "ImageID": "sha256:2e00ae64383cfc865ba0a2ba37f61b50a120d2d9378559dcd458dc0de47bc165", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "nginx-curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "com.amazonaws.ecs.task-definition-family": "nginx", "com.amazonaws.ecs.task-definition-version": "5" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 512, "Memory": 512 }, "CreatedAt": "2018-02-01T20:55:10.554941919Z", "StartedAt": "2018-02-01T20:55:11.064236631Z", "Type": "NORMAL", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.106" ] } ] } ], "PullStartedAt": "2018-02-01T20:55:09.372495529Z", "PullStoppedAt": "2018-02-01T20:55:10.552018345Z", "AvailabilityZone": "us-east-2b" } ``` # Amazon ECS task metadata endpoint version 2 **Important** The task metadata version 2 endpoint is no longer being actively maintained. We recommend that you update the task metadata version 4 endpoint to get the latest metadata endpoint information. For more information, see [Amazon ECS task metadata endpoint version 4](task-metadata-endpoint-v4.md). Beginning with version 1.17.0 of the Amazon ECS container agent, various task metadata and [Docker stats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) are available to tasks that use the `awsvpc` network mode at an HTTP endpoint that is provided by the Amazon ECS container agent. All containers belonging to tasks that are launched with the `awsvpc` network mode receive a local IPv4 address within a predefined link-local address range. When a container queries the metadata endpoint, the Amazon ECS container agent can determine which task the container belongs to based on its unique IP address, and metadata and stats for that task are returned. ## Enabling task metadata **Important** The task metadata version 2 endpoint is no longer being actively maintained. We recommend that you update the task metadata version 4 endpoint to get the latest metadata endpoint information. For more information, see [Amazon ECS task metadata endpoint version 4](task-metadata-endpoint-v4.md). Beginning with version 1.17.0 of the Amazon ECS container agent, various task metadata and [Docker stats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) are available to tasks that use the `awsvpc` network mode at an HTTP endpoint that is provided by the Amazon ECS container agent. All containers belonging to tasks that are launched with the `awsvpc` network mode receive a local IPv4 address within a predefined link-local address range. When a container queries the metadata endpoint, the Amazon ECS container agent can determine which task the container belongs to based on its unique IP address, and metadata and stats for that task are returned. ### Enabling task metadata The task metadata version 2 feature is enabled by default for the following: + Tasks using Fargate that use platform version v1.1.0 or later. For more information, see [Fargate platform versions for Amazon ECS](platform-fargate.md). + Tasks using EC2 that also use the `awsvpc` network mode and are launched on Amazon EC2 Linux infrastructure running at least version 1.17.0 of the Amazon ECS container agent or on Amazon EC2 Windows infrastructure running at least version `1.54.0` of the Amazon ECS container agent. For more information, see [Amazon ECS Linux container instance management](manage-linux.md). You can add support for this feature on older container instances by updating the agent to the latest version. For more information, see [Updating the Amazon ECS container agent](ecs-agent-update.md). ### Task metadata endpoint paths The following API endpoints are available to containers: `169.254.170.2/v2/metadata` This endpoint returns metadata JSON 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 [Task metadata JSON response](#task-metadata-endpoint-v2-response). `169.254.170.2/v2/metadata/` This endpoint returns metadata JSON for the specified Docker container ID. `169.254.170.2/v2/metadata/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. `169.254.170.2/v2/stats` This endpoint returns Docker stats JSON for all of the containers associated with the task. For more information about each of the returned stats, see [ContainerStats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) in the Docker API documentation. `169.254.170.2/v2/stats/` This endpoint returns Docker stats JSON for the specified Docker container ID. For more information about each of the returned stats, see [ContainerStats](https://docs.docker.com/reference/api/engine/version/v1.30/#tag/Container/operation/ContainerStats) in the Docker API documentation. ### Task metadata JSON response The following information is returned from the task metadata endpoint (`169.254.170.2/v2/metadata`) JSON response. `Cluster` The Amazon Resource Name (ARN) or short name of the Amazon ECS cluster to which the task belongs. `TaskARN` The Amazon Resource Name (ARN) of the task to which the container belongs. `Family` The family of the Amazon ECS task definition for the task. `Revision` The revision of the Amazon ECS task definition for the task. `DesiredStatus` The desired status for the task from Amazon ECS. `KnownStatus` The known status for the task from Amazon ECS. `Limits` The resource limits specified at the task level, such as CPU (expressed in vCPUs) and memory. This parameter is omitted if no resource limits are defined. `PullStartedAt` The timestamp for when the first container image pull began. `PullStoppedAt` The timestamp for when the last container image pull finished. `AvailabilityZone` The Availability Zone the task is in. The Availability Zone metadata is only available for Fargate tasks using platform version 1.4 or later (Linux) or 1.0.0 or later (Windows). `Containers` A list of container metadata for each container associated with the task. `DockerId` The Docker ID for the container. `Name` The name of the container as specified in the task definition. `DockerName` The name of the container supplied to Docker. The Amazon ECS container agent generates a unique name for the container to avoid name collisions when multiple copies of the same task definition are run on a single instance. `Image` The image for the container. `ImageID` The SHA-256 digest of the image manifest. This is the digest that can be used to pull the image using the format `repository-url/image@sha256:digest`. `Ports` Any ports exposed for the container. This parameter is omitted if there are no exposed ports. `Labels` Any labels applied to the container. This parameter is omitted if there are no labels applied. `DesiredStatus` The desired status for the container from Amazon ECS. `KnownStatus` The known status for the container from Amazon ECS. `ExitCode` The exit code for the container. This parameter is omitted if the container has not exited. `Limits` The resource limits specified at the container level, such as CPU (expressed in CPU units) and memory. This parameter is omitted if no resource limits are defined. `CreatedAt` The time stamp for when the container was created. This parameter is omitted if the container has not been created yet. `StartedAt` The time stamp for when the container started. This parameter is omitted if the container has not started yet. `FinishedAt` The time stamp for when the container stopped. This parameter is omitted if the container has not stopped yet. `Type` The type of the container. Containers that are specified in your task definition are of type `NORMAL`. You can ignore other container types, which are used for internal task resource provisioning by the Amazon ECS container agent. `Networks` The network information for the container, such as the network mode and IP address. This parameter is omitted if no network information is defined. `ClockDrift` The information about the difference between the reference time and the system time. This applies to the Linux operating system. This capability uses Amazon Time Sync Service to measure clock accuracy and provide the clock error bound for containers. For more information, see [Set the time for your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html) in the *Amazon EC2 User Guide for Linux instances*. `ReferenceTime` The basis of clock accuracy. Amazon ECS uses the Coordinated Universal Time (UTC) global standard through NTP, for example `2021-09-07T16:57:44Z`. `ClockErrorBound` The measure of clock error, defined as the offset to UTC. This error is the difference in milliseconds between the reference time and the system time. `ClockSynchronizationStatus` Indicates whether the most recent synchronization attempt between the system time and the reference time was successful. The valid values are `SYNCHRONIZED` and ` NOT_SYNCHRONIZED`. `ExecutionStoppedAt` The time stamp for when the tasks `DesiredStatus` moved to `STOPPED`. This occurs when an essential container moves to `STOPPED`. ### Example task metadata response The following JSON response is for a single-container task. ``` { "Cluster": "default", "TaskARN": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "Family": "nginx", "Revision": "5", "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Containers": [ { "DockerId": "731a0d6a3b4210e2448339bc7015aaa79bfe4fa256384f4102db86ef94cbbc4c", "Name": "~internal~ecs~pause", "DockerName": "ecs-nginx-5-internalecspause-acc699c0cbf2d6d11700", "Image": "amazon/amazon-ecs-pause:0.1.0", "ImageID": "", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "~internal~ecs~pause", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "com.amazonaws.ecs.task-definition-family": "nginx", "com.amazonaws.ecs.task-definition-version": "5" }, "DesiredStatus": "RESOURCES_PROVISIONED", "KnownStatus": "RESOURCES_PROVISIONED", "Limits": { "CPU": 0, "Memory": 0 }, "CreatedAt": "2018-02-01T20:55:08.366329616Z", "StartedAt": "2018-02-01T20:55:09.058354915Z", "Type": "CNI_PAUSE", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.106" ] } ] }, { "DockerId": "43481a6ce4842eec8fe72fc28500c6b52edcc0917f105b83379f88cac1ff3946", "Name": "nginx-curl", "DockerName": "ecs-nginx-5-nginx-curl-ccccb9f49db0dfe0d901", "Image": "nrdlngr/nginx-curl", "ImageID": "sha256:2e00ae64383cfc865ba0a2ba37f61b50a120d2d9378559dcd458dc0de47bc165", "Labels": { "com.amazonaws.ecs.cluster": "default", "com.amazonaws.ecs.container-name": "nginx-curl", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-2:012345678910:task/9781c248-0edd-4cdb-9a93-f63cb662a5d3", "com.amazonaws.ecs.task-definition-family": "nginx", "com.amazonaws.ecs.task-definition-version": "5" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 512, "Memory": 512 }, "CreatedAt": "2018-02-01T20:55:10.554941919Z", "StartedAt": "2018-02-01T20:55:11.064236631Z", "Type": "NORMAL", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.2.106" ] } ] } ], "PullStartedAt": "2018-02-01T20:55:09.372495529Z", "PullStoppedAt": "2018-02-01T20:55:10.552018345Z", "AvailabilityZone": "us-east-2b" } ```