Chapter 29. Downward API
29.1. Overview
It is common for containers to consume information about API objects. The downward API is a mechanism that allows containers to do this without coupling to OpenShift Enterprise. Containers can consume information from the downward API using environment variables or a volume plug-in.
29.2. Selecting Fields
Fields within the pod are selected using the FieldRef API type. FieldRef has two fields:
| Field | Description |
|---|---|
|
| The path of the field to select, relative to the pod. |
|
|
The API version to interpret the |
Currently, these are the valid selectors in the v1 API:
| Selector | Description |
|---|---|
|
| The pod’s name. This is supported in both environment variables and volumes. |
|
| The pod’s namespace.This is supported in both environment variables and volumes. |
|
| The pod’s labels. This is only supported in volumes and not in environment variables. |
|
| The pod’s annotations. This is only supported in volumes and not in environment variables. |
|
| The pod’s IP. This is only supported in environment variables and not volumes. |
The apiVersion field, if not specified, defaults to the API version of the enclosing pod template.
In the future, more information, such as resource limits for pods and information about services, will be available using the downward API.
29.3. Using Environment Variables
One mechanism for consuming the downward API is using a container’s environment variables. The EnvVar type’s valueFrom field (of type EnvVarSource) is used to specify that the variable’s value should come from a FieldRef source instead of the literal value specified by the value field. In the future, additional sources may be supported; currently the source’s fieldRef field is used to select a field from the downward API.
Only constant attributes of the pod can be consumed this way, as environment variables cannot be updated once a process is started in a way that allows the process to be notified that the value of a variable has changed. The fields supported using environment variables are:
- Pod name
- Pod namespace
For example:
Create a
pod.jsonfile:apiVersion: v1 kind: Pod metadata: name: dapi-env-test-pod spec: containers: - name: env-test-container image: gcr.io/google_containers/busybox command: [ "/bin/sh", "-c", "env" ] env: - name: MY_POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: MY_POD_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace restartPolicy: NeverCreate the pod from the
pod.jsonfile:$ oc create -f pod.json
Check the container’s logs:
$ oc logs -p dapi-env-test-pod
You should see
MY_POD_NAMEandMY_POD_NAMESPACEin the logs.
29.4. Using the Volume Plug-in
Another mechanism for consuming the downward API is using a volume plug-in. The downward API volume plug-in creates a volume with configured fields projected into files. The metadata field of the VolumeSource API object is used to configure this volume. The plug-in supports the following fields:
- Pod name
- Pod namespace
- Pod annotations
- Pod labels
Example 29.1. Downward API Volume Plug-in Configuration
spec:
volumes:
- name: podinfo
metadata: 1
items: 2
- name: "labels" 3
fieldRef:
fieldPath: metadata.labels 4For example:
Create a
volume-pod.jsonfile:kind: Pod apiVersion: v1 metadata: labels: zone: us-east-coast cluster: downward-api-test-cluster1 rack: rack-123 name: dapi-volume-test-pod annotations: annotation1: 345 annotation2: 456 spec: containers: - name: volume-test-container image: gcr.io/google_containers/busybox command: ["sh", "-c", "cat /etc/labels /etc/annotations"] volumeMounts: - name: podinfo mountPath: /etc readOnly: false volumes: - name: podinfo metadata: items: - name: "labels" fieldRef: fieldPath: metadata.labels - name: "annotations" fieldRef: fieldPath: metadata.annotations restartPolicy: NeverCreate the pod from the
volume-pod.jsonfile:$ oc create -f volume-pod.json
Check the container’s logs and verify the presence of the configured fields:
$ oc logs -p dapi-volume-test-pod cluster=downward-api-test-cluster1 rack=rack-123 zone=us-east-coast annotation1=345 annotation2=456 kubernetes.io/config.source=api
