DNS Operator in OKD

The DNS Operator deploys and manages CoreDNS to provide a name resolution service to pods, enabling DNS-based Kubernetes Service discovery in OKD.

DNS Operator

The DNS Operator implements the dns API from the operator.openshift.io API group. The Operator deploys CoreDNS using a daemon set, creates a service for the daemon set, and configures the kubelet to instruct pods to use the CoreDNS service IP address for name resolution.

Procedure

The DNS Operator is deployed during installation with a Deployment object.

  1. Use the oc get command to view the deployment status:

    1. $ oc get -n openshift-dns-operator deployment/dns-operator

    Example output

    1. NAME           READY     UP-TO-DATE   AVAILABLE   AGE
    2. dns-operator   1/1       1            1           23h

  2. Use the oc get command to view the state of the DNS Operator:

    1. $ oc get clusteroperator/dns

    Example output

    1. NAME      VERSION     AVAILABLE   PROGRESSING   DEGRADED   SINCE
    2. dns       4.1.0-0.11  True        False         False      92m

    AVAILABLE, PROGRESSING and DEGRADED provide information about the status of the operator. AVAILABLE is True when at least 1 pod from the CoreDNS daemon set reports an Available status condition.

Changing the DNS Operator managementState

DNS manages the CoreDNS component to provide a name resolution service for pods and services in the cluster. The managementState of the DNS Operator is set to Managed by default, which means that the DNS Operator is actively managing its resources. You can change it to Unmanaged, which means the DNS Operator is not managing its resources.

The following are use cases for changing the DNS Operator managementState:

  • You are a developer and want to test a configuration change to see if it fixes an issue in CoreDNS. You can stop the DNS Operator from overwriting the fix by setting the managementState to Unmanaged.

  • You are a cluster administrator and have reported an issue with CoreDNS, but need to apply a workaround until the issue is fixed. You can set the managementState field of the DNS Operator to Unmanaged to apply the workaround.

Procedure

  • Change managementState DNS Operator:

    1. oc patch dns.operator.openshift.io default --type merge --patch '{"spec":{"managementState":"Unmanaged"}}'

Controlling DNS pod placement

The DNS Operator has two daemon sets: one for CoreDNS and one for managing the /etc/hosts file. The daemon set for /etc/hosts must run on every node host to add an entry for the cluster image registry to support pulling images. Security policies can prohibit communication between pairs of nodes, which prevents the daemon set for CoreDNS from running on every node.

As a cluster administrator, you can use a custom node selector to configure the daemon set for CoreDNS to run or not run on certain nodes.

Prerequisites

  • You installed the oc CLI.

  • You are logged in to the cluster with a user with cluster-admin privileges.

Procedure

  • To prevent communication between certain nodes, configure the spec.nodePlacement.nodeSelector API field:

    1. Modify the DNS Operator object named default:

      1. $ oc edit dns.operator/default

    2. Specify a node selector that includes only control plane nodes in the spec.nodePlacement.nodeSelector API field:

      1.  spec:
      2.    nodePlacement:
      3.      nodeSelector:
      4.        node-role.kubernetes.io/worker: ""

  • To allow the daemon set for CoreDNS to run on nodes, configure a taint and toleration:

    1. Modify the DNS Operator object named default:

      1. $ oc edit dns.operator/default

    2. Specify a taint key and a toleration for the taint:

      1.  spec:
      2.    nodePlacement:
      3.      tolerations:
      4.      - effect: NoExecute
      5.        key: "dns-only"
      6.        operators: Equal
      7.        value: abc
      8.        tolerationSeconds: 3600 (1)
      1If the taint is dns-only, it can be tolerated indefinitely. You can omit tolerationSeconds.

View the default DNS

Every new OKD installation has a dns.operator named default.

Procedure

  1. Use the oc describe command to view the default dns:

    1. $ oc describe dns.operator/default

    Example output

    1. Name:         default
    2. Namespace:
    3. Labels:       <none>
    4. Annotations:  <none>
    5. API Version:  operator.openshift.io/v1
    6. Kind:         DNS
    7. ...
    8. Status:
    9.   Cluster Domain:  cluster.local (1)
    10.   Cluster IP:      172.30.0.10 (2)
    11. ...
    1The Cluster Domain field is the base DNS domain used to construct fully qualified pod and service domain names.
    2The Cluster IP is the address pods query for name resolution. The IP is defined as the 10th address in the service CIDR range.

  2. To find the service CIDR of your cluster, use the oc get command:

    1. $ oc get networks.config/cluster -o jsonpath='{$.status.serviceNetwork}'

Example output

  1. [172.30.0.0/16]

Using DNS forwarding

You can use DNS forwarding to override the default forwarding configuration in the /etc/resolv.conf file in the following ways:

  • Specify name servers for every zone. If the forwarded zone is the Ingress domain managed by OKD, then the upstream name server must be authorized for the domain.

  • Provide a list of upstream DNS servers.

  • Change the default forwarding policy.

