Standard Kubernetes clusters support the following ways of exposing pod and container fields to a running container:

  • Environment variable
  • DownwardAPIVolumeFile

These two ways of exposing pod and container fields are together called the Downward API.

Currently, when Elastic Container Instance (ECI) is used with Alibaba Cloud Container Service for Kubernetes and Alibaba Cloud Serverless Kubernetes, ECI supports most of the common fields that can be exposed through the Downward API. This topic describes how to use the Downward API in an ECI.

Environment variable

You can use the fieldRef field to assign the values of the following ECI fields to environment variables: metadata.name, metadata.namespace, metadata.uid, metadata.labels['<KEY>'], and metadata.annotations['<KEY>']. These fields respectively indicate the ECI name, ECI namespace, ECI UID, key of a single label (for example, mylabel), and key of a single annotation.

You can also use the fieldRef field to assign the values of the following spec and status fields to environment variables:

spec.serviceAccountName

spec.nodeName

status.podIP

The following configuration file of a sample deployment shows how to use the fieldRef field to assign the values of ECI fields to environment variables: 

apiVersion: apps/v1beta2 # For versions earlier than 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-node-eci-0

Log on to the container and check the values of environment variables. You can find that all the environment variables are assigned the values specified by the fieldRef field. 

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.128.1:443
NJS_VERSION=0.3.5
TERM=xterm
SHLVL=1
KUBERNETES_PORT_443_TCP_PROTO=tcp
KUBERNETES_PORT_443_TCP_ADDR=172.22.128.1
KUBERNETES_SERVICE_HOST=192.168.6.120
KUBERNETES_PORT=tcp://172.22.128.1: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

DownwardAPIVolumeFile

You can use the fieldRef field to pass the values of the following ECI fields to DownwardAPIVolumeFiles: metadata.name, metadata.namespace, metadata.uid, metadata.labels['<KEY>'], and metadata.annotations['<KEY>']. These fields respectively indicate the ECI name, ECI namespace, ECI UID, key of a single label (for example, mylabel), and key of a single annotation. The fields are the same as those whose values can be assigned to environment variables. The method of passing the values of these fields to DownwardAPIVolumeFiles is the same as that for assigning the values to environment variables.

In addition, a DownwardAPIVolumeFile can obtain all the labels or annotations of an ECI through the fieldRef field.

metadata.labels: all the labels of the ECI. Each label is stored in the format of label-key="label-value" and occupies one row.

metadata.annotations: all the annotations of the ECI. Each annotation is stored in the format of annotation-key="annotation-value" and occupies one row.

The following configuration file of a sample deployment shows how to use the fieldRef field to assign the values of ECI fields to DownwardAPIVolumeFiles: 

apiVersion: apps/v1beta2 # For versions earlier than 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-node-eci-0

Log on to the container and go to the directory to which the Downward API volume is mounted. You can find that all the specified DownwardAPIVolumeFiles are generated in the directory and they store the values specified by the fieldRef field. 

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#

Currently, you can only pass the values of ECI fields to DownwardAPIVolumeFiles. You cannot pass the values of container fields to DownwardAPIVolumeFiles. For example, the values of the following container fields cannot be passed to DownwardAPIVolumeFiles: 

limits.cpu
requests.cpu
limits.memory
requests.memory
limits.ephemeral-storage
requests.ephemeral-storage