Following this example, you will create a pod with a downward API volume. A downward API volume is a k8s volume plugin with the ability to save some pod information in a plain text file. The pod information can be for example some metadata or a container’s resources.
Supported metadata fields:
metadata.annotationsmetadata.namespacemetadata.namemetadata.labels
Supported container’s resources:
limits.cpulimits.memoryrequests.cpurequests.memory
Step Zero: Prerequisites
This example assumes you have a Kubernetes cluster installed and running, and the kubectl command line tool somewhere in your path. Please see the gettingstarted for installation instructions for your platform.
Step One: Create the pod
Use the dapi-volume.yaml file to create a Pod with a downward API volume which stores pod labels and pod annotations to /etc/labels and /etc/annotations respectively.
$ kubectl create -f docs/user-guide/downward-api/volume/dapi-volume.yaml
Step Two: Examine pod/container output
The pod displays (every 5 seconds) the content of the dump files which can be executed via the usual kubectl log command
$ kubectl logs kubernetes-downwardapi-volume-example
cluster="test-cluster1"
rack="rack-22"
zone="us-est-coast"
build="two"
builder="john-doe"
kubernetes.io/config.seen="2015-08-24T13:47:23.432459138Z"
kubernetes.io/config.source="api"
Internals
In pod’s /etc directory one may find the file created by the plugin (system files elided):
$ kubectl exec kubernetes-downwardapi-volume-example -i -t -- sh
/ # ls -laR /etc
/etc:
total 4
drwxrwxrwt 3 0 0 120 Jun 1 19:55 .
drwxr-xr-x 17 0 0 4096 Jun 1 19:55 ..
drwxr-xr-x 2 0 0 80 Jun 1 19:55 ..6986_01_06_15_55_10.473583074
lrwxrwxrwx 1 0 0 31 Jun 1 19:55 ..data -> ..6986_01_06_15_55_10.473583074
lrwxrwxrwx 1 0 0 18 Jun 1 19:55 annotations -> ..data/annotations
lrwxrwxrwx 1 0 0 13 Jun 1 19:55 labels -> ..data/labels
/etc/..6986_01_06_15_55_10.473583074:
total 8
drwxr-xr-x 2 0 0 80 Jun 1 19:55 .
drwxrwxrwt 3 0 0 120 Jun 1 19:55 ..
-rw-r--r-- 1 0 0 129 Jun 1 19:55 annotations
-rw-r--r-- 1 0 0 59 Jun 1 19:55 labels
/ #
The file labels is stored in a temporary directory (..6986_01_06_15_55_10.473583074 in the example above) which is symlinked to by ..data. Symlinks for annotations and labels in /etc point to files containing the actual metadata through the ..data indirection. This structure allows for dynamic atomic refresh of the metadata: updates are written to a new temporary directory, and the ..data symlink is updated atomically using rename(2).
Example of downward API volume with container resources
Use the docs/user-guide/downward-api/volume/dapi-volume-resources.yaml file to create a Pod with a downward API volume which stores its container’s limits and requests in /etc.
$ kubectl create -f docs/user-guide/downward-api/volume/dapi-volume-resources.yaml
Examine pod/container output
In pod’s /etc directory one may find the files created by the plugin:
$ kubectl exec kubernetes-downwardapi-volume-example -i -t -- sh
/ # ls -alR /etc
/etc:
total 4
drwxrwxrwt 3 0 0 160 Jun 1 19:47 .
drwxr-xr-x 17 0 0 4096 Jun 1 19:48 ..
drwxr-xr-x 2 0 0 120 Jun 1 19:47 ..6986_01_06_15_47_23.076909525
lrwxrwxrwx 1 0 0 31 Jun 1 19:47 ..data -> ..6986_01_06_15_47_23.076909525
lrwxrwxrwx 1 0 0 16 Jun 1 19:47 cpu_limit -> ..data/cpu_limit
lrwxrwxrwx 1 0 0 18 Jun 1 19:47 cpu_request -> ..data/cpu_request
lrwxrwxrwx 1 0 0 16 Jun 1 19:47 mem_limit -> ..data/mem_limit
lrwxrwxrwx 1 0 0 18 Jun 1 19:47 mem_request -> ..data/mem_request
/etc/..6986_01_06_15_47_23.076909525:
total 16
drwxr-xr-x 2 0 0 120 Jun 1 19:47 .
drwxrwxrwt 3 0 0 160 Jun 1 19:47 ..
-rw-r--r-- 1 0 0 1 Jun 1 19:47 cpu_limit
-rw-r--r-- 1 0 0 1 Jun 1 19:47 cpu_request
-rw-r--r-- 1 0 0 8 Jun 1 19:47 mem_limit
-rw-r--r-- 1 0 0 8 Jun 1 19:47 mem_request
/ # cat /etc/cpu_limit
1
/ # cat /etc/mem_limit
67108864
/ # cat /etc/cpu_request
1
/ # cat /etc/mem_request
33554432