Container Service for Kubernetes:DNS troubleshooting

Table of contents

Diagnostic procedure

• Internal domain name: CoreDNS exposes services deployed in a cluster through an internal domain name that ends with .cluster.local. DNS queries for the internal domain name are resolved based on the DNS cache of CoreDNS instead of the upstream DNS servers.
• External domain name: Domain names other than the internal domain name of a cluster. DNS queries for external domain names can be resolved by CoreDNS or by the upstream DNS servers that are specified in DNSConfig. By default, 100.100.2.136 and 100.100.2.138 are specified as the upstream DNS servers. The default upstream DNS servers are deployed in a virtual private cloud (VPC). You can also specify self-managed DNS servers.
• Application pod: Pods other than the pods of system components in a Kubernetes cluster.
• Application pods that use CoreDNS for DNS resolutions: Application pods that use CoreDNS to process DNS queries.
• Application pods that use NodeLocal DNSCache for DNS resolutions: After you install NodeLocal DNSCache in your cluster, you can configure DNS settings by injecting DNSConfig to application pods. This way, DNS queries of these pods are first sent to NodeLocal DNSCache. If NodeLocal DNSCache fails to process the queries, the queries are sent to the kube-dns Service of CoreDNS.

1. Check the domain name and DNS server. For more information, see Common error messages.
   • If the error message indicates that the domain name does not exist, refer to Check the domain name in the Troubleshooting section.
   • If the error message indicates that connections to the DNS server cannot be established, refer to Check the frequency of errors in the Troubleshooting section.
2. If the error still exists, perform the following checks:
   • Check whether CoreDNS is specified in the DNS configuration of the application pod. For more information, see Diagnose the DNS configurations of application pods.
     • If CoreDNS is not specified in the DNS configuration, a possible cause is that the client runs at full load or the conntrack table is full. For more information, see What do I do if DNS resolutions fail because the client is overloaded? and What do I do if the conntrack table is full?.
     • If CoreDNS is specified in the DNS configuration, perform the following checks:
       1. Check the status of the CoreDNS pods. For more information, see Diagnose the status of the CoreDNS pod and What do I do if CoreDNS pods do not run as normal?.
       2. Check the operational logs of the CoreDNS pods. For more information, see Diagnose the operational log of CoreDNS and What do I do if the external domain name of my cluster cannot be resolved?.
       3. Check whether the error can be stably reproduced.
          1. If the error can be stably reproduced, refer to Diagnose the DNS query log of CoreDNS, Diagnose the container network, and Diagnose the network connectivity between application pods and the CoreDNS pod.
          2. If the error cannot be stably reproduced, refer to Capture packets.
   • If NodeLocal DNSCache is specified in the DNS configuration, refer to What do I do if NodeLocal DNSCache doe not work? and What do I do if domain names that are added to Alibaba Cloud DNS PrivateZone cannot be resolved?.
3. If the error still exists, Submit a ticket for troubleshooting.

Troubleshooting

Commonly used diagnostic methods

• Commands

  # Run the following command to query the YAML file of the foo pod. Then, check whether the dnsPolicy field in the YAML file is set to a proper value. 
  kubectl get pod foo -o yaml
  
  # If the dnsPolicy field is set to a proper value, check the DNS configuration file of the pod. 
  
  # Run the following command to log on to the containers of the foo pod by using bash. If bash does not exist, use sh. 
  kubectl exec -it foo bash
  
  # Run the following command to query the DNS configuration file. Then, check the DNS server addresses in the nameserver field. 
  cat /etc/resolv.conf

• DNS policy settings

  The following sample code provides a pod template that is configured with DNS policy settings:

  apiVersion: v1
  kind: Pod
  metadata:
    name: <pod-name>
    namespace: <pod-namespace>
  spec:
    containers:
    - image: <container-image>
      name: <container-name>
  
  # The default value of dnsPolicy is ClusterFirst. 
    dnsPolicy: ClusterFirst
  # The following code shows the DNS policy settings that are applied when NodeLocal DNSCache is used. 
    dnsPolicy: None
    dnsConfig:
      nameservers:
      - 169.254.20.10
      - 172.21.0.10
      options:
      - name: ndots
        value: "3"
      - name: timeout
        value: "1"
      - name: attempts
        value: "2"
      searches:
      - default.svc.cluster.local
      - svc.cluster.local
      - cluster.local
  
    securityContext: {}
    serviceAccount: default
    serviceAccountName: default
    terminationGracePeriodSeconds: 30

  Value of dnsPolicy	Description
  Default	You can use this value if internal access from within the cluster is not required. The pod uses DNS servers that are specified in the /etc/resolv.conf file of the Elastic Compute Service (ECS) instance.
  ClusterFirst	This is the default value. The IP address of the kube-dns Service is used as the address of the DNS server that is used by the pod. For pods that use the host network, a value of ClusterFirst has the same effect as the value of Default.
  ClusterFirstWithHostNet	For pods that use the host network, a value of ClusterFirstWithHostNet has the same effect as the value of ClusterFirst.
  None	If you use this value, you can configure self-managed DNS servers and custom parameters in the DNSConfig section. If you enable the automatic injection of DNSConfig for NodeLocal DNSCache, the IP address of the local DNS cache and the IP address of the kube-dns Service are set as the addresses of the DNS servers.

