Obtain metadata within a container - Elastic Container Instance

Applications running inside ECI pods often need instance-level or pod-level information — such as the pod name, ID, IP address, and network interface controller (NIC) — at runtime for logging, service discovery, dynamic configuration, and monitoring. ECI exposes this metadata through three methods, each suited to different deployment scenarios.

Method	How it works	Best for
MetaServer	Query a link-local HTTP endpoint from inside the container	Instance-level fields (ID, IP, NIC, RAM credentials) at runtime
Environment variables	Inject ECI-specific values into container env vars at pod creation	Simple key-value lookups without shell access to the metadata endpoint
Downward API	Kubernetes-native mechanism to expose pod fields as env vars or volume files	ACK deployments needing pod-level fields (name, namespace, labels, annotations)

Note: The integration of Container Service for Kubernetes (ACK) and Elastic Container Instance supports the most fields used by the Downward API.

Method 1: Use MetaServer to access metadata

MetaServer is a link-local HTTP service available at http://100.100.100.200 from inside any ECI container. It exposes instance-level metadata fields over plain HTTP.

Prerequisites

Before you begin, ensure that you have:

curl installed in the container. If not installed, install it before proceeding.
Connected to the container. See Connect to an elastic container instance.

Query a metadata field

Run the following command from inside the container, replacing <metadata> with the field path you want to query:

curl http://100.100.100.200/latest/meta-data/<metadata>

For example, to get the instance ID:

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

Available metadata fields

Field	Description
`/dns-conf/nameservers`	Domain Name System (DNS) configuration of the instance
`/eipv4`	Elastic IPv4 address of the instance
`/hostname`	Hostname of the instance, equal to the `ContainerGroupName` value
`/instance-id`	ID of the elastic container instance
`/mac`	MAC address of the instance
`/network/interfaces/`	MAC addresses of all NICs
`/network/interfaces/macs/[mac]/network-interface-id`	NIC ID. Replace `[mac]` with the instance MAC address.
`/network/interfaces/macs/[mac]/netmask`	Subnet mask of the NIC
`/network/interfaces/macs/[mac]/vswitch-cidr-block`	IPv4 CIDR block of the vSwitch connected to the NIC
`/network/interfaces/macs/[mac]/vpc-cidr-block`	IPv4 CIDR block of the virtual private cloud (VPC)
`/network/interfaces/macs/[mac]/private-ipv4s`	Private IPv4 addresses assigned to the NIC
`/network/interfaces/macs/[mac]/vpc-ipv6-cidr-blocks`	IPv6 CIDR block of the VPC. Applies only to instances with IPv6 addresses assigned.
`/network/interfaces/macs/[mac]/vswitch-id`	ID of the vSwitch in the same VPC as the NIC's security group
`/network/interfaces/macs/[mac]/vpc-id`	ID of the VPC where the NIC's security group resides
`/network/interfaces/macs/[mac]/primary-ip-address`	Primary private IP address of the NIC
`/network/interfaces/macs/[mac]/gateway`	IPv4 gateway address of the NIC
`/instance/max-netbw-egress`	Maximum outbound internal bandwidth. Unit: Kbit/s.
`/instance/max-netbw-ingerss`	Maximum inbound internal bandwidth. Unit: Kbit/s.
`/network/interfaces/macs/[mac]/ipv6s`	IPv6 addresses assigned to the NIC. Applies only to instances with IPv6 addresses assigned.
`/network/interfaces/macs/[mac]/ipv6-gateway`	IPv6 gateway address of the VPC
`/network/interfaces/macs/[mac]/vswitch-ipv6-cidr-block`	IPv6 CIDR block of the vSwitch. Applies only to instances with IPv6 addresses assigned.
`/private-ipv4`	Private IPv4 address of the instance
`/ntp-conf/ntp-servers`	Network Time Protocol (NTP) server address
`/owner-account-id`	ID of the Alibaba Cloud account that owns the instance
`/region-id`	Region ID
`/serial-number`	Serial number of the instance
`/vpc-id`	ID of the VPC where the instance resides
`/vpc-cidr-block`	CIDR block of the VPC
`/vswitch-cidr-block`	CIDR block of the connected vSwitch
`/vswitch-id`	ID of the connected vSwitch
`/zone-id`	Zone ID
`/ram/security-credentials/[role-name]`	Temporary Security Token Service (STS) credentials for the Resource Access Management (RAM) role. Requires a RAM role attached to the instance. Replace `[role-name]` with the RAM role name. If you omit the role name, the instance name is returned instead.

Method 2: Configure environment variables

Inject ECI-specific metadata directly into container environment variables at pod creation time. The following __PLACEHOLDER__ values are resolved to the actual instance values when the pod starts.

