Amazon Elastic Container Service
开发人员指南 (API Version 2014-11-13)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

Amazon ECS 容器元数据

自 Amazon ECS 容器代理的 1.15.0 版本起,ECS 任务容器中提供了各种容器元数据。通过启用此功能,您可以通过读取每个容器的元数据文件,从容器内部或从容器实例查询有关任务、容器和容器实例的信息。元数据文件在主机实例上创建,并作为 Docker 卷挂载到容器中。

容器元数据文件位置设置为容器内的 ECS_CONTAINER_METADATA_FILE 环境变量。您可以使用以下命令读取容器中的文件内容:

  • 对于 Linux 实例:

    cat $ECS_CONTAINER_METADATA_FILE
  • 对于 Windows 实例 (PowerShell):

    Get-Content -path $env:ECS_CONTAINER_METADATA_FILE

清除容器时,主机实例上的容器元数据文件将被清除。在这种情况下,您可以使用 ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION 容器代理变量进行调整。有关更多信息,请参阅 自动化任务和映像清除

启用容器元数据

该功能在默认情况下处于禁用状态。您可以将 ECS_ENABLE_CONTAINER_METADATA 容器代理变量设置为 true,从而在容器实例级别启用容器元数据。您可以在 /etc/ecs/ecs.config 配置文件中设置此变量,并重新启动代理。您也可以在启动代理容器时将其设置为 Docker 环境变量。有关更多信息,请参阅 Amazon ECS 容器代理配置

注意

支持此功能的最低 Amazon ECS 容器代理版本是 1.15.0。

如果在代理启动时将 ECS_ENABLE_CONTAINER_METADATA 设置为 true,则会为 ECS 启动的任何将来容器创建元数据文件。

注意

Amazon ECS 容器代理无法为那些在 ECS_ENABLE_CONTAINER_METADATA 容器代理变量设置为 true 之前创建的容器创建元数据文件。为确保所有容器都收到元数据文件,应在容器实例启动时间设置此代理变量。

容器元数据文件位置

默认情况下,容器元数据文件写入到以下主机和容器路径。

  • 对于 Linux 实例:

    • 主机路径:/var/lib/ecs/data/metadata/task_id/container_name/ecs-container-metadata.json

      注意

      Linux 主机路径假定在启动代理时使用默认数据目录挂载路径 (/var/lib/ecs/data)。如果您并非使用经 Amazon ECS 优化的 AMI (或 ecs-init 程序包来启动和维护容器代理),请确保将 ECS_HOST_DATA_DIR 代理配置变量设置为容器代理状态文件所在的主机路径。有关更多信息,请参阅 Amazon ECS 容器代理配置

    • 容器路径:/opt/ecs/metadata/random_ID/ecs-container-metadata.json

  • 对于 Windows 实例:

    • 主机路径:C:\ProgramData\Amazon\ECS\data\metadata\task_id\container_name\ecs-container-metadata.json

    • 容器路径:C:\ProgramData\Amazon\ECS\metadata\random_ID\ecs-container-metadata.json

但是为了便于访问,容器元数据文件位置设置为容器内的 ECS_CONTAINER_METADATA_FILE 环境变量。您可以使用以下命令读取容器中的文件内容:

  • 对于 Linux 实例:

    cat $ECS_CONTAINER_METADATA_FILE
  • 对于 Windows 实例 (PowerShell):

    Get-Content -path $env:ECS_CONTAINER_METADATA_FILE

容器元数据文件格式

以下信息存储在容器元数据 JSON 文件中。

ContainerInstanceARN

主机容器实例的完整 Amazon 资源名称 (ARN)。

TaskARN

容器所属的任务的完整 Amazon 资源名称 (ARN)。

ContainerID

容器的 Docker 容器 ID (而不是 Amazon ECS 容器 ID)。

ContainerName

容器 Amazon ECS 任务定义中的容器名称。

DockerContainerName

Docker 守护程序用于容器的容器名称 (例如,docker ps 命令输出中显示的名称)。

ImageID

用于启动容器的 Docker 映像的 SHA 摘要。

ImageName

用于启动容器的 Docker 映像的映像名称和标签。

PortMappings

与容器关联的任何端口映射。

ContainerPort

公开的容器上的端口。

HostPort

公开的主机容器实例上的端口。

BindIp

Docker 分配给容器的绑定 IP 地址。此 IP 地址仅适用于 bridge 网络模式,只能从容器实例进行访问。

Protocol

用于端口映射的网络协议。

Networks

容器的网络模式和 IP 地址。

NetworkMode

容器所属的任务的网络模式。

IPv4Addresses

与容器关联的 IP 地址。

MetadataFileStatus

元数据文件的状态。如果状态为 READY,则元数据文件是最新状态且内容完整。如果文件尚未准备就绪 (例如在启动任务时),将会提供文件格式的截断版本。为了避免可能出现的竞用情况,比如已经启动容器,但尚未写入元数据,您可以解析元数据文件,并等待此参数设置为 READY,然后再使用元数据。这通常是在容器启动后的 1 秒内提供。

例 Amazon ECS 容器元数据文件 (READY)

以下示例显示了处于 READY 状态的容器元数据文件。

{ "ContainerInstanceARN": "arn:aws:ecs:us-west-2:012345678910:container-instance/1f73d099-b914-411c-a9ff-81633b7741dd", "TaskARN": "arn:aws:ecs:us-west-2:012345678910:task/2b88376d-aba3-4950-9ddf-bcb0f388a40c", "ContainerID": "98e44444008169587b826b4cd76c6732e5899747e753af1e19a35db64f9e9c32", "ContainerName": "metadata", "DockerContainerName": "/ecs-metadata-7-metadata-f0edfbd6d09fdef20800", "ImageID": "sha256:c24f66af34b4d76558f7743109e2476b6325fcf6cc167c6e1e07cd121a22b341", "ImageName": "httpd:2.4", "PortMappings": [ { "ContainerPort": 80, "HostPort": 80, "BindIp": "", "Protocol": "tcp" } ], "Networks": [ { "NetworkMode": "bridge", "IPv4Addresses": [ "172.17.0.2" ] } ], "MetadataFileStatus": "READY" }

例 未完成的 Amazon ECS 容器元数据文件 (尚未处于 READY 状态)

以下示例显示了尚未处于 READY 状态的容器元数据文件。文件中的信息仅限任务定义中已知的几个参数。容器元数据文件应在容器启动后的 1 秒内准备就绪。

{ "ContainerInstanceARN": "arn:aws:ecs:us-west-2:012345678910:container-instance/1f73d099-b914-411c-a9ff-81633b7741dd", "TaskARN": "arn:aws:ecs:us-west-2:012345678910:task/d90675f8-1a98-444b-805b-3d9cabb6fcd4", "ContainerName": "metadata" }