Commands

kubectl -n kube-system logs -f --tail=500 --timestamps coredns-xxxxxxxxx-xxxxx

Commands

The DNS query log of CoreDNS is generated only when the log plug-in of CoreDNS is enabled. For more information about how to enable the log plug-in, see Configure DNS resolution.

Run the command that you use to query the operational log of CoreDNS. For more information, see Diagnose the operational log of CoreDNS.

Procedure

1. Log on to the node on which the CoreDNS pod runs.
2. Run the ps aux | grep coredns command to query the ID of the CoreDNS process.
3. Run the nsenter -t <pid> -n bash command to enter the network namespace to which CoreDNS belongs. Replace pid with the process ID that you obtained in the previous step.
4. Test the network connectivity.
   1. Run the telnet <apiserver_slb_ip> 443 command to test the connectivity to the Kubernetes API server of the cluster.

      Replace apiserver_slb_ip with the IP address of the Service that is used to expose the Kubernetes API server of the cluster.

   2. Run the dig <domain> @<upstream_dns_server_ip> command to test the connectivity between the CoreDNS pod and the upstream DNS servers.

      Replace domain with the test domain name and upstream_dns_server_ip with the IP addresses of the upstream DNS servers, which are 100.100.2.136 and 100.100.2.138 by default.

FAQ

Procedure

1. Use one of the following methods to connect to the container network of the application pods.
   • Method 1: Run the kubectl exec command.
   • Method 2:
     1. Log on to the node on which the application pods run.
     2. Run the ps aux | grep <application process name> command to query the ID of the application process.
     3. Run the nsenter -t <pid> -n bash command to enter the network namespace to which the application pods belong.

        Replace pid with the process ID that you obtained in the previous step.

   • Method 3: If the application pods frequently restart, perform the following steps:
     1. Log on to the node on which the application pods run.
     2. Run the docker ps -a | grep <application container names> command to query the containers whose names start with k8s_POD_ . Record the sandboxed container IDs that are returned.
     3. Run the docker inspect <sandboxed container ID> | grep netns command to query the path of the network namespace to which the container belongs in the /var/run/docker/netns/xxxx file.
     4. Run the nsenter -n<netns path> -n bash command to enter the network namespace.

        Replace netns path with the path that you obtained in the previous step.

        Note Do not add spaces between -n and <netns path>.
2. Test the network connectivity.
   1. Run the dig <domain> @<kube_dns_svc_ip> command to test the connectivity between the application pods and the kube-dns Service.

      Replace <domain> with the test domain name and <kube_dns_svc_ip> with the IP address of the kube-dns Service in the kube-system namespace.

   2. Run the ping <coredns_pod_ip> command to test the connectivity between the application pods and the CoreDNS pod.

      Replace <coredns_pod_ip> with the IP address of the CoreDNS pod in the kube-system namespace.

   3. Run the dig <domain> @<coredns_pod_ip> command to test the connectivity between the application pods and the CoreDNS pod.

      Replace <domain> with the test domain name and <coredns_pod_ip> with the IP address of the CoreDNS pod in the kube-system namespace.

FAQ

1. Log on to the ACK console.
2. On the Clusters page, find the cluster that you want to manage and click the name of the cluster or click Details in the Actions column. The details page of the cluster appears.
3. In the left-side navigation pane of the ACK console, click Clusters.
4. In the left-side navigation pane of the details page, choose Operations > Cluster Check.
5. In the left-side navigation pane of the Container Intelligence Service page, choose Cluster Check > Diagnosis.
6. On the Diagnosis page, click the Network Diagnosis tab.
7. Set Source address to the IP address of an application pod, Destination address to the IP address of the kube-dns Service, and Destination port to 53. Select Enable packet tracing and I know and agree. Then, click Create diagnosis.
8. In the list of diagnosis records, find the diagnosis record that you want to manage and click Diagnosis details in the operation column.
   You can view the diagnostic results that are displayed in the Diagnosis result, Packet paths, and All possible paths sections. The causes of errors are also provided. For more information, see Use the cluster diagnostics feature to troubleshoot cluster issues.

