Configure custom parameters for managed CoreDNS - Container Service for Kubernetes

When you deploy a containerized application to a cluster, you must access external services or interfaces in addition to internal services of the cluster. In this case, external domain name resolution is important. You can specify a DNS server for the external domain name to improve the DNS resolution speed. For domain names that are mapped to static IP addresses, you can also add the mappings to the local hosts file. This topic describes how to configure DNS settings for managed CoreDNS by defining a CustomDNSConfig CustomResource (CR) to meet the preceding requirements.

Introduction to custom CoreDNS parameters

The following example describes how to configure custom CoreDNS parameters.

apiVersion: networking.alibabacloud.com/v1beta1
kind: CustomDNSConfig
metadata:
  name: default
  namespace: default
spec:
  zones:
  - name: example.com
    forward:
      protocolStrategy: ""
      transportConfig: {}
      upstreams:
      - xxx.xxx.xxx.xxx     # IP address
      - xxx.xxx.xxx.xxx:53  # IP:port
    hosts:
    - hostName: "a.example.com" 
      ipAddress: xxx.xxx.xxx.xxx

The custom zone. The zone must be a fully qualified domain name (FQDN). Default value: ".".
The default value of the .forward.protocolStrategy parameter is "", which specifies that UDP is used. You can also set this parameter to tcp.
The default value of the .forward.transportConfig parameter is {}. You cannot change the value of this parameter.
You can configure custom upstream DNS server addresses by using the.forward.upstreams parameter in a single zone. This parameter can be in the format of IP or IP: PORT and only supports IPv4.
- If you do not specify the .forward.upstreams parameter, Alibaba Cloud DNS PrivateZone is used.
- You can specify up to 15 upstream DNS server addresses in the .forward.upstreams parameter.
You can configure a custom hosts plug-in in a single zone and map static IP addresses to domain names.
- The hostName parameter is used to define a specific domain name. The format of the domain name must comply with DNS specifications.
- The ipAddress parameter is used to define the IP address mapped to a domain name, which must be a valid IPv4 address.
- You can use the hostName parameter to define multiple IP addresses (ipAddress). Example:
```
...
 hosts:
    - hostName: "a.example.com" 
      ipAddress: 10.0.0.123  
    - hostName: "a.example.com" 
      ipAddress: 10.0.0.124
 ...
```
CustomDNSConfig is not a namespace-wide CustomResourceDefinition (CRD). You can only create a CustomDNSConfig CR named default.

Prerequisites

The managed CoreDNS plug-in is installed. The version of the plug-in is 1.9.3.20 or later. For more information, see Manage components.

A kubectl client is connected to the cluster. For more information, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

Scenario 1: Configure a custom zone

Create a file named default.yaml and copy the following content to the file:

apiVersion: networking.alibabacloud.com/v1beta1
kind: CustomDNSConfig
metadata:
  name: default
spec:
  zones:
  - name: example.com
    forward:
      upstreams:
      - 100.100.2.136  # Set the upstream DNS server addresses for example.com to 100.100.2.136 and 100.100.2.138.
      - 100.100.2.138
  - name: foo.com
    hosts:
    -hostName: "a.foo.com"# Configure custom static IP addresses for a.foo.com and b.foo.com in the foo.com zone.
      ipAddress: 192.168.0.251
    - hostName: "b.foo.com"
      ipAddress: 192.168.0.252

Two custom zones are configured in the YAML file:

example.com
Set the upstream DNS server addresses to 100.100.2.136 and 100.100.2.138.
Note
100.100.2.136 and 100.100.2.138 are the default internal DNS resolution service addresses allocated by the system. For more information, see Endpoints.
foo.com
Configure custom static IP addresses for a.foo.com and b.foo.com.

Run the following command to create a CustomDNSConfig CR:
```
kubectl apply -f default.yaml
```

Run the following command to view the generated corefile:

kubectl get customdnsconfig default -o yaml |grep corefile -A 35 -B 1