A DNS forwarding configuration for the default domain can have both the default servers specified in the /etc/resolv.conf file and the upstream DNS servers.

Procedure

  1. Modify the DNS Operator object named default:

    1. $ oc edit dns.operator/default

    This allows the Operator to create and update the config map named dns-default with additional server configuration blocks based on Server. If none of the servers have a zone that matches the query, then name resolution falls back to the upstream DNS servers.

    Configuring DNS forwarding

    1. apiVersion: operator.openshift.io/v1
    2. kind: DNS
    3. metadata:
    4.   name: default
    5. spec:
    6.   servers:
    7.   - name: example-server (1)
    8.     zones: (2)
    9.     - example.com
    10.     forwardPlugin:
    11.       policy: Random (3)
    12.       upstreams: (4)
    13.       - 1.1.1.1
    14.       - 2.2.2.2:5353
    15.   upstreamResolvers: (5)
    16.     policy: Random (6)
    17.     upstreams: (7)
    18.     - type: SystemResolvConf (8)
    19.     - type: Network
    20.       address: 1.2.3.4 (9)
    21.       port: 53 (10)
    1Must comply with the rfc6335 service name syntax.
    2Must conform to the definition of a subdomain in the rfc1123 service name syntax. The cluster domain, cluster.local, is an invalid subdomain for the zones field.
    3Defines the policy to select upstream resolvers. Default value is Random. You can also use the values RoundRobin, and Sequential.
    4A maximum of 15 upstreams is allowed per forwardPlugin.
    5Optional. You can use it to override the default policy and forward DNS resolution to the specified DNS resolvers (upstream resolvers) for the default domain. If you do not provide any upstream resolvers, the DNS name queries go to the servers in /etc/resolv.conf.
    6Determines the order in which upstream servers are selected for querying. You can specify one of these values: Random, RoundRobin, or Sequential. The default value is Sequential.
    7Optional. You can use it to provide upstream resolvers.
    8You can specify two types of upstreams - SystemResolvConf and Network. SystemResolvConf configures the upstream to use /etc/resolv.conf and Network defines a Networkresolver. You can specify one or both.
    9If the specified type is Network, you must provide an IP address. The address field must be a valid IPv4 or IPv6 address.
    10If the specified type is Network, you can optionally provide a port. The port field must have a value between 1 and 65535. If you do not specify a port for the upstream, by default port 853 is tried.

    When working in a highly regulated environment, you might need the ability to secure DNS traffic when forwarding requests to upstream resolvers so that you can ensure additional DNS traffic and data privacy. Cluster administrators can configure transport layer security (TLS) for forwarded DNS queries.

    Configuring DNS forwarding with TLS

    1. apiVersion: operator.openshift.io/v1
    2. kind: DNS
    3. metadata:
    4.   name: default
    5. spec:
    6.   servers:
    7.   - name: example-server (1)
    8.     zones: (2)
    9.     - example.com
    10.     forwardPlugin:
    11.       transportConfig:
    12.         transport: TLS (3)
    13.         tls:
    14.           caBundle:
    15.             name: mycacert
    16.           serverName: dnstls.example.com  (4)
    17.       policy: Random (5)
    18.       upstreams: (6)
    19.       - 1.1.1.1
    20.       - 2.2.2.2:5353
    21.   upstreamResolvers: (7)
    22.     transportConfig:
    23.       transport: TLS
    24.       tls:
    25.         caBundle:
    26.           name: mycacert
    27.         serverName: dnstls.example.com
    28.     upstreams:
    29.     - type: Network (8)
    30.       address: 1.2.3.4 (9)
    31.       port: 53 (10)
    1Must comply with the rfc6335 service name syntax.
    2Must conform to the definition of a subdomain in the rfc1123 service name syntax. The cluster domain, cluster.local, is an invalid subdomain for the zones field. The cluster domain, cluster.local, is an invalid subdomain for zones.
    3When configuring TLS for forwarded DNS queries, set the transport field to have the value TLS. By default, CoreDNS caches forwarded connections for 10 seconds. CoreDNS will hold a TCP connection open for those 10 seconds if no request is issued. With large clusters, ensure that your DNS server is aware that it might get many new connections to hold open because you can initiate a connection per node. Set up your DNS hierarchy accordingly to avoid performance issues.
    4When configuring TLS for forwarded DNS queries, this is a mandatory server name used as part of the server name indication (SNI) to validate the upstream TLS server certificate.
    5Defines the policy to select upstream resolvers. Default value is Random. You can also use the values RoundRobin, and Sequential.
    6Required. You can use it to provide upstream resolvers. A maximum of 15 upstreams entries are allowed per forwardPlugin entry.
    7Optional. You can use it to override the default policy and forward DNS resolution to the specified DNS resolvers (upstream resolvers) for the default domain. If you do not provide any upstream resolvers, the DNS name queries go to the servers in /etc/resolv.conf.
    8Network type indicates that this upstream resolver should handle forwarded requests separately from the upstream resolvers listed in /etc/resolv.conf. Only the Network type is allowed when using TLS and you must provide an IP address.
    9The address field must be a valid IPv4 or IPv6 address.
    10You can optionally provide a port. The port must have a value between 1 and 65535. If you do not specify a port for the upstream, by default port 853 is tried.

    If servers is undefined or invalid, the config map only contains the default server.

  2. View the config map:

    1. $ oc get configmap/dns-default -n openshift-dns -o yaml

    Sample DNS ConfigMap based on previous sample DNS

    1. apiVersion: v1
    2. data:
    3.   Corefile: |
    4.     example.com:5353 {
    5.         forward . 1.1.1.1 2.2.2.2:5353
    6.     }
    7.     bar.com:5353 example.com:5353 {
    8.         forward . 3.3.3.3 4.4.4.4:5454 (1)
    9.     }
    10.     .:5353 {
    11.         errors
    12.         health
    13.         kubernetes cluster.local in-addr.arpa ip6.arpa {
    14.             pods insecure
    15.             upstream
    16.             fallthrough in-addr.arpa ip6.arpa
    17.         }
    18.         prometheus :9153
    19.         forward . /etc/resolv.conf 1.2.3.4:53 {
    20.             policy Random
    21.         }
    22.         cache 30
    23.         reload
    24.     }
    25. kind: ConfigMap
    26. metadata:
    27.   labels:
    28.     dns.operator.openshift.io/owning-dns: default
    29.   name: dns-default
    30.   namespace: openshift-dns
    1Changes to the forwardPlugin triggers a rolling update of the CoreDNS daemon set.