If you cannot identify the issue, capture and diagnose packets.

1. Log on to the nodes on which the application pods and CoreDNS pod run.
2. Run the following command on each ECS instance to capture all recent packets received on port 53:

   tcpdump -i any port 53 -C 20 -W 200 -w /tmp/client_dns.pcap

3. Diagnose the packets that are transferred during the time period in which DNS resolution errors occurred. You can obtain the time period from the application log.
   Note

   • Packet capture does not affect your service and only causes a slight increase in the CPU utilization and disk I/O.
   • The preceding command rotates the captured packets and can generate at most 200 .pcap files that each has a size of 20 MB.

What do I do if the external domain name of my cluster cannot be resolved?

The upstream DNS server returns an error code, which indicates that a domain name resolution error occurred.

The internal domain name of the cluster can be resolved, but the external domain name cannot be resolved.

Check the DNS query log of CoreDNS.

# If the response code is NOERROR, it indicates that the domain name is resolved without errors. 
[INFO] 172.20.2.25:44525 - 36259 "A IN redis-master.default.svc.cluster.local. udp 56 false 512" NOERROR qr,aa,rd 110 0.000116946s

What do I do if domain names of headless Services cannot be resolved?

In CoreDNS versions earlier than 1.7.0, CoreDNS may unexpectedly exit if network jitters occur on the Kubernetes API server of the cluster. As a result, the domain names of headless Services are not updated when CoreDNS is down.

CoreDNS cannot resolve domain names of headless Services.

Update CoreDNS to 1.7.0 or later. For more information, see [Component Updates] Update CoreDNS.

What do I do if domains names of StatefulSet pods cannot be resolved?

If a StatefulSet is exposed by using a headless Service, the ServiceName parameter in the pod YAML template must be set to the name of the headless Service. Otherwise, you cannot access the domain names of the StatefulSet pods, such as pod.headless-svc.ns.svc.cluster.local. However, you can access the domain name of the headless Service, such as headless-svc.ns.svc.cluster.local.

The domain names of StatefulSet pods cannot be resolved.

Set the ServiceName parameter in the pod YAML template to the name of the headless Service that is used to expose the StatefulSet pods.

What do I do if DNS queries are blocked by security group rules or the network access control lists (ACLs) that are associated with vSwitches?

The security group rules or network ACLs that control the network communications of the ECS instance block UDP port 53.

DNS resolution failures of CoreDNS persist on some or all nodes.

Modify the security group rules or network ACLs to open UDP port 53.

What do I do if container network connectivity errors occur?

UDP port 53 is blocked due to container network connectivity errors or other causes.

DNS resolution failures of CoreDNS persist on some or all nodes.

Diagnose the container network. For more information, see Use the cluster diagnostics feature to troubleshoot cluster issues.

What do I do if CoreDNS pods are overloaded?

The number of replicated pods that are configured for CoreDNS is insufficient to handle DNS queries.

• The DNS resolution latency of CoreDNS is high, or DNS resolution failures of CoreDNS persist or occasionally occur on some or all nodes.
• Check the status of CoreDNS pods and check whether the CPU and memory utilization is about to reach the upper limit.

• Use NodeLocal DNSCache to improve DNS resolution efficiency and reduce the load on CoreDNS. For more information, see Configure NodeLocal DNSCache.
• Scale out CoreDNS pods to ensure that the peak CPU utilization of each pod is less than the amount of idle CPU resources of the node.

What do I do if DNS queries are not evenly distributed among CoreDNS pods?

DNS queries are not evenly distributed among CoreDNS pods due to imbalanced pod scheduling or improper SessionAffinity settings of the kube-dns Service.

• The DNS resolution latency of CoreDNS is high, or DNS resolution failures of CoreDNS persist or occasionally occur on some or all nodes.
• The status of CoreDNS pods shows that the CPU utilization is different among the pods.
• The number of replicated pods that are configured for CoreDNS is less than two or multiple CoreDNS pods are deployed on the same node.

• Scale out CoreDNS pods and schedule the pods to different nodes.
• You can delete the SessionAffinity parameter from the configuration of the kube-dns Service. For more information, see Configure the kube-dns Service.

What do I do if CoreDNS pods do not run as normal?

CoreDNS pods do not run as normal due to improper settings in the YAML file or the CoreDNS ConfigMap.

• The DNS resolution latency of CoreDNS is high, or DNS resolution failures of CoreDNS persist or occasionally occur on some or all nodes.
• CoreDNS pods are not in the Running state or the number of pod restarts continuously increases.
• The CoreDNS log data indicates that errors occurred.

