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

Amazon ECS Container Agent Introspection

The Amazon ECS container agent provides an API for gathering details about the container instance that the agent is running on and the associated tasks that are running on that instance. You can use the curl command from within the container instance to query the Amazon ECS container agent (port 51678) and return container instance metadata or task information.

To view container instance metadata log in to your container instance via SSH and run the following command. Metadata includes the container instance ID, the Amazon ECS cluster in which the container instance is registered, and the Amazon ECS container agent version information,

Copy
[ec2-user ~]$ curl http://localhost:51678/v1/metadata

Output:

{
  "Cluster": "default",
  "ContainerInstanceArn": "<container_instance_ARN>",
  "Version": "Amazon ECS Agent - v1.14.1 (467c3d7)"
}

To view information about all of the tasks that are running on a container instance, log in to your container instance via SSH and run the following command:

Copy
[ec2-user ~]$ curl http://localhost:51678/v1/tasks

Output:


{
  "Tasks": [
    {
      "Arn": "arn:aws:ecs:us-east-1:<aws_account_id>:task/example5-58ff-46c9-ae05-543f8example",
      "DesiredStatus": "RUNNING",
      "KnownStatus": "RUNNING",
      "Family": "hello_world",
      "Version": "8",
      "Containers": [
        {
          "DockerId": "9581a69a761a557fbfce1d0f6745e4af5b9dbfb86b6b2c5c4df156f1a5932ff1",
          "DockerName": "ecs-hello_world-8-mysql-fcae8ac8f9f1d89d8301",
          "Name": "mysql"
        },
        {
          "DockerId": "bf25c5c5b2d4dba68846c7236e75b6915e1e778d31611e3c6a06831e39814a15",
          "DockerName": "ecs-hello_world-8-wordpress-e8bfddf9b488dff36c00",
          "Name": "wordpress"
        }
      ]
    }
  ]
}

You can view information for a particular task that is running on a container instance. To specify a specific task or container, append one of the following to the request:

  • The task ARN (?taskarn=task_arn)

  • The container Docker ID (?dockerid=docker_id)

To get task information with a Docker ID, log in to your container instance via SSH and run the following command.

Note

The Amazon ECS container agent introspection API requires full Docker IDs, not the short version that is shown with docker ps. You can get the full Docker ID for a container by running the docker ps --no-trunc command on the container instance.

Copy
[ec2-user ~]$ curl http://localhost:51678/v1/tasks?dockerid=9581a69a761a557fbfce1d0f6745e4af5b9dbfb86b6b2c5c4df156f1a5932ff1

Output:


{
  "Arn": "arn:aws:ecs:us-east-1:<aws_account_id>:task/example5-58ff-46c9-ae05-543f8example",
  "DesiredStatus": "RUNNING",
  "KnownStatus": "RUNNING",
  "Family": "hello_world",
  "Version": "8",
  "Containers": [
    {
      "DockerId": "9581a69a761a557fbfce1d0f6745e4af5b9dbfb86b6b2c5c4df156f1a5932ff1",
      "DockerName": "ecs-hello_world-8-mysql-fcae8ac8f9f1d89d8301",
      "Name": "mysql"
    },
    {
      "DockerId": "bf25c5c5b2d4dba68846c7236e75b6915e1e778d31611e3c6a06831e39814a15",
      "DockerName": "ecs-hello_world-8-wordpress-e8bfddf9b488dff36c00",
      "Name": "wordpress"
    }
  ]
}