Expected output:

 status:
  corefile: |
    example.com:53 {
        prometheus :9153
        forward .  100.100.2.136 100.100.2.138 {
          policy random
          prefer_udp
        }
...
    }
    foo.com:53 {
        prometheus :9153
        hosts {
          192.168.0.251    a.foo.com
          192.168.0.252    b.foo.com
          fallthrough
        }
        forward .  /etc/resolv.conf {
          policy random
          prefer_udp
        }
...
    }
...
--
  corefileHash: 41f7be21cf3022c305091665ed33b1e5
  lastTransitionTime: "2024-09-13T09:07:37Z"
  phase: GenerateSuccess

The output indicates that the CustomDNSConfig CR named default is created and the corresponding corefile can be found in the status parameter.

Scenario 2: Modify the default zone configuration

Create a file named default.yaml and copy the following content to the file:

apiVersion: networking.alibabacloud.com/v1beta1
kind: CustomDNSConfig
metadata:
  name: default
spec:
  zones:
  - name: .
    forward:
      upstreams:
      -100.100.2.136 # The upstream DNS server addresses for the custom default zone named "." are 100.100.2.136 and 100.100.2.138.
      - 100.100.2.138

In the YAML file, the custom upstream DNS server addresses are 100.100.2.136 and 100.100.2.138.

Run the following command to create a CustomDNSConfig CR:
```
kubectl apply -f default.yaml
```

Run the following command to view the generated corefile:

kubectl get customdnsconfig default -o yaml |grep corefile -A 35 -B 1

Expected output:

 status: 
  corefile: |
    .:53 {
        errors
        health {
          lameduck 20s
        }
        ready
        kubeapi {
          kubeconfig /etc/kubernetes/config/managed-coredns.conf
        }
        k8s_event {
          level error warning
        }
...
        prometheus :9153
        forward .  100.100.2.136 100.100.2.138 {
          policy random
          prefer_udp
        }
...
    }
  corefileHash: 847bf69cc4c97cee965945f45d17c661
  lastTransitionTime: "2024-09-13T09:54:22Z"
  phase: GenerateSuccess

The CustomDNSConfig CR named default is created and the corefile is generated.

Note

After you create or modify the CustomDNSConfig CR, CoreDNS needs to perform a configuration reload, which takes about 20 seconds. You can adjust the reload duration for CoreDNS by modifying the value of lamduck in the corefile parameter. The default value is 20 seconds.

Troubleshooting

You can create only a CustomDNSConfig CR named default. This section explains why the status of CustomDNSConfig is NotSupported when you create a CustomDNSConfig CR with a name other than default.

Create a file named gotest.yaml and copy the following content to the file:

apiVersion: networking.alibabacloud.com/v1beta1
kind: CustomDNSConfig
metadata:
  name: test  ## You can create only a CustomDNSConfig CR named default.
spec:
  zones:
  - name: example.com
    forward:
      upstreams:
      - 100.100.2.138
  - name: foo.com
    hosts:
    - hostName: "ah.foo.com"
      ipAddress: 1.1.xx.251
    - hostName: "aha.foo.com"
      ipAddress: 1.1.xx.252

Run the following command to create a CustomDNSConfig CR:
```
kubectl apply -f test.yaml
```

Run the following command to view the generated corefile:

kubectl get customdnsconfig

Expected output:

NAME      PHASE             VERSION                            AGE
default   GenerateSuccess   847bf69cc4c97cee96xxxxxxxxxxx      89m
test      NotSupported                                         9s

The output indicates that the CustomDNSConfig CR named test cannot be created and NotSupported is displayed.

Event information

The custom CoreDNS controller synchronizes event information to the default namespace.

Run the following command to view the events:

kubectl get events

Expected output:

LAST SEEN   TYPE     REASON                  OBJECT                           MESSAGE
45m         Normal   CustomDNSConfigSyncOk   customdnsconfig/default          custom dns config sync to coredns configmap success