Kubernetes Downward API: Pod-Infos ohne API-Zugriff – einfach erklärt

Die Kubernetes Downward API macht Metadaten eines Pods innerhalb seiner Container verfügbar, ohne dass die Anwendung die Kubernetes-API selbst abfragen muss. Typische Werte sind Pod-Name, Namespace, Pod-IP oder Ressourcen-Grenzen.

Zwei Wege: Umgebungsvariablen und Dateien

Die Downward API arbeitet auf zwei Arten: als Umgebungsvariable (im Manifest unter env mit valueFrom.fieldRef oder resourceFieldRef) oder als Volume-Datei (Volume-Typ downwardAPI). Die Werte stehen direkt in der Pod-Spec; die Anwendung liest sie wie jede andere Konfiguration.

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

Verfügbare Felder

  • Per fieldRef auf Pod-Ebene: metadata.name, metadata.namespace, metadata.uid, metadata.labels[<key>], metadata.annotations[<key>], spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP.
  • Per resourceFieldRef auf Container-Ebene: resources.requests.cpu, resources.requests.memory, resources.limits.cpu, resources.limits.memory.
  • Labels und Annotations sind nur als Volume-Dateien verfügbar, nicht als Umgebungsvariable.

Wichtige Eigenschaften

  • Umgebungsvariablen werden beim Start des Containers gesetzt und danach nicht aktualisiert.
  • Volume-Dateien aktualisiert der kubelet regelmäßig – spätere Änderungen an Labels oder Annotations kommen so an.
  • Fehlen CPU- oder Memory-Limits, liefert die Downward API den Node-Allocatable-Wert als Standard.
  • Die Downward API ist read-only: Sie gibt nur Metadaten weiter, die bereits existieren.

Typische Einsätze

  • Logging: Die Anwendung schreibt ihren Pod-Namen in die Logs, ohne ihn hart zu kodieren.
  • Konfiguration: Pod-IP, Node-Name oder Umgebung fließen in die Anwendungskonfiguration ein.
  • Ressourcenbewusstes Verhalten: Die App liest ihre CPU- und Memory-Limits per resourceFieldRef.

Die Downward API ist auch eine Quelle im Projected Volume – dort bündelt sie Metadaten mit ConfigMaps und Secrets in einem Mount. In StatefulSets hinter einem Headless Service liefert metadata.name genau den festen Pod-Namen, der der DNS-Adresse des Pods entspricht. Mutierende Admission Webhooks ergänzen solche fieldRef-Referenzen oft automatisch in Pod-Specs.