Downward API

## What the downward API is "Downward" means information flowing *down* from the Pod object into the containers running inside it. Without it, a container that wants to know its own name has two bad options: guess from the hostname, or authenticate to the API server and query itself. The downward API removes both by letting the kubelet inject selected fields of the Pod's own spec and status directly. It has exactly two delivery forms: - **Environment variables** — `env[].valueFrom.fieldRef` (Pod metadata/spec/status fields) and `env[].valueFrom.resourceFieldRef` (the container's resource requests and limits). - **A `downwardAPI` volume** — files under a mount path, using the same two selector kinds. This question covers the env form for identity fields. ## The syntax ```yaml env: - name: POD_NAMESPACE valueFrom: fieldRef: apiVersion: v1 fieldPath: metadata.namespace ``` `apiVersion: v1` is the schema the `fieldPath` is interpreted against; it defaults to `v1` and is normally omitted (the API server writes it back in, which surprises people diffing manifests). ## Which fields are available in the env form Single-valued fields only: - `metadata.name` — the Pod name. For a Deployment this includes the ReplicaSet and random suffix; for a StatefulSet it is the stable `web-0` style name, which is why parsing the ordinal off it is a common pattern. - `metadata.namespace` — essential for building in-cluster DNS names and for tagging telemetry. - `metadata.uid` — the unique identity of this Pod instance, useful as a correlation key or for owner references written by the workload itself. - `metadata.labels['<key>']` and `metadata.annotations['<key>']` — a *single* label or annotation selected by key. The whole map is not available as an env var; that requires a volume. - `spec.nodeName` and `spec.serviceAccountName`. - `status.podIP`, `status.hostIP` (and the plural `status.podIPs` / `status.hostIPs` for dual-stack clusters). Notably absent: anything about *other* objects. You cannot read node labels, Service details, other Pods, or arbitrary status fields. Those need an API call with a ServiceAccount and RBAC. ## Timing and immutability The kubelet resolves these values while constructing the container, and a process environment cannot be rewritten afterwards — so a downward-API env var is fixed for the life of the container. That matches reality for identity fields: a Pod's name, namespace, UID and node never change, and its IP is assigned before containers start and is stable until the Pod is deleted (a *restarted container* in the same Pod keeps the same Pod IP; a *rescheduled* Pod is a new Pod object with a new name and IP). The one field where immutability bites is labels and annotations, which *can* be edited on a running Pod. If you need to observe such edits, use the volume form, whose files are refreshed by the kubelet. ## Why not just use the hostname? A Pod's hostname defaults to the Pod name, so `hostname` often *looks* like a substitute. It is not reliable: `spec.hostname` and `spec.subdomain` can override it, `hostNetwork: true` Pods inherit the node's hostname, and the hostname is truncated/normalised in ways the Pod name is not. Reading `metadata.name` explicitly is unambiguous and self-documenting. ## Why not query the API server? Because it turns a free lookup into a networked dependency with a security surface: the Pod needs a mounted ServiceAccount token, an RBAC rule granting `get` on pods, resilience to API-server unavailability at startup, and a client library. For four strings that the kubelet already has in hand, this is pure downside. "Use the downward API instead of granting the app RBAC to read itself" is a good least-privilege talking point in an interview. ## Typical uses - **Telemetry.** OpenTelemetry resource attributes (`k8s.pod.name`, `k8s.namespace.name`, `k8s.node.name`) are almost always populated this way; logging libraries add the Pod name to every line so that aggregated logs stay attributable. - **Clustering.** Systems that must advertise a reachable address (Hazelcast, Akka, Kafka clients, Elasticsearch transport) take `status.podIP` from the downward API. - **StatefulSet identity.** `metadata.name` gives `mysql-2`; the ordinal drives which shard or replica role the process takes. - **Correlating crashes and node problems.** `spec.nodeName` in the application's own logs makes "all errors are on one node" visible without cross-referencing the API. ## Failure modes An unsupported `fieldPath` is rejected at admission with a clear validation error, so mistakes fail fast at apply time rather than at run time. Referencing a label key that does not exist in the env form is also a validation error at Pod creation — unlike ConfigMap references, there is no `optional` flag here.