Configure a custom DNS server for a pod - Elastic Container Instance

In hybrid cloud environments, the cluster DNS server often cannot resolve on-premises internal domain names — which means pods may fail to pull images from a private image repository or reach internal services. To fix this, add the k8s.aliyun.com/eci-custom-dnsconfig annotation to your pod spec. Elastic Container Instance (ECI) uses the annotation to route DNS queries through your internal DNS server.

Configure a custom DNS server

Prerequisites

Before you begin, ensure that you have:

A running Kubernetes cluster with a virtual node (ECI enabled)
The IP address of your internal DNS server

Add the annotation to your pod spec

Add the k8s.aliyun.com/eci-custom-dnsconfig annotation to metadata.annotations in your pod or Deployment manifest. The annotation value is a JSON string with the following fields:

Field	Description
`nameservers`	IP addresses of the DNS servers. At most 2 IP addresses are supported — extra addresses are automatically ignored. Alibaba Cloud DNS is automatically appended to the end to ensure that the system works as expected.
`searches`	Search domains. At most 32 search domains are allowed. When a query uses an incomplete domain name, the system appends each search domain suffix in turn and retries the lookup.
`options`	DNS resolution options as key-value pairs. Common options: `ndots`, `edns0`, `timeout`, `attempts`.

The options field supports the following keys:

ndots: the minimum number of dots a name must contain to be treated as an absolute domain name. Names with fewer dots are first tried against each search domain.
edns0: enables the Extension Mechanisms for DNS (EDNS0) extension for larger UDP packets and enhanced security.
timeout: the timeout period for each DNS query.
attempts: the number of times to retry a failed DNS query.

The annotation value format is:

{"nameservers":"<dns-server-ip-1>,<dns-server-ip-2>","searches":"<domain-1>,<domain-2>","options":"ndots:<n>,edns0"}

The following example Deployment configures two custom nameservers, two search domains, and sets ndots and edns0:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
      annotations:
        k8s.aliyun.com/eci-custom-dnsconfig: "{\"nameservers\":\"20.1.xx.xx,20.1.xx.xx\",\"searches\":\"xx.com,xx.eee\",\"options\":\"ndots:2,edns0\"}"
    spec:
      dnsPolicy: Default
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80

Set dnsPolicy

Set dnsPolicy to Default when using a custom DNS server. With Default, the pod inherits the DNS configuration of the node it runs on. This preserves the node's routing path to your internal DNS server while keeping public domain resolution intact.

What's next

DNS overview