All Products
Search
Document Center

Obtain the metadata of a container

Last Updated: Sep 16, 2021

This topic describes how to obtain the metadata of a container.

Elastic Container Instance provides the following methods to expose pod (elastic container instance) information and container metadata to containers in the running state:

Method 1: Use MetaServer to access metadata

You can perform the following steps to obtain the metadata of an elastic container instance:

  1. Connect to a container. For more information, see Debug an elastic container instance.

  2. Run the following command to access the root directory of the metadata:

    curl http://100.100.100.200/latest/meta-data/
  3. Append the name of a metadata item to the command to obtain information about the item.

    For example, run the following command to obtain the ID of the elastic container instance:

    curl http://100.100.100.200/latest/meta-data/instance-id

    The following table describes the metadata items that you can obtain for an elastic container instance.

    Metadata item

    Description

    /dns-conf/nameservers

    The Domain Name System (DNS) configurations of the elastic container instance.

    /eipv4

    The elastic IPv4 address of the elastic container instance.

    /hostname

    The hostname of the elastic container instance, which is the ContainerGroupName value.

    /instance-id

    The ID of the elastic container instance.

    /mac

    The media access control (MAC) address of the elastic container instance.

    /network/interfaces/

    The MAC addresses of the network interface controllers (NICs).

    /network/interfaces/macs/[mac]/network-interface-id

    The ID of the NIC. Replace [mac] with the MAC address of the elastic container instance.

    /network/interfaces/macs/[mac]/netmask

    The subnet mask of the NIC.

    /network/interfaces/macs/[mac]/vswitch-cidr-block

    The IPv4 CIDR block of the vSwitch to which the NIC belongs.

    /network/interfaces/macs/[mac]/vpc-cidr-block

    The IPv4 CIDR block of the virtual private cloud (VPC) to which the NIC belongs.

    /network/interfaces/macs/[mac]/private-ipv4s

    The private IPv4 addresses assigned to the NIC.

    /network/interfaces/macs/[mac]/vpc-ipv6-cidr-blocks

    The IPv6 CIDR block of the VPC to which the NIC belongs. This item is applicable only to the elastic container instances that reside within VPCs and are assigned IPv6 addresses.

    /network/interfaces/macs/[mac]/vswitch-id

    The ID of the vSwitch in the same VPC as the security group of the NIC.

    /network/interfaces/macs/[mac]/vpc-id

    The ID of the VPC to which the security group of the NIC belongs.

    /network/interfaces/macs/[mac]/primary-ip-address

    The primary private IP address of the NIC.

    /network/interfaces/macs/[mac]/gateway

    The IPv4 gateway address of the VPC to which the NIC belongs.

    /instance/max-netbw-egress

    The maximum outbound internal bandwidth of the elastic container instance. Unit: Kbit/s.

    /instance/max-netbw-ingerss

    The maximum inbound internal bandwidth of the elastic container instance. Unit: Kbit/s.

    /network/interfaces/macs/[mac]/ipv6s

    The IPv6 addresses assigned to the NIC. This item is applicable only to the elastic container instances that reside within VPCs and are assigned IPv6 addresses.

    /network/interfaces/macs/[mac]/ipv6-gateway

    The IPv6 gateway address of the VPC to which the NIC belongs.

    /network/interfaces/macs/[mac]/vswitch-ipv6-cidr-block

    The IPv6 CIDR block of the vSwitch to which the NIC is connected. This item is applicable only to the elastic container instances that reside within VPCs and are assigned IPv6 addresses.

    /private-ipv4

    The private IPv4 address of the elastic container instance.

    /ntp-conf/ntp-servers

    The address of the Network Time Protocol (NTP) server.

    /owner-account-id

    The ID of the Alibaba Cloud account to which the elastic container instance belongs.

    /region-id

    The region ID of the elastic container instance.

    /serial-number

    The serial number of the elastic container instance.

    /vpc-id

    The ID of the VPC to which the elastic container instance belongs.

    /vpc-cidr-block

    The CIDR block of the VPC to which the elastic container instance belongs.

    /vswitch-cidr-block

    The CIDR block of the vSwitch to which the elastic container instance is connected.

    /vswitch-id

    The ID of the vSwitch to which the elastic container instance is connected.

    /zone-id

    The zone ID of the elastic container instance.

    /ram/security-credentials/[role-name]

    The temporary Security Token Service (STS) credentials generated for the Resource Access Management (RAM) role of the elastic container instance. You can obtain the STS credentials only after you specify a RAM role to an elastic container instance. Replace [role-name] with the name of the RAM role. If [role-name] is not specified, the name of the RAM role is returned.