Additional resources

DNS Operator status

You can inspect the status and view the details of the DNS Operator using the oc describe command.

Procedure

View the status of the DNS Operator:

  1. $ oc describe clusteroperators/dns

DNS Operator logs

You can view DNS Operator logs by using the oc logs command.

Procedure

View the logs of the DNS Operator:

  1. $ oc logs -n openshift-dns-operator deployment/dns-operator -c dns-operator

Setting the CoreDNS log level

You can configure the CoreDNS log level to determine the amount of detail in logged error messages. The valid values for CoreDNS log level are Normal, Debug, and Trace. The default logLevel is Normal.

The errors plugin is always enabled. The following logLevel settings report different error responses:

  • logLevel: Normal enables the “errors” class: log . { class error }.

  • logLevel: Debug enables the “denial” class: log . { class denial error }.

  • logLevel: Trace enables the “all” class: log . { class all }.

Procedure

  • To set logLevel to Debug, enter the following command:

    1. $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"logLevel":"Debug"}}' --type=merge

  • To set logLevel to Trace, enter the following command:

    1. $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"logLevel":"Trace"}}' --type=merge

Verification

  • To ensure the desired log level was set, check the config map:

    1. $ oc get configmap/dns-default -n openshift-dns -o yaml

Setting the CoreDNS Operator log level

Cluster administrators can configure the Operator log level to more quickly track down OpenShift DNS issues. The valid values for operatorLogLevel are Normal, Debug, and Trace. Trace has the most detailed information. The default operatorlogLevel is Normal. There are seven logging levels for issues: Trace, Debug, Info, Warning, Error, Fatal and Panic. After the logging level is set, log entries with that severity or anything above it will be logged.

  • operatorLogLevel: "Normal" sets logrus.SetLogLevel("Info").

  • operatorLogLevel: "Debug" sets logrus.SetLogLevel("Debug").

  • operatorLogLevel: "Trace" sets logrus.SetLogLevel("Trace").

Procedure

  • To set operatorLogLevel to Debug, enter the following command:

    1. $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"operatorLogLevel":"Debug"}}' --type=merge

  • To set operatorLogLevel to Trace, enter the following command:

    1. $ oc patch dnses.operator.openshift.io/default -p '{"spec":{"operatorLogLevel":"Trace"}}' --type=merge

Tuning the CoreDNS cache

You can configure the maximum duration of both successful or unsuccessful caching, also known as positive or negative caching respectively, done by CoreDNS. Tuning the duration of caching of DNS query responses can reduce the load for any upstream DNS resolvers.

Procedure

  1. Edit the DNS Operator object named default by running the following command:

    1. $ oc edit dns.operator.openshift.io/default

  2. Modify the time-to-live (TTL) caching values:

    Configuring DNS caching

    1. apiVersion: operator.openshift.io/v1
    2. kind: DNS
    3. metadata:
    4.   name: default
    5. spec:
    6.   cache:
    7.     successTTL: 1h (1)
    8.     denialTTL: 0.5h10m (2)
    1The string value 1h is converted to its respective number of seconds by CoreDNS. If this field is omitted, the value is assumed to be 0s and the cluster uses the internal default value of 900s as a fallback.
    2The string value can be a combination of units such as 0.5h10m and is converted to its respective number of seconds by CoreDNS. If this field is omitted, the value is assumed to be 0s and the cluster uses the internal default value of 30s as a fallback.

    Setting TTL fields to low values could lead to an increased load on the cluster, any upstream resolvers, or both.