Container Service for Kubernetes:Configure NodeLocal DNSCache

Limits

• NodeLocal DNSCache does not support pods that run in ACK Serverless clusters or on elastic container instances in ACK managed clusters or ACK dedicated clusters.

• If your cluster uses the Terway network plug-in, the Terway version must be 1.0.10.301 or later. If your cluster runs Terway in inclusive ENI mode based on IPvlan, you must modify the configurations of Terway. For more information, see Modify the configurations of Terway.

• To install NodeLocal DNSCache, you can install ACK NodeLocal DNSCache on the Add-ons page or install ack-node-local-dns on the App Catalog tab of the ACK console.

• NodeLocal DNSCache serves as a transparent caching proxy for CoreDNS and does not provide plug-ins such as hosts or rewrite. If you want to enable these plug-ins, modify the CoreDNS configurations.

• If you do not modify the configurations of CoreDNS before you use NodeLocal DNSCache, CoreDNS may fail to resolve external domain names. For more information, see Configure the default protocol for the Forward plug-in and upstream DNS servers of VPC.

Introduction

For more information about the caching policies supported by NodeLocal DNSCache, see DNS resolution policies and caching policies.

Figure 1. How NodeLocal DNSCache works

Install NodeLocal DNSCache

You can install NodeLocal DNSCache on the Add-ons page or the App Catalog tab of the ACK console. We recommend that you install NodeLocal DNSCache on the Add-ons page.

Method 1: Install NodeLocal DNSCache from the Add-ons page

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, find the cluster that you want to manage and choose More > Operations > Manage Components in the Actions column.

3. On the Add-ons page, click the Networking tab and find ACK NodeLocal DNSCache.

4. Click Install. In the message that appears, click OK.

Method 2: Install NodeLocal DNSCache from the App Catalog tab

1. Log on to the ACK console. In the left-side navigation pane, choose Marketplace > Marketplace.

2. On the Marketplace page, click the App Catalog tab. Then, find and click ack-node-local-dns.

3. On the ack-node-local-dns page, click Deploy.

4. In the Deploy wizard, select a cluster and a namespace, and then click Next.

5. On the Parameters wizard page, configure the parameters and click OK.

   The following table describes the parameters.

   Parameter	Description	How to obtain the value
   upstream_ip	The cluster IP address of the kube-dns Service in the kube-system namespace. NodeLocal DNSCache uses the kube-dns Service to communicate with CoreDNS and resolve cluster-local domain names.	You can modify the parameter value to specify other upstream DNS servers.
   clusterDomain	The domain name of the cluster.	Query the --cluster-domain parameter of the kubelet process on a node. The default value of the parameter is cluster.local.

Configure NodeLocal DNSCache for an application

Method 1: Automatically inject DNSConfig

kubectl label namespace default node-local-dns-injection=enabled

dnsConfig:
  nameservers:
  - 169.254.20.10
  - 172.21.0.10
  options:
  - name: ndots
    value: "3"
  - name: attempts
    value: "2"
  - name: timeout
    value: "1"
  searches:
  - default.svc.cluster.local
  - svc.cluster.local
  - cluster.local
dnsPolicy: None

Automatic DNSConfig injection takes effect only when pods meet all of the following requirements. If no DNS server IP address is injected into the containers in a pod, you need to check whether the pod meets these requirements.

• Newly created pods do not belong to the kube-system or kube-public namespace.

• The namespace to which newly created pods belong has the node-local-dns-injection=enabled label.

• The namespace to which newly created pods belong does not have labels related to Elastic Container Instance, such as virtual-node-affinity-injection, eci, and alibabacloud.com/eci.

• Newly created pods do not have labels related to Elastic Container Instance, such as eci and alibabacloud.com/eci, or the node-local-dns-injection=disabled label.

• Newly created pods use the hostNetwork network and the ClusterFirstWithHostNet DNS policy, or the pods do not use the hostNetwork network but use the ClusterFirst DNS policy.

Method 2: Manually specify DNSConfig

apiVersion: v1
kind: Pod
metadata:
  name: alpine
  namespace: default
spec:
  containers:
  - image: alpine
    command:
      - sleep
      - "10000"
    imagePullPolicy: Always
    name: alpine
  dnsPolicy: None
  dnsConfig:
    nameservers: ["169.254.20.10","172.21.0.10"]
    searches:
    - default.svc.cluster.local
    - svc.cluster.local
    - cluster.local
    options:
    - name: ndots
      value: "3"
    - name: attempts
      value: "2"
    - name: timeout 
      value: "1"