Check the status and operational logs of CoreDNS pods.

What do I do if DNS resolutions fail because the client is overloaded?

The ECS instance that hosts the pod that sends the DNS query to CoreDNS is fully loaded, which causes UDP packet loss.

DNS resolution errors occur occasionally or during peak hours. The monitoring information about the ECS instance indicates an abnormal retransmission rate of the network interface controller (NIC) and an abnormal CPU utilization.

• Submit a ticket for troubleshooting.
• Use NodeLocal DNSCache to improve DNS resolution efficiency and reduce the load on CoreDNS. For more information, see Configure NodeLocal DNSCache.

What do I do if the conntrack table is full?

The conntrack table of the Linux kernel is full. As a result, requests that are sent over UDP or TCP cannot be processed.

• CoreDNS frequently fails to resolve domain names on some or all nodes in peak hours, but can resolve domain names as expected beyond peak hours
• Run the dmesg -H command on the instance and check the log that is generated during the period in which the resolution fails. The log contains the keyword conntrack full.

Increase the maximum number of entries in the conntrack table of the Linux kernel. For more information, see How do I increase the maximum number of tracked connections in the conntrack table of the Linux kernel?.

What do I do if the autopath plug-in does not work as normal?

The autopath plug-in does not work as normal due to the defects of CoreDNS.

• The external domain name occasionally fails to be resolved or is occasionally resolved to a wrong IP address. However, the internal domain name is resolved as normal.
• When the cluster creates containers at a high frequency, the internal domain name is resolved to a wrong IP address.

What do I do if DNS resolutions fail due to concurrent queries for A records and AAAA records?

Concurrent DNS queries for A records and AAAA records cause errors of the conntrack table of the Linux kernel, which results in UDP packet loss.

• DNS resolutions of CoreDNS occasionally fail.
• The captured packets or the log of DNS queries to CoreDNS shows that queries for A records and AAAA records are initiated at the same time over the same port.

• Use NodeLocal DNSCache to improve DNS resolution efficiency and reduce the load on CoreDNS. For more information, see Configure NodeLocal DNSCache.
• If the image that you use is based on CentOS or Ubuntu, add the options timeout:2 attempts:3 rotate single-request-reopen configuration.
• If the image that you use is based on Alpine Linux, we recommend that you replace the image with an image that is based on another operating system. For more information, see Alpine.
• A variety of resolution errors may occur when applications written in PHP send DNS queries by using short-lived connections. If you use PHP cURL, you must add CURL_IPRESOLVE_V4 to specify that domain names can be resolved only to IPv4 addresses. For more information, see cURL functions.

What do I do if DNS resolutions fail due to IP Virtual Server (IPVS) errors?

The load balancing mode of kube-proxy is set to IPVS in your cluster. If you remove IPVS UDP backend pods from nodes that run CentOS or Alibaba Cloud Linux 2 whose kernel versions are earlier than 4.19.91-25.1.al7.x86_64, source port conflicts occur when UDP packets are sent. As a result, the UDP packets are dropped.

DNS resolutions occasionally fail when nodes are added to or removed from the cluster, nodes are shut down, or CoreDNS is scaled in. In most cases, this situation lasts for about 5 minutes.

• Use NodeLocal DNSCache to reduce packet loss in IPVS mode. For more information, see Configure NodeLocal DNSCache.
• Shorten the timeout period of UDP sessions in IPVS mode. For more information, see Change the UDP timeout period in IPVS mode.

What do I do if NodeLocal DNSCache doe not work?

• DNSConfig is not injected into the application pods. The IP address of the kube-dns Service is configured as the address of the DNS server for the application pods.
• The application pods are deployed by using an image based on Alpine Linux. As a result, DNS queries are concurrently sent to all nameservers, including the local DNS cache and CoreDNS pods.

All DNS queries are sent to CoreDNS instead of NodeLocal DNSCache.

• Configure automatic injection for DNSConfig. For more information, see Configure NodeLocal DNSCache.
• If the image that you use is based on Alpine Linux, we recommend that you replace the image with an image that is based on another operating system. For more information, see Alpine.

What do I do if domain names that are added to Alibaba Cloud DNS PrivateZone cannot be resolved?

Alibaba Cloud DNS PrivateZone does not support TCP. You must use UDP.

When NodeLocal DNSCache is used, domain names that are added to Alibaba Cloud DNS PrivateZone cannot be resolved, the endpoints of Alibaba Cloud service APIs that contain vpc-proxy cannot be resolved, or domain names are resolved to wrong IP addresses.

Add the prefer_udp configuration to CoreDNS. For more information, see Configure CoreDNS.