Troubleshooting¶

This guide provides steps to diagnose and resolve common issues with automated DNS management. Since you interact with ExternalDNS by defining Kubernetes resources via GitOps, these steps focus on what you can check and configure yourself.

Step 1: Self-Service Checks¶

Before escalating an issue, please perform the following checks on your Kubernetes resource manifests and their status in the cluster.

Issue: DNS Record is Not Created or Updated¶

Symptom: You have deployed a Service, Ingress, or HTTPProxy, but the expected DNS record does not appear in your DNS provider after some minutes.

Checks:

Verify Annotations in Git: The most common issue is a missing or incorrect annotation in your YAML file. Ensure your resource has the following annotation, replacing webapp.example.com with your desired hostname:
```
metadata:
annotations:
    external-dns.alpha.kubernetes.io/hostname: webapp.example.com
```
- Check carefully for typos in both the annotation key and the hostname value.
Inspect the Resource's Status: ExternalDNS can only create a record if the resource has a public-facing IP address or hostname. Use kubectl describe to check this.
For a Service:
```
kubectl describe service <your-service-name> -n <your-namespace>
```
Look for an Ingress value under status.loadBalancer. If this is empty or <pending>, the issue is with the cloud provider's load balancer provisioning, not ExternalDNS.
For an Ingress or HTTPProxy:
```
kubectl describe ingress <your-ingress-name> -n <your-namespace>
```
Check the Address field. If it is empty, the ingress controller has not yet assigned an IP address.

Issue: DNS Record Points to the Wrong IP Address¶

Symptom: The DNS record creation was successful, but it points to an incorrect IP address (e.g., an internal cluster IP).

Checks:

Check the Source of Truth: ExternalDNS uses the IP address or hostname from the status of your Kubernetes resource (Service, Ingress, etc.).
Use the same kubectl describe commands from the previous section to inspect the Ingress or Address field. The IP address listed there is the one ExternalDNS will use. If that IP is incorrect, the issue lies with the component that provides it (e.g., the cloud load balancer or the ingress controller), not with ExternalDNS itself.

Step 2: When to Contact Support¶

If you have completed all the self-service checks above and your issue is still not resolved, it's time to contact the platform provider. An underlying issue with the ExternalDNS component may be preventing it from processing your resource correctly.

Please provide the following information in your support request to ensure a speedy resolution:

Resource Details: The namespace, type, and name of the Kubernetes resource (e.g., namespace: my-app, service: my-web-app).
Expected Outcome: The DNS hostname you are trying to create (e.g., webapp.example.com).
Full Resource Manifest: The complete YAML definition of your resource from your Git repository.
Resource Status: The output of the relevant kubectl describe command for your resource.