Use the Downward API

Background information

The Kubernetes Downward API provides the following methods to expose pod information that includes pod and container fields to running containers:

• Environment variables

  You can pass pod information as the value of a single environment variable into a container.

• Volume files

  You can use pod information to generate files and mount the files to the mount directories of volumes in containers.

Container Service for Kubernetes (ACK), Serverless Kubernetes (ASK), and Elastic Container Instance support the majority of commonly used fields of the Downward API. The following sections describe how to use the Downward API.

Environment variables

You can use the Downward API to pass information such as the name, namespace, and IP address of a pod into the environment variables of a container. The following table describes the values that can be obtained by using this method.

Deployment example:

apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: vk-downward-env
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
        annotations: 
            regionId: cn-beijing
            platform: Aliyun ECI
        labels:
            app: nginx
            env: test
    spec:
      containers:
      - name: nginx
        image: nginx
        env:
        - name: MY_metadata.name
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: MY_metadata.namespace
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: MY_metadata.uid
          valueFrom:
            fieldRef:
              fieldPath: metadata.uid
        - name: MY_metadata.labels
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['env']
        - name: MY_metadata.annotations
          valueFrom:
            fieldRef:
              fieldPath: metadata.annotations['regionId']
        - name: MY_status.podIP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: MY_spec.serviceAccountName
          valueFrom:
            fieldRef:
              fieldPath: spec.serviceAccountName
        - name: MY_spec.nodeName
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
      nodeName: virtual-kubelet  #Specify a virtual node name to schedule the pod to Elastic Container Instance in a Container Service for Kubernetes (ACK) cluster.

Log on to the container and check the values of environment variables. You can find that the fieldRef field has taken effect. Example:

root@default-vk-downward-env:/# env
MY_spec.nodeName=virtual-kubelet
MY_spec.serviceAccountName=default
MY_metadata.annotations=cn-beijing
MY_metadata.namespace=default
MY_metadata.uid=f4881309-f3dd-11e9-bcf9-9efaf54dcfa7
MY_metadata.name=vk-downward-env
MY_metadata.labels=test
MY_status.podIP=192.168.6.245
KUBERNETES_SERVICE_PORT_HTTPS=443
KUBERNETES_SERVICE_PORT=6443
PWD=/
PKG_RELEASE=1~buster
HOME=/root
KUBERNETES_PORT_443_TCP=tcp://172.22.*.*:443
NJS_VERSION=0.3.5
TERM=xterm
SHLVL=1
KUBERNETES_PORT_443_TCP_PROTO=tcp
KUBERNETES_PORT_443_TCP_ADDR=172.22.*.*
KUBERNETES_SERVICE_HOST=192.168.*.*
KUBERNETES_PORT=tcp://172.22.*.*:443
KUBERNETES_PORT_443_TCP_PORT=443
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
NGINX_VERSION=1.17.4
_=/usr/bin/env

Volume files

You can use the Downward API to mount pod information such as labels and annotations as a file to the mount directory of a volume in a container. The following table describes the values that can be obtained by using this method.

Deployment example:

apiVersion: apps/v1beta2 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: vk-downward-down-volume
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
        annotations: 
            regionId: cn-beijing
            platform: Aliyun ECI
        labels:
            app: nginx
            env: test
    spec:
      containers:
      - name: nginx
        image: nginx
        volumeMounts:
        - name: podinfo
          mountPath: /etc/podinfo
          readOnly: false
      volumes:
      - name: podinfo
        downwardAPI:
          items:
            - path: "metadata.name"
              fieldRef:
                fieldPath: metadata.name
            - path: "metadata.namespace"
              fieldRef:
                fieldPath: metadata.namespace
            - path: "metadata.uid"
              fieldRef:
                fieldPath: metadata.uid
            - path: "metadata.labels"
              fieldRef:
                fieldPath: metadata.labels
            - path: "metadata.annotations"
              fieldRef:
                fieldPath: metadata.annotations
      nodeName: virtual-kubelet

Log on to the container and go to the mount directory of the volume. You can find that the fieldRef field has taken effect and that the pod information specified by the fieldRef field is stored in the directory. Example:

Welcome to Alibaba Cloud Elastic Container Instance!
root@default-vk-downward-down-volume:/# cd /etc/podinfo/
root@default-vk-downward-down-volume:/etc/podinfo# ls
metadata.annotations  metadata.labels  metadata.name  metadata.namespace  metadata.uid
root@default-vk-downward-down-volume:/etc/podinfo# cat metadata.namespace 
default
root@default-vk-downward-down-volume:/etc/podinfo# cat metadata.name
vk-downward-down-volume
root@default-vk-downward-down-volume:/etc/podinfo# cat metadata.uid 
fa50b2b2-f3e3-11e9-bcf9-9efaf54dcfa7
root@default-vk-downward-down-volume:/etc/podinfo# cat metadata.annotations 
platform="Aliyun ECI"
regionId="cn-beijing"
root@default-vk-downward-down-volume:/etc/podinfo# cat metadata.labels 
app="nginx"
env="test"
root@default-vk-downward-down-volume:/etc/podinfo#