Amazon ECS 태스크 메타데이터 엔드포인트 버전 4

Amazon ECS 태스크 메타데이터 엔드포인트 버전 4

Amazon ECS container agent가 각 컨테이너에 주입하는 태스크 메타데이터 엔드포인트(버전 4)와 그 경로를 알아봐요.

출처: 문서

본문

Amazon ECS container agent는 각 컨테이너에 태스크 메타데이터 엔드포인트라고 하는 환경 변수를 주입해요. 이는 컨테이너에 다양한 태스크 메타데이터와 Docker stats를 제공해요. 태스크 메타데이터와 네트워크 rate stats는 CloudWatch Container Insights로 전송되고 AWS Management Console에서 볼 수 있어요. 자세한 내용은 Monitor Amazon ECS containers using Container Insights with enhanced observability 참고.

참고 — Amazon ECS는 태스크 메타데이터 엔드포인트의 이전 버전을 제공해요. 향후 새 태스크 메타데이터 엔드포인트 버전을 만들 필요가 없도록 추가 메타데이터가 버전 4 출력에 추가될 수 있어요. 기존 메타데이터를 제거하거나 메타데이터 필드 이름을 변경하지 않을 거예요.

환경 변수는 기본적으로 최소 버전 1.39.0의 Amazon ECS container agent를 실행하는 Amazon EC2 Linux 인스턴스에서 시작되는 Amazon ECS 태스크의 컨테이너에 주입돼요. awsvpc 네트워크 모드를 사용하는 Amazon EC2 Windows 인스턴스의 경우 Amazon ECS container agent가 최소 버전 1.54.0이어야 해요. 자세한 내용은 Amazon ECS Linux container instance management 참고.

참고 — 구버전의 Amazon ECS container agent를 사용하는 Amazon EC2 인스턴스에서 에이전트를 최신 버전으로 업데이트해 이 기능 지원을 추가할 수 있어요. 자세한 내용은 Updating the Amazon ECS container agent 참고. 태스크 메타데이터 예시 출력은 Amazon ECS task metadata v4 examples 참고.

태스크 메타데이터 엔드포인트 버전 4 경로 (Paths)

다음 태스크 메타데이터 엔드포인트 경로를 컨테이너에서 사용할 수 있어요.

  • ${ECS_CONTAINER_METADATA_URI_V4} - 이 경로는 컨테이너의 메타데이터를 반환해요.
  • ${ECS_CONTAINER_METADATA_URI_V4}/task - 이 경로는 태스크에 연결된 모든 컨테이너의 컨테이너 ID와 이름 목록을 포함해 태스크의 메타데이터를 반환해요. 이 엔드포인트의 응답에 대한 자세한 내용은 Amazon ECS task metadata V4 JSON response 참고.
  • ${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags - 이 경로는 /task 엔드포인트에 포함된 태스크 메타데이터와 함께, ListTagsForResource API로 검색할 수 있는 태스크 및 컨테이너 인스턴스 태그를 반환해요. 태그 메타데이터 검색 시 발생하는 오류는 응답의 Errors 필드에 포함돼요.
    • 참고 — Errors 필드는 최소 버전 1.50.0의 container agent를 실행하는 Amazon EC2 Linux 인스턴스에서 호스팅되는 태스크에 대해서만 응답에 있어요. awsvpc 네트워크 모드를 사용하는 Amazon EC2 Windows 인스턴스의 경우 Amazon ECS container agent가 최소 버전 1.54.0이어야 해요.
    • 이 엔드포인트는 ecs.ListTagsForResource 권한이 필요해요.
    • 중요 — ${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags 엔드포인트를 사용할 때 각 호출은 ecs:ListTagsForResource에 최대 두 개의 API 요청(컨테이너 인스턴스 태그용 1개, 태스크 태그용 1개)을 하며, 태스크의 사이드카 컨테이너가 사용자를 대신해 이러한 호출을 할 수 있어요. 빈번한 엔드포인트 호출은 API 제한(throttling)을 초래할 수 있어요. 특히 높은 트래픽 애플리케이션에서 호출 빈도를 줄이기 위해 캐싱이나 일괄 처리 전략 구현을 고려하고, AWS CloudTrail로 API 제한 문제를 디버깅하세요. ListTagsForResource API의 제한 한도에 대한 내용은 Amazon Elastic Container Service API Reference의 Request throttling for the Amazon ECS API 참고.

더 알아보기 (Learn more)