Method 2: Configure environment variables for a container

You can obtain the information about an elastic container instance by configuring the values of environment variables for a container in the instance. The metadata items of an elastic container instance that can be obtained in this manner include the instance ID, instance name, region ID of the instance, zone ID of the instance, and container name.

Key

Value

Description

eci_id

__ECI_ID__

The ID of the elastic container instance.

eci_name

__ECI_NAME__

The name of the elastic container instance.

region_id

__REGION_ID__

The region ID of the elastic container instance.

zone_id

__ZONE_ID__

The zone ID of the elastic container instance.

container_name

__CONTAINER_NAME__

The name of the container in the elastic container instance.

params = {
        'Container.1.Image': 'registry-vpc.cn-shanghai.aliyuncs.com/eci_open/nginx:alpine',
        'Container.1.Name': 'nginx',
        'SecurityGroupId': 'sg-uf6biempwqvodk7a****',
        'VSwitchId': 'vsw-uf6mhqg2wiq9iifhn****',
        'ContainerGroupName': 'test-env',
        # Configure environment variables.
        'Container.1.EnvironmentVar.1.Key': 'eci_id',
        'Container.1.EnvironmentVar.2.Key': 'eci_name',
        'Container.1.EnvironmentVar.3.Key': 'region_id',
        'Container.1.EnvironmentVar.4.Key': 'zone_id',
        'Container.1.EnvironmentVar.5.Key': 'container_name',
        'Container.1.EnvironmentVar.1.Value': '__ECI_ID__',
        'Container.1.EnvironmentVar.2.Value': '__ECI_NAME__',
        'Container.1.EnvironmentVar.3.Value': '__REGION_ID__',
        'Container.1.EnvironmentVar.4.Value': '__ZONE_ID__',
        'Container.1.EnvironmentVar.5.Value': '__CONTAINER_NAME__',
    }

You can log on to the Elastic Container Instance console and connect to the container to check whether the configured environment variables have taken effect. For more information, see Debug an elastic container instance.view

Method 3: Use the Downward API

The Kubernetes Downward API provides the following methods to expose pod information to running containers:

  • Pass pod information to environment variables of a container

    You can pass each piece of pod information as the value of a single environment variable to a container.

  • Mount pod information as a file to the directory where a volume is mounted

    You can generate a file from pod information and mount the file to the directory where a volume is mounted in a container.

Alibaba Cloud Container Service for Kubernetes (ACK), Serverless Kubernetes (ASK), and Elastic Container Instance support the majority of fields commonly used by the Downward API.

  • Pass pod information to environment variables of a container

You can use the Downward API to pass information such as the name, namespace, and IP address of a pod to environment variables of a container. The following table describes the pod parameters whose values can be passed to environment variables of a container.

Parameter

Description

metadata.name

The name of the pod.

metadata.namespace

The namespace of the pod.

metadata.uid

The UID of the pod.

metadata.labels['<KEY>']

The label value of the pod.

metadata.annotations['<KEY>']

The annotation value of the pod.

spec.serviceAccountName

The name of the pod service account.

spec.nodeName

The name of the node.

status.podIP

The IP address of the node.

The following Deployment sample code provides an example on how to pass the information of a pod to the environment variables of a container:

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

Log on to the container and view the environment variables. You can find that fieldRef has taken effect. Examples of container environment variables to which pod information is passed after fieldRef takes effect:

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 directory where a volume is mounted in a container. The following table describes the pod parameters whose values that can be mounted to the directory where a volume is mounted in a container.

Parameter

Description

metadata.name

The name of the pod.

metadata.namespace

The namespace of the pod.

metadata.uid

The UID of the pod.

metadata.labels['<KEY>']

The label value of the pod.

metadata.annotations['<KEY>']

The annotation value of the pod.

metadata.labels

All labels of the pod.

metadata.annotations

All annotations of the pod.

Note

You can use the Downward API to mount pod fields, but you cannot mount container fields such as limits.cpu, requests.cpu, limits.memory, requests.memory, limits.ephemeral-storage, and requests.ephemeral-storage.

The following Deployment sample code provides an example on how to mount the information of a pod as a file to the directory where a volume is mounted in a container:

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 directory where the volume is mounted. You can find that fieldRef has taken effect and that the pod information specified in fieldRef is stored in the directory. Example of pod information stored in the directory where a volume is mounted in a container:

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#