Chapter 8. Configure on-premises DNS with CoreDNS (Technology Preview)

Procedure

1. Set up the primary cluster. Set the following environment variables for your primary cluster context:

   export CTX_PRIMARY=<primary_cluster_context_name> # e.g., kind-primary
   export KUBECONFIG=~/.kube/config # Adjust path if necessary
   export PRIMARY_CLUSTER_NAME=<primary_cluster_name> # e.g., primary
   export ONPREM_DOMAIN=<your_onprem_domain> # e.g., example.local
   export KUADRANT_SUBDOMAIN=kuadrant # Subdomain to delegate

   Copy to Clipboard Toggle word wrap

2. Install CoreDNS using the Connectivity Link kustomization, which includes the required kuadrant plugin. Apply the following configuration to the primary cluster, replacing <kuadrant-coredns-kustomize-url> with the actual URL for the Kuadrant CoreDNS kustomization.

   kustomize build --enable-helm github.com/kuadrant/dns-operator/config/coredns?ref=v0.15.0 | kubectl apply --context ${CTX_PRIMARY} -f -

   Copy to Clipboard Toggle word wrap
   Note

   The default CoreDNS Helm chart does not include the kuadrant plugin. You must use the Connectivity Link-provided kustomization which bundles a customized CoreDNS build.

3. Wait for the CoreDNS service to get an external IP address and store it:

   export COREDNS_IP_PRIMARY=$(kubectl --context $CTX_PRIMARY -n kuadrant-system get service <coredns-service-name> -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
   echo "CoreDNS Primary IP: ${COREDNS_IP_PRIMARY}"

   Copy to Clipboard Toggle word wrap

   You need this IP address later to configure delegation on your authoritative on-premises DNS server.

4. Create a ConfigMap to define the authoritative zone for CoreDNS on the primary cluster. This minimal configuration enables the kuadrant plugin and GeoIP features.

   cat | kubectl --context $CTX_PRIMARY apply -f -
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: coredns-kuadrant-config
     namespace: kuadrant-system
   data:
     Corefile: |
       ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}:53 {
           debug
           errors
           health {
               lameduck 5s
           }
           ready
           log
           geoip GeoLite2-City-demo.mmdb {
               edns-subnet
           }
           metadata
           kuadrant
       }

   Copy to Clipboard Toggle word wrap
   Note

   The geoip plugin in this example uses the GeoLite2-City-demo.mmdb database included for demonstration purposes. For production or accurate GeoIP routing, mount your licensed MaxMind GeoIP database into the CoreDNS pod and update the filename in the Corefile.

5. Update the CoreDNS deployment to use the new configuration:

   kubectl --context $CTX_PRIMARY -n kuadrant-system patch deployment <coredns-deployment-name> --patch '{"spec":{"template":{"spec":{"volumes":[{"name":"config-volume","configMap":{"name":"coredns-kuadrant-config","items":[{"key":"Corefile","path":"Corefile"}]}}]}}}}'

   Copy to Clipboard Toggle word wrap

6. Wait for the deployment rollout to complete:

   kubectl --context $CTX_PRIMARY -n kuadrant-system rollout status deployment/<coredns-deployment-name>

   Copy to Clipboard Toggle word wrap

7. Create the Kubernetes Secret that Connectivity Link uses to interact with CoreDNS. This secret specifies the zones this provider instance is authoritative for.

   kubectl create secret generic coredns-credentials \
     --namespace=kuadrant-system \
     --type=kuadrant.io/coredns \
     --from-literal=ZONES="${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}" \
     --context ${CTX_PRIMARY}

   Copy to Clipboard Toggle word wrap

8. On your authoritative on-premises DNS server, configure delegation for the ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN} subdomain to the external IP addresses of the CoreDNS services running on your primary and secondary clusters ($COREDNS_IP_PRIMARY and $COREDNS_IP_SECONDARY). The specific steps depend on your DNS server software (for example, BIND, Windows DNS Server). You typically need to add NS (Name Server) records pointing the subdomain to the CoreDNS IP addresses. For example:

   ; Delegate kuadrant.example.local to CoreDNS instances
   $ORIGIN ${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}.
   @       IN      SOA     ns1.${ONPREM_DOMAIN}. hostmaster.${ONPREM_DOMAIN}. (
                           2023102601 ; serial
                           7200       ; refresh (2 hours)
                           3600       ; retry (1 hour)
                           1209600    ; expire (2 weeks)
                           3600       ; minimum (1 hour)
                           )
           IN      NS      coredns-primary.${KUADRANT_SUBDOMAIN}.${ONPREM_DOMAIN}.
   
   coredns-primary   IN A ${COREDNS_IP_PRIMARY}

   Copy to Clipboard Toggle word wrap