Method 3: Configure kubelet startup parameters

--cluster-dns=169.254.20.10 --cluster-dns=<kube-dns ip> --cluster-domain=<search domain>

Example on how to configure NodeLocal DNSCache for an application

The following example shows how to configure NodeLocal DNSCache for a Deployment that is created in the default namespace.

1. Run the following command to add a label to the namespace to which the Deployment belongs. In this example, the Deployment is created in the default namespace.

   kubectl label namespace default node-local-dns-injection=enabled

   Important

   The admission controller ignores applications in the kube-system and kube-public namespaces. Do not configure to automatically inject dnsConfig to applications in the two namespaces.

2. Deploy a sample application in the default namespace.

   1. Use the following YAML template to create a sample application named ubuntu-deployment:

      apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
      kind: Deployment
      metadata:
        name: ubuntu
        labels:
          app: ubuntu
      spec:
        replicas: 2
        selector:
          matchLabels:
            app: ubuntu
        template:
          metadata:
            labels:
              app: ubuntu
          spec:
            containers:
            - name: ubuntu
              image: ubuntu
              command: ["sh", "-c"]
              args: ["sleep 100000"]

   2. Run the following command to deploy the application in the cluster:

      kubectl apply -f ubuntu-deployment.yaml

      Expected output:

      deployment.apps/ubuntu created

   3. Run the following command to view information about the application:

      kubectl get deployment ubuntu

      Expected output:

      NAME     READY   UP-TO-DATE   AVAILABLE   AGE
      ubuntu   2/2     2            2           7s

3. Check whether dnsConfig is injected.

   1. Run the following command to query the pods that run the application:

      kubectl get pods

      Expected output:

      NAME                      READY   STATUS    RESTARTS   AGE
      ubuntu-766448f68c-m****   1/1     Running   0          4m39s
      ubuntu-766448f68c-w****   1/1     Running   0          4m39s

   2. Run the following command to check whether NodeLocal DNSCache is enabled in dnsConfig of a pod:

      kubectl get pod ubuntu-766448f68c-m**** -o=jsonpath='{.spec.dnsConfig}'

      Expected output:

      map[nameservers:[169.254.20.10 172.21.0.10] options:[map[name:ndots value:5]] searches:[default.svc.cluster.local svc.cluster.local cluster.local]]

      The preceding output indicates that NodeLocal DNSCache is enabled for the application.

      After NodeLocal DNSCache is enabled for an application, the following parameters are added to the pods that are provisioned for the application. To ensure the high availability of DNS services, the cluster IP address 172.21.0.10 of the kube-dns Service is specified as the IP address of the backup DNS server in the nameservers parameter.

        dnsConfig:
          nameservers:
          - 169.254.20.10
          - 172.21.0.10
          options:
          - name: ndots
            value: "3"
          - name: attempts
            value: "2"
          - name: timeout
            value: "1"
          searches:
          - default.svc.cluster.local
          - svc.cluster.local
          - cluster.local
        dnsPolicy: None

Update NodeLocal DNSCache

If you installed NodeLocal DNSCache on the Add-ons page, you must update NodeLocal DNSCache on the Add-ons page. If you installed NodeLocal DNSCache on the App Catalog page, you must uninstall the current version of NodeLocal DNSCache on the Helm page and then install the latest version.

Update NodeLocal DNSCache on the Add-ons page

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, click the name of the cluster that you want to manage and choose Operations > Add-ons in the left-side navigation pane.

3. On the Add-ons page, find NodeLocal DNSCache and click Upgrade. In the message that appears, click OK.

   Note

   • If you modified tolerations for the node-local-dns DaemonSet, the modifications are overwritten during the update process. You must configure the tolerations again after the update is complete.

   • If the system fails to update NodeLocal DNSCache, troubleshoot the failure based on the error code that is returned. For more information, see Component troubleshooting.

Update NodeLocal DNSCache on the App Catalog page

If you installed NodeLocal DNSCache on the App Catalog page, you must uninstall the current version of NodeLocal DNSCache and then install the latest version. For more information, see Uninstall NodeLocal DNSCache and Install NodeLocal DNSCache.

