Downward API

Overview

Downward API exposes pod and container metadata to containers via environment variables or files.

---

Available Fields

Pod Fields (fieldRef)

Field	Description
metadata.name	Pod name
metadata.namespace	Pod namespace
metadata.uid	Pod UID
metadata.labels['<KEY>']	Specific label value
metadata.annotations['<KEY>']	Specific annotation value
spec.nodeName	Node name where pod runs
spec.serviceAccountName	Service account name
status.podIP	Pod IP address
status.hostIP	Node IP address

Container Fields (resourceFieldRef)

Field	Description
requests.cpu	CPU request
requests.memory	Memory request
limits.cpu	CPU limit
limits.memory	Memory limit

---

Environment Variables

apiVersion: v1
kind: Pod
metadata:
  name: downward-env
  labels:
    app: demo
    tier: frontend
spec:
  containers:
  - name: app
    image: busybox
    command: ["sh", "-c", "printenv && sleep 3600"]
    env:
    - name: POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: POD_NAMESPACE
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: POD_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP
    - name: NODE_NAME
      valueFrom:
        fieldRef:
          fieldPath: spec.nodeName
    - name: POD_LABEL_APP
      valueFrom:
        fieldRef:
          fieldPath: metadata.labels['app']

---

Resource Fields as Env Vars

apiVersion: v1
kind: Pod
metadata:
  name: resource-env
spec:
  containers:
  - name: app
    image: busybox
    command: ["sh", "-c", "printenv && sleep 3600"]
    resources:
      requests:
        cpu: "100m"
        memory: "64Mi"
      limits:
        cpu: "200m"
        memory: "128Mi"
    env:
    - name: CPU_REQUEST
      valueFrom:
        resourceFieldRef:
          containerName: app
          resource: requests.cpu
    - name: MEM_LIMIT
      valueFrom:
        resourceFieldRef:
          containerName: app
          resource: limits.memory

---

Volume Mount (downwardAPI volume)

apiVersion: v1
kind: Pod
metadata:
  name: downward-volume
  labels:
    app: demo
  annotations:
    build: "123"
spec:
  containers:
  - name: app
    image: busybox
    command: ["sh", "-c", "cat /etc/podinfo/* && sleep 3600"]
    volumeMounts:
    - name: podinfo
      mountPath: /etc/podinfo
  volumes:
  - name: podinfo
    downwardAPI:
      items:
      - path: "labels"
        fieldRef:
          fieldPath: metadata.labels
      - path: "annotations"
        fieldRef:
          fieldPath: metadata.annotations
      - path: "name"
        fieldRef:
          fieldPath: metadata.name
      - path: "namespace"
        fieldRef:
          fieldPath: metadata.namespace

---

Labels and Annotations as Files

Volume approach is useful when you need:

• All labels/annotations at once
• Dynamic updates (labels/annotations can change)

# Inside container
cat /etc/podinfo/labels
# Output: app="demo"

cat /etc/podinfo/annotations  
# Output: build="123"

---

Common Use Cases

1. Application logging - Include pod name in log lines
2. Service discovery - Know which node you're on
3. Resource-aware apps - Adjust behavior based on limits
4. Debugging - Expose metadata for troubleshooting

---

Verify

# Check env vars
kubectl exec <pod-name> -- printenv | grep POD

# Check mounted files
kubectl exec <pod-name> -- cat /etc/podinfo/labels