Allowing containers to consume API objects

    The Downward API contains such information as the pod’s name, project, and resource values. Containers can consume information from the downward API using environment variables or a volume plug-in.

    Fields within the pod are selected using the API type. FieldRef has two fields:

    Currently, the valid selectors in the v1 API include:

    SelectorDescription

    metadata.name

    The pod’s name. This is supported in both environment variables and volumes.

    metadata.namespace

    The pod’s namespace.This is supported in both environment variables and volumes.

    metadata.labels

    The pod’s labels. This is only supported in volumes and not in environment variables.

    metadata.annotations

    The pod’s annotations. This is only supported in volumes and not in environment variables.

    status.podIP

    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.

    Understanding how to consume container values using the downward API

    You containers can consume API values using environment variables or a volume plug-in. Depending on the method you choose, containers can consume:

    • Pod name

    • Pod project/namespace

    • Pod annotations

    • Pod labels

    Annotations and labels are available using only a volume plug-in.

    When using a container’s environment variables, use the EnvVar type’s valueFrom field (of type EnvVarSource) to specify that the variable’s value should come from a FieldRef source instead of the literal value specified by the value field.

    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

    Procedure

    To use environment variables

    1. Create a pod.yaml file:

    2. Create the pod from the pod.yaml file:

      1. $ oc create -f pod.yaml

    3. Check the container’s logs for the MY_POD_NAME and MY_POD_NAMESPACE values:

      1. $ oc logs -p dapi-env-test-pod

    You containers can consume API values using a volume plug-in.

    Containers can consume:

    • Pod name

    • Pod project/namespace

    • Pod annotations

    • Pod labels

    Procedure

    To use the volume plug-in:

    1. Create a volume-pod.yaml file:

      1. kind: Pod
      2. apiVersion: v1
      3. metadata:
      4.   labels:
      5.     zone: us-east-coast
      6.     cluster: downward-api-test-cluster1
      7.     rack: rack-123
      8.   name: dapi-volume-test-pod
      9.   annotations:
      10.     annotation1: "345"
      11.     annotation2: "456"
      12. spec:
      13.   containers:
      14.     - name: volume-test-container
      15.       image: gcr.io/google_containers/busybox
      16.       command: ["sh", "-c", "cat /tmp/etc/pod_labels /tmp/etc/pod_annotations"]
      17.       volumeMounts:
      18.         - name: podinfo
      19.           mountPath: /tmp/etc
      20.           readOnly: false
      21.   volumes:
      22.   - name: podinfo
      23.     downwardAPI:
      24.       defaultMode: 420
      25.       items:
      26.       - fieldRef:
      27.           fieldPath: metadata.name
      28.         path: pod_name
      29.       - fieldRef:
      30.           fieldPath: metadata.namespace
      31.         path: pod_namespace
      32.       - fieldRef:
      33.           fieldPath: metadata.labels
      34.         path: pod_labels
      35.       - fieldRef:
      36.           fieldPath: metadata.annotations
      37.         path: pod_annotations

    2. Create the pod from the volume-pod.yaml file:

      1. $ oc create -f volume-pod.yaml

    3. Check the container’s logs and verify the presence of the configured fields:

      1. $ oc logs -p dapi-volume-test-pod

      Example output

      1. cluster=downward-api-test-cluster1
      2. rack=rack-123
      3. zone=us-east-coast
      5. annotation2=456
      6. kubernetes.io/config.source=api

    When creating pods, you can use the Downward API to inject information about computing resource requests and limits so that image and application authors can correctly create an image for specific environments.

    You can do this using environment variable or a volume plug-in.

    When creating pods, you can use the Downward API to inject information about computing resource requests and limits using environment variables.

    Procedure

    To use environment variables:

    1. When creating a pod configuration, specify environment variables that correspond to the contents of the resources field in the **spec.container** field:

      1. ....
      2. spec:
      3.   containers:
      4.     - name: test-container
      5.       image: gcr.io/google_containers/busybox:1.24
      6.       command: [ "/bin/sh", "-c", "env" ]
      7.       resources:
      8.         requests:
      9.           memory: "32Mi"
      10.           cpu: "125m"
      11.         limits:
      12.           memory: "64Mi"
      13.           cpu: "250m"
      14.       env:
      15.         - name: MY_CPU_REQUEST
      16.           valueFrom:
      17.             resourceFieldRef:
      18.               resource: requests.cpu
      19.         - name: MY_CPU_LIMIT
      20.           valueFrom:
      21.             resourceFieldRef:
      22.               resource: limits.cpu
      23.         - name: MY_MEM_REQUEST
      24.           valueFrom:
      25.             resourceFieldRef:
      26.               resource: requests.memory
      27.         - name: MY_MEM_LIMIT
      28.           valueFrom:
      29.             resourceFieldRef:
      30.               resource: limits.memory
      31. ....

      If the resource limits are not included in the container configuration, the downward API defaults to the node’s CPU and memory allocatable values.

    2. Create the pod from the ***pod.yaml*** file:

      1. $ oc create -f pod.yaml

    When creating pods, you can use the Downward API to inject information about computing resource requests and limits using a volume plug-in.

    Procedure

    1. When creating a pod configuration, use the spec.volumes.downwardAPI.items field to describe the desired resources that correspond to the spec.resources field:

      If the resource limits are not included in the container configuration, the Downward API defaults to the node’s CPU and memory allocatable values.

    2. Create the pod from the ***volume-pod.yaml*** file:

      1. $ oc create -f volume-pod.yaml

    Consuming secrets using the Downward API

    When creating pods, you can use the downward API to inject secrets so image and application authors can create an image for specific environments.

    Procedure

    1. Create a secret.yaml file:

      1. apiVersion: v1
      2. kind: Secret
      3. metadata:
      4.   name: mysecret
      5. data:
      6.   password: cGFzc3dvcmQ=
      7.   username: ZGV2ZWxvcGVy
      8. type: kubernetes.io/basic-auth

    2. Create a Secret object from the secret.yaml file:

      1. $ oc create -f secret.yaml

    3. Create a pod.yaml file that references the username field from the above Secret object:

      1. apiVersion: v1
      2. kind: Pod
      3. metadata:
      4.   name: dapi-env-test-pod
      5. spec:
      6.     - name: env-test-container
      7.       image: gcr.io/google_containers/busybox
      8.       command: [ "/bin/sh", "-c", "env" ]
      9.       env:
      11.           valueFrom:
      12.             secretKeyRef:
      13.               name: mysecret
      14.               key: username
      15.   restartPolicy: Never

    4. Create the pod from the pod.yaml file:

      1. $ oc create -f pod.yaml

    5. Check the container’s logs for the MY_SECRET_USERNAME value:

      1. $ oc logs -p dapi-env-test-pod

    When creating pods, you can use the Downward API to inject configuration map values so image and application authors can create an image for specific environments.

    Procedure

    1. Create a ***configmap.yaml*** file:

      1. apiVersion: v1
      2. kind: ConfigMap
      3. metadata:
      4.   name: myconfigmap
      5. data:
      6.   mykey: myvalue

    2. Create a ConfigMap object from the ***configmap.yaml*** file:

      1. $ oc create -f configmap.yaml

    3. Create a ***pod.yaml*** file that references the above ConfigMap object:

    4. Create the pod from the ***pod.yaml*** file:

      1. $ oc create -f pod.yaml

    5. Check the container’s logs for the MY_CONFIGMAP_VALUE value:

      1. $ oc logs -p dapi-env-test-pod

    Referencing environment variables

    When creating pods, you can reference the value of a previously defined environment variable by using the $() syntax. If the environment variable reference can not be resolved, the value will be left as the provided string.

    Procedure

    1. Create a ***pod.yaml*** file that references an existing environment variable:

      1. apiVersion: v1
      2. kind: Pod
      3. metadata:
      4.   name: dapi-env-test-pod
      5. spec:
      6.   containers:
      7.     - name: env-test-container
      8.       image: gcr.io/google_containers/busybox
      9.       command: [ "/bin/sh", "-c", "env" ]
      10.       env:
      11.         - name: MY_EXISTING_ENV
      12.           value: my_value
      13.         - name: MY_ENV_VAR_REF_ENV
      14.           value: $(MY_EXISTING_ENV)
      15.   restartPolicy: Never

    2. Create the pod from the ***pod.yaml*** file:

      1. $ oc create -f pod.yaml

    3. Check the container’s logs for the MY_ENV_VAR_REF_ENV value:

      1. $ oc logs -p dapi-env-test-pod

    When creating a pod, you can escape an environment variable reference by using a double dollar sign. The value will then be set to a single dollar sign version of the provided value.

    Procedure

    1. Create a ***pod.yaml*** file that references an existing environment variable:

      1. apiVersion: v1
      2. kind: Pod
      3. metadata:
      4.   name: dapi-env-test-pod
      5. spec:
      6.   containers:
      7.     - name: env-test-container
      8.       image: gcr.io/google_containers/busybox
      9.       command: [ "/bin/sh", "-c", "env" ]
      10.       env:
      11.         - name: MY_NEW_ENV
      12.           value: $$(SOME_OTHER_ENV)
      13.   restartPolicy: Never

    2. Create the pod from the ***pod.yaml*** file:

      1. $ oc create -f pod.yaml