Supported fields

Environment variable	Value placeholder	Description
`eci_id`	`__ECI_ID__`	ID of the elastic container instance
`eci_name`	`__ECI_NAME__`	Name of the elastic container instance
`region_id`	`__REGION_ID__`	Region ID
`zone_id`	`__ZONE_ID__`	Zone ID
`container_name`	`__CONTAINER_NAME__`	Name of the container

Example deployment

The following Deployment injects all five metadata fields into the nginx container:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        env:
          - name: eci_id
            value: __ECI_ID__
          - name: eci_name
            value: __ECI_NAME__
          - name: region_id
            value: __REGION_ID__
          - name: zone_id
            value: __ZONE_ID__
          - name: container_name
            value: __CONTAINER_NAME__

After the pod starts, log in to the container and inspect the environment variables to confirm the values have been resolved:

root@test-885c644d6-bgkjp:/# env
HOSTNAME=test-885c644d6-bgkjp
NJS_VERSION=1.14.2.0.2.6-1~stretch
region_id=cn-beijing
NGINX_VERSION=1.14.2-1~stretch
KUBERNETES_PORT_443_TCP_PROTO=tcp
KUBERNETES_PORT_443_TCP_ADDR=192.168.xxx
KUBERNETES_PORT=tcp://192.168.xxx:443
PWD=/
HOME=/root
KUBERNETES_SERVICE_PORT_HTTPS=6443
KUBERNETES_PORT_443_TCP_PORT=443
KUBERNETES_PORT_443_TCP=tcp://192.168.xxx:443
TERM=xterm
container_name=nginx
eci_id=eci-2zeig58fozpdlxxx
SHLVL=1
KUBERNETES_SERVICE_PORT=6443
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
zone_id=cn-beijing-g
eci_name=test-885c644d6-bgkjp
KUBERNETES_SERVICE_HOST=172.16.xxx
ECI_CONTAINER_TYPE=normal
_=/usr/bin/env

Method 3: Use the Downward API

The Kubernetes Downward API exposes pod-level information to containers without requiring application code changes. ACK + ECI supports most standard Downward API fields.

Two mechanisms are available:

Environment variables — each pod field is injected as a single env var value
Volume files — pod fields are written to files mounted inside the container

Pass pod information as environment variables

Use fieldRef in the container spec to map pod fields to environment variables.

Supported fields

Field path	Description
`metadata.name`	Name of the pod
`metadata.namespace`	Namespace of the pod
`metadata.uid`	UID of the pod
`metadata.labels['<KEY>']`	Value of a specific pod label
`metadata.annotations['<KEY>']`	Value of a specific pod annotation. See Pod annotations.
`spec.serviceAccountName`	Name of the pod's service account
`spec.nodeName`	Name of the node
`status.podIP`	IP address of the pod

Example deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: 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
            alibabacloud.com/eci: "true"
    spec:
      containers:
      - name: nginx
        image: registry-vpc.cn-beijing.aliyuncs.com/eci_open/nginx:1.14.2
        env:
        - name: METADATA_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: METADATA_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: METADATA_UID
          valueFrom:
            fieldRef:
              fieldPath: metadata.uid
        - name: METADATA_LABELS
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['env']
        - name: METADATA_ANNOTATIONS_REGION
          valueFrom:
            fieldRef:
              fieldPath: metadata.annotations['regionId']
        - name: METADATA_ANNOTATIONS_ECI_INSTANCE_ID
          valueFrom:
            fieldRef:
              fieldPath: metadata.annotations['k8s.aliyun.com/eci-instance-id']
        - name: STATUS_POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: SPEC_SERVICE_ACCOUNT_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.serviceAccountName

After the pod starts, log in to the container and inspect the environment variables to confirm the fieldRef values have been resolved:

root@downward-env-9dbdd674d-v72wk:/# env
SPEC_SERVICE_ACCOUNT_NAME=default
HOSTNAME=downward-env-9dbdd674d-v72wk
NJS_VERSION=1.14.2.0.2.6-1~stretch
METADATA_UID=98f07fbb-707d-4519-a776-8dc0324f1cb9
NGINX_VERSION=1.14.2-1~stretch
KUBERNETES_PORT_443_TCP_PROTO=tcp
KUBERNETES_PORT_443_TCP_ADDR=192.168.xxx
STATUS_POD_IP=172.16.1xxx
METADATA_NAMESPACE=default
METADATA_NAME=downward-env-9dbdd674d-v72wk
KUBERNETES_PORT=tcp://192.168.xxx:443
PWD=/
HOME=/root
KUBERNETES_SERVICE_PORT_HTTPS=6443
KUBERNETES_PORT_443_TCP_PORT=443
METADATA_ANNOTATIONS_ECI_INSTANCE_ID=eci-2zegqxj2gygpxxx
METADATA_LABELS=test
KUBERNETES_PORT_443_TCP=tcp://192.168.xxx:443
TERM=xterm
SHLVL=1
METADATA_ANNOTATIONS_REGION=cn-beijing
KUBERNETES_SERVICE_PORT=6443
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
KUBERNETES_SERVICE_HOST=172.16.xxx
ECI_CONTAINER_TYPE=normal
_=/usr/bin/env

