Configure the /etc/hosts file of an Elastic Container Instance-based pod - Elastic Container Instance

The k8s.aliyun.com/eci-custom-hosts annotation lets you add custom entries to a pod's /etc/hosts file at creation time. This is useful when containers need to resolve a domain name to a specific IP address — for example, when pulling images from a self-managed image repository.

Do not modify /etc/hosts directly inside a running container, as manual changes may not persist.

Prerequisites

Before you begin, ensure that you have:

A Kubernetes cluster with Elastic Container Instance (ECI) support enabled
Permission to create Deployment resources

How it works

When you add the k8s.aliyun.com/eci-custom-hosts annotation to a pod, ECI injects the specified host-to-IP mappings into /etc/hosts.

Each mapping uses the following JSON format:

{"host":"<domain-name>","ip":"<ip-address>"}

To specify multiple mappings, use a JSON array:

[{"host":"example.com","ip":"100.100.XX.XX"},{"host":"aliyundoc.com","ip":"100.100.XX.XX"}]

Important

Each object maps exactly one domain name to one IP address. To map multiple domains to the same IP, add a separate object for each domain.

Constraints:

Add the annotation at pod creation time. Adding or modifying the annotation on an existing pod has no effect.
For Deployments, place the annotation in spec.template.metadata.annotations, not in the top-level metadata.

Add custom host entries

The following example creates a Deployment with two custom host entries. The nginx container pulls from example.com and the busybox container pulls from aliyundoc.com. Both domains resolve to IP addresses specified in the annotation.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: test
  template:
    metadata:
      name: test
      labels:
        app: test
        alibabacloud.com/eci: "true"
      annotations:
        k8s.aliyun.com/eci-custom-hosts: "[{\"host\":\"example.com\",\"ip\":\"100.100.XX.XX\"},{\"host\":\"aliyundoc.com\",\"ip\":\"100.100.XX.XX\"}]"
    spec:
      containers:
      - name: nginx
        image: example.com/test/nginx:latest
        ports:
        - containerPort: 80
      - name: busybox
        image: aliyundoc.com/test/busybox:1.30
        command: ["sleep"]
        args: ["999999"]

Replace 100.100.XX.XX with the actual IP addresses of your image repositories.

Verify the configuration

After the pod is running, check that the custom entries appear in /etc/hosts:

kubectl exec <pod-name> -- cat /etc/hosts

If the custom entries are missing, confirm that the annotation was present when the pod was first created, not added afterward.