쿠버네티스 Downward API — 파드 메타데이터 주입하기

컨테이너 안에서 "지금 내가 어느 Pod, 어느 노드, 어느 네임스페이스에 떠 있지?"를 알아야 할 때가 있습니다. 로그에 Pod 이름을 찍거나, 메트릭에 노드 라벨을 붙일 때입니다. 이런 Pod 자신의 메타데이터를 컨테이너에 넘겨주는 쿠버네티스 기능이 Downward API입니다. 클러스터를 조회하는 API 호출 없이, 컨테이너가 자기 정보를 환경변수나 파일로 받아볼 수 있습니다.

Downward API란

이름의 "Downward(아래로)"는 정보가 컨트롤플레인에서 컨테이너로 내려온다는 뜻입니다. 컨테이너가 kube-apiserver에 따로 질의하지 않아도, kubelet이 Pod 스펙에 이미 들어 있는 값을 주입해 줍니다. 주입 방식은 두 가지입니다.

방식	설명	적합한 경우
환경변수	컨테이너 시작 시 값 고정	Pod 이름, 네임스페이스 등 안 바뀌는 값
볼륨 파일	파일로 마운트, 변경 시 갱신	라벨·어노테이션처럼 바뀔 수 있는 값

가져올 수 있는 값은 크게 fieldRef(Pod의 필드: 이름·네임스페이스·IP·노드 이름·라벨 등)와 resourceFieldRef(컨테이너의 CPU·메모리 요청/제한)로 나뉩니다.

환경변수로 주입하기

가장 흔한 패턴은 Pod 이름과 네임스페이스를 환경변수로 받는 것입니다.

YAML

apiVersion: v1
kind: Pod
metadata:
  name: demo
spec:
  containers:
    - name: app
      image: busybox
      command: ["sh", "-c", "echo $POD_NAME in $POD_NS; sleep 3600"]
      env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NS
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName

valueFrom.fieldRef.fieldPath에 가져올 필드 경로를 적습니다. 컨테이너 안에서 확인해 보면 값이 들어 있습니다.

Kubernetes

kubectl exec demo -- env | grep POD_

볼륨 파일로 주입하기

라벨이나 어노테이션은 런타임에 바뀔 수 있어 파일 방식이 적합합니다. downwardAPI 볼륨으로 마운트하면 디렉터리에 파일로 떨어집니다.

YAML

volumes:
  - name: podinfo
    downwardAPI:
      items:
        - path: "labels"
          fieldRef:
            fieldPath: metadata.labels

이렇게 마운트하면 /etc/podinfo/labels 파일에 라벨이 들어가고, kubectl label로 라벨이 바뀌면 잠시 뒤 파일도 갱신됩니다. 환경변수는 이렇게 자동 갱신되지 않는다는 점이 중요한 차이입니다.

요점 정리

Downward API는 Pod 자신의 메타데이터를 API 호출 없이 컨테이너로 내려준다.
fieldRef는 Pod 필드(이름·IP·노드), resourceFieldRef는 CPU·메모리 값을 가져온다.
환경변수 방식은 시작 시 고정, 볼륨 파일 방식은 라벨 변경 시 갱신된다.
로깅·메트릭에 Pod 정체성을 붙일 때 가장 많이 쓴다.

Pod 메타데이터를 직접 주입하고 컨테이너 안에서 확인하는 실습은 쿠버네티스 트랙에서 할 수 있습니다 — 회원가입 없이 무료로.