Mount pod information as a volume file

Use a downwardAPI volume to write pod fields to files inside the container. Each item maps a field path to a file at the specified path inside the volume.

Supported fields

Field path	Description
`metadata.name`	Name of the pod
`metadata.namespace`	Namespace of the pod
`metadata.uid`	UID of the pod
`metadata.labels['<KEY>']`	Value of a specific pod label
`metadata.annotations['<KEY>']`	Value of a specific pod annotation
`metadata.labels`	All labels of the pod
`metadata.annotations`	All annotations of the pod

Note: The Downward API supports pod-level fields only. Container-level resource fields — limits.cpu, requests.cpu, limits.memory, requests.memory, limits.ephemeral-storage, and requests.ephemeral-storage — are not supported.

Example deployment

The following Deployment mounts pod metadata to /etc/podinfo inside the container:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: 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
            alibabacloud.com/eci: "true"
    spec:
      containers:
      - name: nginx
        image: registry-vpc.cn-beijing.aliyuncs.com/eci_open/nginx:1.14.2
        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

After the pod starts, log in to the container and list the files under /etc/podinfo to confirm the volume is mounted and pod fields are written to the directory:

~$ kubectl exec -it downward-down-volume-656b8b48bc-r5xsh -- bash
root@downward-down-volume-656b8b48bc-r5xsh:/# cd /etc/podinfo/
root@downward-down-volume-656b8b48bc-r5xsh:/etc/podinfo# ls
metadata.annotations  metadata.labels  metadata.name  metadata.namespace  metadata.uid
root@downward-down-volume-656b8b48bc-r5xsh:/etc/podinfo# cat metadata.namespace
defaultroot@downward-down-volume-656b8b48bc-r5xsh:/etc/podinfo# cat metadata.name
downward-down-volume-656b8b48bc-r5xshroot@downward-down-volume-656b8b48bc-r5xsh:/etc/podinfo# cat metadata.uid
bd5b8161-19d9-455a-9786-48f72f0dcf9croot@downward-down-volume-656b8b48bc-r5xsh:/etc/podinfo# cat metadata.annotations
ProviderCreate="done"
k8s.aliyun.com/cluster-dns=""
k8s.aliyun.com/cluster-domain="cluster.local"
k8s.aliyun.com/eci-client-token="9ca100f5-98fe-48ad-965e-ff17a2055c25"
k8s.aliyun.com/eci-created-by-template="true"
k8s.aliyun.com/eci-drop-apiserver-interactive-caps=""
k8s.aliyun.com/eci-instance-cpu="2.0"
k8s.aliyun.com/eci-instance-id="eci-2ze0imdty5xxx6"
k8s.aliyun.com/eci-instance-mem="4.0"
k8s.aliyun.com/eci-instance-spec="2.0-4.0Gi"
k8s.aliyun.com/eci-instance-zone="cn-beijing-k"
k8s.aliyun.com/eci-kube-proxy-enabled="true"
k8s.aliyun.com/eci-matched-image-cache="imc-2zee9fyxxxb"
k8s.aliyun.com/eci-request-id="1E355E5B-4BF2-5728-9xxxA5D4"
k8s.aliyun.com/eci-schedule-result="finished"
k8s.aliyun.com/eci-security-group="sg-2xxx4mcws1p31pvf"
k8s.aliyun.com/eci-vpc="vpc-2zeghwzptn5xxx42d"
k8s.aliyun.com/eci-vswitch="vsw-2zevanrxxxryxs6ll"
k8s.aliyun.com/eni-instance-id="eni-2zexxxw5atyaiqua"
k8s.aliyun.com/k8s-version="v1.24.6-aliyun.1"
k8s.aliyun.com/pod-ip-addrs="172.16.5.xxx"
k8s.aliyun.com/vk-version="v2.7.5-2022-11-04-09-42-UTC"
kubernetes.io/pod-stream-port="10250"
kubernetes.io/psp="ack.privileged"
platform="Aliyun ECI"
regionId="cn-beijing"root@downward-down-volume-656b8b48bc-r5xsh:/etc/podinfo# cat metadata.labels
alibabacloud.com/eci="true"
app="nginx"
env="test"