Kubernetes Downward API

What is it?

Data that is already known can be passed to the Pod using ConfigMap or Secret volumes. But there are a few cases where the data isn't known upfront such as Pod's IP or name as well as the data that is defined elsewhere, such as Pod's labels and annotations. How to pass this data to a container? This is where the Kubernetes Downward API comes into the picture.

The Kubernetes Downward API enables a container to access information about itself without having to interact with the Kubernetes API Server directly. This can be done in two ways:

Through Environment Variables
Through files in downwardAPI Volume

It is important to note that this isn't like a REST endpoint where the app has to hit to get the data. It's a way of having environment variables of files populated with values from Pod's specification or status.

Now let's see what are all fields available through this Downward API.

Information Available through Downward API

The pod's name
The pod's namespace
The pod's unique ID
The pod's IP
The host's IP
The pod's labels
The pod's annotations
The name of the node where the pod is executing
CPU and memory requests for each container
CPU and memory limits for each container

A more extensive list can be found in the official documentation.

Using Environment Variables

The YAML specification is taken from the official documentation.

fieldRef: Refer to a field's value using downwardAPI.
resourceFieldRef: Refer to resource-related information.
containerName: Refer to container-related metadata instead of a pod (can be container resource limits/requests, etc)

apiVersion: v1
kind: Pod
metadata:
  name: dapi-envars-fieldref
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "sh", "-c"]
      args:
      - while true; do
          echo -en '\n';
          printenv MY_POD_NAME MY_POD_NAMESPACE;
          printenv MY_POD_IP MY_CPU_REQUEST;
          sleep 10;
        done;
      resources:
        requests:
          memory: "32Mi"
          cpu: "125m"
        limits:
          memory: "64Mi"
          cpu: "250m"
      env:
        - name: MY_POD_NAME
          valueFrom:
            fieldRef: 
              fieldPath: metadata.name
        - name: MY_POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: MY_POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: MY_CPU_REQUEST
          valueFrom:
            resourceFieldRef:
              containerName: test-container # get information related a specific container rather than a pod
              resource: requests.cpu
        - name: MY_CPU_LIMIT
          valueFrom:
            resourceFieldRef:
              containerName: test-container
              resource: limits.cpu
  restartPolicy: Never

Using downwardAPI Volume Files

We must use downwardAPI volume for exposing the pod’s labels and annotations because neither can be exposed through environment variables. The reason for this is that labels and annotations can be modified when a pod is running. So when they change, Kubernetes updates the files holding them. If they were stored in environment variables, the pod needs to be restarted for the effects to take place.

apiVersion: v1
kind: Pod
metadata:
  name: kubernetes-downwardapi-volume-example
  labels:
    zone: us-est-coast
    cluster: test-cluster1
    rack: rack-22
  annotations:
    build: two
    builder: john-doe
spec:
  containers:
    - name: client-container
      image: registry.k8s.io/busybox
      command: ["sh", "-c"]
      args:
      - while true; do
          if [[ -e /etc/podinfo/labels ]]; then
            echo -en '\n\n'; cat /etc/podinfo/labels; fi;
          if [[ -e /etc/podinfo/annotations ]]; then
            echo -en '\n\n'; cat /etc/podinfo/annotations; fi;
          sleep 5;
        done;
      volumeMounts:
        - name: podinfo
          mountPath: /etc/podinfo # mount path where Kubernetes will store the information about labels and annotations
  volumes:
    - name: podinfo
      downwardAPI: # this is the volume type we'll use with downwardAPI
        items:
          - path: "labels" # name of the file in which the labels information will get saved
            fieldRef: # Refers to pod's labels
              fieldPath: metadata.labels
          - path: "annotations"
            fieldRef:
              fieldPath: metadata.annotations

Let's assume that we posted the above YAML file using the following command:

$ kubectl apply -f downward-api-files.yaml

Now according to the specification, we should have a folder path /etc/podinfo in our container. And inside that folder we should have two files named: labels and annotations. Let's check that:

$ kubectl exec kubernetes-downwardapi-volume-example -- ls /etc/podinfo
# output
annotations
labels

Yes, we have two files inside /etc/podinfo. Let's look at the contents of those two files:

$ kubectl exec kubernetes-downwardapi-volume-example -- cat /etc/podinfo/labels
# output
cluster="test-cluster1"
rack="rack-22"
zone="us-est-coast"%

$ kubectl exec kubernetes-downwardapi-volume-example -- cat /etc/podinfo/annotations
build="two"
builder="john-doe"

That's awesome. We have all the information about labels and annotations from the specification in those files.

Conclusion

By leveraging the Downward API, developers can easily access details such as the pod's name, namespace, IP address, labels, annotations, and other important metadata. This information can be utilized to make runtime decisions, and dynamically adjust application behavior.

Feedback is highly appreciated. Let me know about any improvements or suggestions. Thanks!

Chandra Kiran G's Blog