Install CoreDNS On Kubernetes: A Quick & Easy Guide

Nov 3, 2025 by Team 52 views

Let's dive into setting up CoreDNS on your Kubernetes cluster! CoreDNS is often the default DNS server in Kubernetes, handling service discovery and name resolution within the cluster. This guide will walk you through the process, ensuring you have a smooth and functional DNS setup. It's crucial for services to find each other, and CoreDNS makes that happen. We will focus on verifying that CoreDNS is running, checking the CoreDNS configuration, and troubleshooting common issues. Get ready to make your Kubernetes cluster even more efficient!

Prerequisites

Before we get started, make sure you have the following:

A running Kubernetes cluster: This could be Minikube, Kind, a cloud-based Kubernetes service (like GKE, EKS, or AKS), or a self-hosted cluster.
kubectl installed and configured: kubectl is the command-line tool for interacting with your Kubernetes cluster. Ensure it's properly set up to communicate with your cluster.
Basic understanding of Kubernetes concepts: Familiarity with Pods, Services, and Deployments will be helpful.

Step 1: Verify CoreDNS Pods are Running

The first thing we need to do is confirm that CoreDNS pods are up and running in your cluster. CoreDNS usually runs in the kube-system namespace. Let's check their status.

Open your terminal and run the following command:

kubectl get pods -n kube-system -l k8s-app=kube-dns

This command does the following:

kubectl get pods: This tells kubectl to retrieve information about pods.
-n kube-system: This specifies that we're looking in the kube-system namespace, where CoreDNS typically resides.
-l k8s-app=kube-dns: This filters the pods based on the label k8s-app=kube-dns, which is commonly used to identify CoreDNS pods.

Expected Output:

You should see output similar to this:

NAME                       READY   STATUS    RESTARTS   AGE
coredns-66c46f6d69-mcvgq   1/1     Running   0          2d
coredns-66c46f6d69-qbxnq   1/1     Running   0          2d

If the STATUS column shows Running for all CoreDNS pods, that's great! It means CoreDNS is likely functioning correctly. If you see a status like Pending, Error, or CrashLoopBackOff, it indicates a problem with the CoreDNS pods. Scroll down to the troubleshooting section for help.

Why is this important? Verifying the pods are running confirms that the CoreDNS deployment is active and attempting to serve DNS requests. Without running pods, your cluster's internal DNS resolution will fail.

Step 2: Check the CoreDNS Configuration (Corefile)

The CoreDNS configuration is stored in a ConfigMap named coredns. Let's take a look at the configuration file, known as the Corefile, to understand how CoreDNS is set up. The Corefile dictates how CoreDNS handles DNS queries. This is a very important step in the CoreDNS setup!

Run the following command to view the Corefile:

kubectl get configmap coredns -n kube-system -o yaml

This command does the following:

kubectl get configmap coredns: This retrieves the ConfigMap named coredns.
-n kube-system: This specifies that we're looking in the kube-system namespace.
-o yaml: This tells kubectl to output the ConfigMap in YAML format, which is human-readable.

Examine the Output:

Look for the data section in the output. Inside the data section, you should find an entry named Corefile. The value of Corefile is the actual CoreDNS configuration.

A typical Corefile looks something like this:

apiVersion: v1
data:
  Corefile: |
    .:53 {
        errors
        health {
            lameduck
        }
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
            pods verified
            fallthrough in-addr.arpa ip6.arpa
        }
        prometheus :9153
        forward . /etc/resolv.conf {
            prefer_udp
        }
        cache 30
        loop
        reload
        loadbalance
    }
kind: ConfigMap
metadata:
  name: coredns
  namespace: kube-system

Understanding the Corefile:

.:53: This tells CoreDNS to listen on all interfaces on port 53 (the standard DNS port).
errors: Enables error logging.
health: Enables a health endpoint for CoreDNS.
ready: Exposes a readiness endpoint.
kubernetes cluster.local in-addr.arpa ip6.arpa: This is the core of the Kubernetes integration. It tells CoreDNS to handle DNS queries for the cluster.local domain (the default Kubernetes domain), as well as reverse DNS lookups for IP addresses.
pods verified: This tells CoreDNS to only return IP addresses for pods that are in the Running state.
fallthrough in-addr.arpa ip6.arpa: If CoreDNS cannot resolve a reverse DNS lookup, it will forward the query to the next server in the chain.
prometheus :9153: Enables Prometheus metrics on port 9153.
forward . /etc/resolv.conf: Forwards any queries that CoreDNS cannot resolve to the upstream DNS servers defined in /etc/resolv.conf on the node.
cache 30: Caches DNS responses for 30 seconds.
loop: Detects and prevents loops in DNS queries.
reload: Allows CoreDNS to reload the Corefile when it's changed.
loadbalance: Load balances between multiple upstream DNS servers.

Customizing the Corefile:

You can modify the Corefile to customize CoreDNS behavior. For example, you might want to add custom DNS records or configure CoreDNS to forward queries to a different set of upstream DNS servers. To modify the Corefile, edit the coredns ConfigMap:

kubectl edit configmap coredns -n kube-system

Important: Be very careful when editing the Corefile. A syntax error in the Corefile can cause CoreDNS to fail, which will disrupt DNS resolution in your cluster. After making changes, verify that the CoreDNS pods restart successfully. A rolling restart will apply the new configuration.

Why is this important? Examining the Corefile ensures that CoreDNS is configured correctly to integrate with Kubernetes and handle DNS queries as expected. Understanding the Corefile allows you to customize CoreDNS behavior to meet your specific needs. Having a solid understanding will make you a Kubernetes master!

Step 3: Test DNS Resolution

Now that we've verified that the CoreDNS pods are running and examined the Corefile, let's test whether DNS resolution is working correctly within the cluster. We can do this by creating a simple pod and using nslookup or dig to resolve a service name.

Create a Test Pod:

First, create a simple pod that includes DNS utilities. We'll use a busybox image for this purpose. Create a file named test-pod.yaml with the following content:

apiVersion: v1
kind: Pod
metadata:
  name: dns-test
spec:
  containers:
  - name: dns-test
    image: busybox:latest
    command: ['sleep', '3600']
    imagePullPolicy: IfNotPresent
  restartPolicy: Always

Then, apply this YAML file to create the pod:

kubectl apply -f test-pod.yaml

Execute DNS Lookup:

Once the pod is running, you can execute nslookup or dig inside the pod to test DNS resolution. First, get a shell into the pod:

kubectl exec -it dns-test -- sh

Now, inside the pod's shell, run nslookup or dig to resolve a Kubernetes service name. For example, let's try resolving the kubernetes.default service, which should always be available:

nslookup kubernetes.default

Or, using dig:

dig kubernetes.default

Expected Output:

If DNS resolution is working correctly, you should see output similar to this (for nslookup):

Server:    10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local

Name:      kubernetes.default
Address 1: 10.96.0.1 kubernetes.default.svc.cluster.local

And similar output for dig, with the ANSWER SECTION showing the resolved IP address.

If you see an error message like server can't find kubernetes.default: NXDOMAIN, it indicates that DNS resolution is not working correctly. This usually means there's a problem with CoreDNS configuration or the CoreDNS pods are not running properly. Check the troubleshooting section below.

Why is this important? Testing DNS resolution confirms that your cluster's DNS is functioning as expected, allowing services to discover and communicate with each other. This is a fundamental aspect of a healthy Kubernetes cluster. This will help you sleep better at night!

Troubleshooting Common Issues

If you encounter problems with CoreDNS, here are some common issues and their solutions:

CoreDNS Pods Not Running: If the CoreDNS pods are in a Pending, Error, or CrashLoopBackOff state, there might be a problem with resource allocation, networking, or the CoreDNS configuration itself.
- Solution:
  - Check the logs of the CoreDNS pods using kubectl logs -n kube-system <pod-name>. Look for error messages that might indicate the cause of the problem. Maybe there is not enough memory allocated to the cluster.
  - Ensure that there are enough resources (CPU and memory) available in your cluster for the CoreDNS pods. If your cluster is resource-constrained, CoreDNS might not be able to start.
  - Verify that the networking configuration allows the CoreDNS pods to communicate with each other and with other pods in the cluster. Check the firewall rules.
DNS Resolution Fails: If nslookup or dig fails to resolve service names, there might be a problem with the CoreDNS configuration or the CoreDNS pods are not functioning correctly.
- Solution:
  - Double-check the Corefile for syntax errors or misconfigurations. Use kubectl edit configmap coredns -n kube-system to edit the Corefile.
  - Restart the CoreDNS pods to apply any changes you've made to the Corefile. You can do this by deleting the pods, and Kubernetes will automatically recreate them.
  - Verify that the kubernetes plugin is configured correctly in the Corefile and that it's pointing to the correct Kubernetes API server address.
CoreDNS Failing to Start After Corefile Change: Incorrect syntax in the Corefile can prevent CoreDNS from starting.
- Solution:
  - Carefully review the changes you made to the Corefile. Use a YAML validator to check for syntax errors.
  - If possible, revert to a known working Corefile configuration.
  - Check the CoreDNS pod logs for error messages that indicate the cause of the startup failure. The logs often provide clues about syntax errors or misconfigurations.

Why is this important? Troubleshooting ensures that you can quickly identify and resolve issues with CoreDNS, maintaining a healthy and functional Kubernetes cluster. This is a critical skill for any Kubernetes administrator. It is going to save you time in the future.

Conclusion

Congratulations! You've successfully installed and configured CoreDNS on your Kubernetes cluster. You now have a solid foundation for service discovery and name resolution within your cluster. Remember to monitor your CoreDNS pods and review logs frequently to ensure its smooth operation. Regular maintenance and monitoring will help you avoid potential problems. CoreDNS is a vital component of any Kubernetes cluster, and understanding how it works is essential for managing your cluster effectively. Keep learning, keep exploring, and have fun with Kubernetes! You guys are doing great!