Uninstall NodeLocal DNSCache

If you installed NodeLocal DNSCache on the Add-ons page, you must uninstall NodeLocal DNSCache on the Add-ons page. If you installed NodeLocal DNSCache on the App Catalog page, you must uninstall NodeLocal DNSCache on the Helm page.

Uninstall NodeLocal DNSCache on the Add-ons page

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, click the name of the cluster that you want to manage and choose Operations > Add-ons in the left-side navigation pane.

3. On the Add-ons page, find NodeLocal DNSCache and click Uninstall. In the message that appears, click OK.

   Note

   After NodeLocal DNSCache is uninstalled, all DNS queries are sent to CoreDNS. We recommend that you scale out CoreDNS before you uninstall NodeLocal DNSCache.

Uninstall NodeLocal DNSCache on the App Catalog page

1. Check the parameter settings.

   1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

   2. On the Clusters page, click the name of the cluster that you want to manage and choose Applications > Helm in the left-side navigation pane.

   3. On the Helm page, find and click ack-node-local-dns-default.

   4. On the Parameters tab, check the parameters.

      • If the local_dns_ip parameter is set to the cluster IP address of kube-dns, proceed to Step 2 to uninstall NodeLocal DNSCache.

      • If the high_availability parameter is set to enabled and the local_dns_ip parameter is set to 169.254.20.10, proceed to Step 2 to uninstall NodeLocal DNSCache.

      • If the preceding conditions are not met, perform the following steps to uninstall NodeLocal DNSCache:

        1. Run the kubectl get ns -o yaml command to find the namespaces that have the node-local-dns-injection=enabled label. Remove the label from the namespaces.

        2. Run the kubectl get pod -o yaml command to find the pods to which DNSConfig is injected. Delete the pods and recreate them.

        3. Perform Step 2 to uninstall NodeLocal DNSCache.

2. Uninstall NodeLocal DNSCache.

   1. In the left-side navigation pane of the ACK console, click Clusters.

   2. On the Clusters page, click the name of the cluster that you want to manage and choose Applications > Helm in the left-side navigation pane.

   3. On the Helm page, select ack-node-local-dns-default and click Delete in the Actions column. In the dialog box that appears, select Clear Release Records and click OK.

Modify the configurations of Terway

1. Run the following command to view the ConfigMap of Terway:

   kubectl -n kube-system edit cm eni-config -o yaml

2. Check the ConfigMap of Terway.

   • Check whether IPvlan is enabled in the eniip_virtual_type field. If this field does not exist in the ConfigMap or the value is not set to IPvlan, you do not need to perform the following steps before you install NodeLocal DNSCache. For more information, see Install NodeLocal DNSCache.

   • Check whether the host_stack_cidrs field is specified in the ConfigMap. If the host_stack_cidrs field is specified, you do not need to perform the following steps before you install NodeLocal DNSCache. For more information, see Install NodeLocal DNSCache.

3. Add the host_stack_cidrs field to the ConfigMap of Terway and set the value to 169.254.20.10/32. Then, save the ConfigMap and exit.

    10-terway.conf: |
     {
       "cniVersion": "0.3.0",
       "name": "terway",
       "eniip_virtual_type": "IPVlan",
       "host_stack_cidrs": ["169.254.20.10/32"], 
       "type": "terway"
     }

4. Run the following command to query all of the DaemonSet pods provisioned for Terway:

   kubectl -n kube-system get pod | grep terway-eniip

   Expected output:

   terway-eniip-7****         2/2     Running   0          30m
   terway-eniip-s****         2/2     Running   0          30m

5. Run the following command to recreate the Terway pods:

    kubectl -n kube-system delete pod terway-eniip-7**** terway-eniip-s****

6. Log on to a node of the cluster and run the following command to query the ConfigMap of Terway.

   If the ConfigMap contains the CIDR block that you added, the ConfigMap of Terway is modified.

   cat /etc/cni/net.d/*

   Expected output:

    {
      "cniVersion": "0.3.0",
      "name": "terway-chainer",
      "plugins": [
        {
          "eniip_virtual_type": "IPVlan",
          "host_stack_cidrs": [ 
            "169.254.20.10/32",
          ],
          "type": "terway"
        },
        {
          "type": "cilium-cni"
        }
      ]
    }

   After all the Terway pods are recreated and run as normal, you can install NodeLocal DNSCache.