Downward API

Downward API

실행 중인 컨테이너에 파드와 컨테이너 필드를 노출하는 방법은 두 가지가 있어요. 환경 변수와, 특별한 볼륨 유형으로 채워지는 파일이에요. 파드와 컨테이너 필드를 노출하는 이 두 가지 방법을 합쳐서 downward API라고 불러요.

컨테이너가 쿠버네티스에 지나치게 결합되지 않으면서 자신에 대한 정보를 갖는 것이 때로는 유용해요. downward API는 컨테이너가 쿠버네티스 클라이언트나 API 서버를 사용하지 않고도 자신이나 클러스터에 대한 정보를 소비할 수 있게 해 줘요.

예를 들어, 특정 잘 알려진 환경 변수가 고유 식별자를 담고 있다고 가정하는 기존 애플리케이션이 있다고 해 보죠. 한 가지 방법은 애플리케이션을 래핑하는 것인데, 이는 지루하고 오류가 발생하기 쉬우며 낮은 결합도라는 목표를 위반해요. 더 나은 방법은 파드의 이름을 식별자로 사용하고, 그 파드 이름을 잘 알려진 환경 변수에 주입하는 것이에요.

쿠버네티스에서 실행 중인 컨테이너에 파드와 컨테이너 필드를 노출하는 방법은 두 가지가 있어요.

  • 환경 변수로
  • downwardAPI 볼륨의 파일로

파드와 컨테이너 필드를 노출하는 이 두 가지 방법을 합쳐서 downward API라고 불러요.

출처: 문서

본문

사용 가능한 필드 (Available fields)

downward API를 통해 사용할 수 있는 쿠버네티스 API 필드는 일부뿐이에요. 이 섹션에서는 사용 가능하게 만들 수 있는 필드를 나열해요.

fieldRef를 사용해 사용 가능한 파드 레벨 필드에서 정보를 전달할 수 있어요. API 레벨에서 Pod의 spec은 항상 최소 하나의 Container를 정의해요. resourceFieldRef를 사용해 사용 가능한 컨테이너 레벨 필드에서 정보를 전달할 수 있어요.

fieldRef로 사용 가능한 정보 (Information available via fieldRef)

일부 파드 레벨 필드는 컨테이너에 환경 변수로 또는 downwardAPI 볼륨으로 제공할 수 있어요. 두 메커니즘 모두에서 사용 가능한 필드는 다음과 같아요.

필드 설명
metadata.name 파드의 이름
metadata.namespace 파드의 네임스페이스
metadata.uid 파드의 고유 ID
metadata.annotations['<KEY>'] <KEY>라는 이름의 파드 어노테이션 값 (예: metadata.annotations['myannotation'])
metadata.labels['<KEY>'] <KEY>라는 이름의 파드 라벨의 텍스트 값 (예: metadata.labels['mylabel'])

다음 정보는 환경 변수로는 사용할 수 있지만 downwardAPI 볼륨 fieldRef로는 사용할 수 없어요.

필드 설명
spec.serviceAccountName 파드의 서비스어카운트 이름
spec.nodeName Pod가 실행되는 노드의 이름
status.hostIP Pod가 할당된 노드의 기본 IP 주소
status.hostIPs status.hostIP의 이중 스택(dual-stack) 버전 IP 주소. 첫 번째는 항상 status.hostIP와 같아요.
status.podIP 파드의 기본 IP 주소 (보통 IPv4 주소)
status.podIPs status.podIP의 이중 스택 버전 IP 주소. 첫 번째는 항상 status.podIP와 같아요.

다음 정보는 downwardAPI 볼륨 fieldRef로는 사용할 수 있지만 환경 변수로는 사용할 수 없어요.

필드 설명
metadata.labels 파드의 모든 라벨. label-key="escaped-label-value" 형식으로 한 줄에 라벨 하나
metadata.annotations 파드의 모든 어노테이션. annotation-key="escaped-annotation-value" 형식으로 한 줄에 어노테이션 하나

resourceFieldRef로 사용 가능한 정보 (Information available via resourceFieldRef)

이 컨테이너 레벨 필드들은 CPU와 메모리 같은 리소스의 요청(request)과 제한(limit)에 대한 정보를 제공할 수 있게 해 줘요.

참고: 기능 상태: Kubernetes v1.35부터 Stable. 이것은 쿠버네티스의 안정적인 기능이며 v1.35부터 그랬어요. 처음에는 v1.27 릴리스에서 사용할 수 있었어요. 더 이상 이 기능이나 동작을 비활성화하거나 거부할 수 없어요(잠겨 있음). 관련 기능 게이트인 InPlacePodVerticalScaling에 값을 명시적으로 설정하면 쿠버네티스는 이를 무시하지만 오류는 보고하지 않아요.

컨테이너 CPU와 메모리 리소스는 컨테이너가 실행되는 동안 크기를 조정할 수 있어요. 이 경우 downward API 볼륨은 업데이트되지만, 환경 변수는 컨테이너가 재시작되지 않는 한 업데이트되지 않아요. 자세한 내용은 "컨테이너에 할당된 CPU와 메모리 리소스 크기 조정"을 참고하세요.

필드 설명
resource: limits.cpu 컨테이너의 CPU 제한
resource: requests.cpu 컨테이너의 CPU 요청
resource: limits.memory 컨테이너의 메모리 제한
resource: requests.memory 컨테이너의 메모리 요청
resource: limits.hugepages-* 컨테이너의 hugepages 제한
resource: requests.hugepages-* 컨테이너의 hugepages 요청
resource: limits.ephemeral-storage 컨테이너의 임시 스토리지 제한
resource: requests.ephemeral-storage 컨테이너의 임시 스토리지 요청

리소스 제한의 폴백 정보 (Fallback information for resource limits)

컨테이너에 CPU와 메모리 제한이 지정되지 않았고, downward API를 사용해 그 정보를 노출하려고 한다면, kubelet은 노드 할당 가능(allocatable) 계산을 기반으로 CPU와 메모리의 최대 할당 가능 값을 노출하는 것을 기본값으로 해요.

다음 단계 (What's next)

downwardAPI 볼륨에 대해 읽을 수 있어요. downward API를 사용해 컨테이너 또는 파드 레벨 정보를 노출하는 것을 시도해 볼 수 있어요.

  • 환경 변수로
  • downwardAPI 볼륨의 파일로

더 알아보기 (Learn more)