해당 문서의 쿠버네티스 버전: v1.28
Kubernetes v1.28 문서는 더 이상 적극적으로 관리되지 않음. 현재 보고있는 문서는 정적 스냅샷임. 최신 문서를 위해서는, 다음을 참고. 최신 버전.
다운워드(Downward) API
컨테이너가 쿠버네티스에 지나치게 종속되지 않으면서도 자기 자신에 대한 정보를 알고 있으면 유용할 때가 있다. 다운워드 API는 컨테이너가 자기 자신 혹은 클러스터에 대한 정보를, 쿠버네티스 클라이언트나 API 서버 없이도 사용할 수 있게 한다.
예를 들어, 잘 알려진 특정 환경 변수에다가 고유한 식별자를 넣어 사용하는 애플리케이션이 있다고 하자. 해당 애플리케이션에 맞게 작업할 수도 있겠지만, 이는 지루하고 오류가 나기 쉬울뿐더러, 낮은 결합이라는 원칙에도 위배된다. 대신, 파드의 이름을 식별자로 사용하고 잘 알려진 환경 변수에 파드의 이름을 넣는 것도 괜찮은 방법이다.
쿠버네티스에는 실행 중인 컨테이너에 파드 및 컨테이너 필드를 노출하는 두 가지 방법이 있다.
파드 및 컨테이너 필드를 노출하는 이 두 가지 방법을 다운워드 API라고 한다.
사용 가능한 필드
쿠버네티스 API 필드 중 일부만이 다운워드 API를 통해 접근 가능하다. 이 페이지에서는 사용 가능한 필드를 나열한다.
사용 가능한 파드 필드에 대한 정보는 fieldRef를 통해 넘겨줄 수 있다.
API 레벨에서, 파드의 spec은 항상 하나 이상의
컨테이너를 정의한다.
사용 가능한 컨테이너 필드에 대한 정보는
resourceFiledRef를 통해 넘겨줄 수 있다.
fieldRef를 통해 접근 가능한 정보
대부분의 파드 필드는 환경 변수로써,
또는 다운워드 API 볼륨을 사용하여 컨테이너에 제공할 수 있다.
이런 두 가지 방법을 통해 사용 가능한 필드는 다음과 같다.
metadata.name- 파드의 이름
metadata.namespace- 파드가 속한 네임스페이스
metadata.uid- 파드의 고유 ID
metadata.annotations['<KEY>']- 파드의 어노테이션에서
<KEY>에 해당하는 값 (예를 들어,metadata.annotations['myannotation']) metadata.labels['<KEY>']- 파드의 레이블에서
<KEY>에 해당하는 문자열 (예를 들어,metadata.labels['mylabel']) spec.serviceAccountName- 파드의 서비스 어카운트
spec.nodeName- 파드가 실행중인 노드명
status.hostIP- 파드가 할당된 노드의 기본 IP 주소
status.podIP- 파드의 기본 IP 주소 (일반적으로 IPv4 주소)
추가적으로 아래 필드는 환경 변수가 아닌,
다운워드 API 볼륨의 fieldRef로만 접근 가능하다.
metadata.labels- 파드의 모든 레이블로, 한 줄마다 하나의 레이블을 갖는(
label-key="escaped-label-value") 형식을 취함 metadata.annotations- 파드의 모든 어노테이션으로, 한 줄마다 하나의 어노테이션을 갖는(
annotation-key="escaped-annotation-value") 형식을 취함
resourceFieldRef를 통해 접근 가능한 정보
컨테이너 필드는 CPU와 메모리 같은 리소스에 대한 요청 및 제한 값을 제공한다.
resource: limits.cpu- 컨테이너의 CPU 제한
resource: requests.cpu- 컨테이너의 CPU 요청
resource: limits.memory- 컨테이너의 메모리 제한
resource: requests.memory- 컨테이너의 메모리 요청
resource: limits.hugepages-*- 컨테이너의 hugepage 제한 (
DownwardAPIHugePages기능 게이트가 활성화 된 경우) resource: requests.hugepages-*- 컨테이너의 hugepage 요청 (
DownwardAPIHugePages기능 게이트가 활성화 된 경우) resource: limits.ephemeral-storage- 컨테이너의 임시 스토리지 제한
resource: requests.ephemeral-storage- 컨테이너의 임시 스토리지 요청
리소스 제한에 대한 참고 정보
컨테이너의 CPU와 메모리 제한을 명시하지 않고 다운워드 API로 이 정보들을 제공하려고 할 경우, kubelet은 기본적으로 노드의 할당 가능량에 기반하여 CPU와 메모리에 할당 가능한 최댓값을 노출시킨다.
다음 내용
자세한 정보는 다운워드API 볼륨를 참고한다.
다운워드 API를 사용하여 파드 및 컨테이너 정보를 노출시켜보자.