external-dns/docs/contributing/bug-report.md

Bug Report Guide

Before filing a bug: validate the behavior against the latest release. We do not support past versions.

[!WARNING]

The outputs requested in this guide may contain sensitive information such as domain names, IP addresses, cloud account IDs, annotation values, or credentials. Redact any sensitive values before posting them publicly in a GitHub issue.

Bug reports regularly arrive without the information needed to reproduce or debug them — no process flags, no normalized Kubernetes resources, no logs — forcing maintainers to ask multiple follow-up rounds before any investigation can start.

A bug that cannot be reproduced will not be fixed. This page explains exactly what information to collect and how to collect it so that maintainers can reason about your environment without making assumptions.

---

Why we need normalized resources

external-dns only reads Kubernetes API objects at runtime. It does not read Helm values, Terraform state, Flux kustomizations, or AWS Load Balancer Controller annotations directly — it sees only what those tools produce in the API server.

Please provide the live Kubernetes objects, not the templates that generated them.

---

Reproduce on a local cluster

If your environment is not reproducible or involves proprietary infrastructure, the fastest path to a fix is reproducing the issue on a local cluster: minikube or kind.

---

Step-by-step: collect the required information

Work through each section below and paste the output into your issue.

1 — external-dns info

Version

kubectl get pod -n <namespace> -l app.kubernetes.io/name=external-dns \
  -o jsonpath='{.items[0].spec.containers[0].image}'

Or, if you have direct access to the binary:

external-dns --version

Startup flags

Helm values and Terraform variables are not useful here because they are transformed before reaching the process. We need the flags that the external-dns process was actually started with.

kubectl get pod -n <namespace> <pod-name> \
  -o jsonpath='{range .spec.containers[*]}{.args}{end}'

Example of the kind of output we need:

--provider=aws
--registry=txt
--txt-owner-id=my-cluster
--source=ingress
--domain-filter=example.com
--log-level=debug

Debug logs

Enable debug logging before reproducing the issue. If external-dns is already deployed, patch it:

kubectl set env deployment/external-dns \
  -n <namespace> \
  EXTERNAL_DNS_LOG_LEVEL=debug

Or add --log-level=debug to the process args and redeploy.

Once the pod restarts, collect logs covering the full reconciliation loop that should have created or updated the record:

kubectl logs -n <namespace> \
  -l app.kubernetes.io/name=external-dns \
  --since=10m \
  --prefix=true \
  > extdns-debug.log

Paste the full content of extdns-debug.log into the issue (or attach the file).

Specifically we look for lines like:

level=debug msg="Desired change: CREATE example.com A [1.2.3.4]"
level=debug msg="No endpoints could be generated from ingress ..."
level=info  msg="All records are already up to date"

2 — Kubernetes resources

Collect the full YAML — including status — for every resource relevant to your source type. If reporting a regression, include the output before and after the change. The status.loadBalancer field is critical for ingress and service sources.

kubectl get <resource> -A -o yaml

Common examples by source:

kubectl get ingress,service -A -o yaml          # source=ingress
kubectl get service -A -o yaml                  # source=service
kubectl get gateway,httproute -A -o yaml        # source=gateway-httproute
kubectl get dnsendpoint -A -o yaml              # source=crd
kubectl get nodes -o yaml                       # source=node

3 — DNS provider: existing vs expected records

Tell us what records actually exist in your DNS provider and what you expected to exist.

For Route 53:

aws route53 list-resource-record-sets \
  --hosted-zone-id <ZONE_ID> \
  --query 'ResourceRecordSets[?Name==`example.com.`]'

For other providers, use their CLI or API equivalent, or paste a screenshot from the console.

Format the answer as:

Record	Type	Value	TTL	Expected?
foo.example.com	A	1.2.3.4	300	yes
foo.example.com	TXT	"heritage=external-dns,..."	300	yes

4 — TXT ownership records

external-dns uses TXT records to track ownership. If records are not being created or are being deleted unexpectedly, include the TXT records:

# Route 53 example — look for TXT records with "heritage=external-dns"
aws route53 list-resource-record-sets \
  --hosted-zone-id <ZONE_ID> \
  --query 'ResourceRecordSets[?Type==`TXT`]'

---

Collection scripts

external-dns info — version, startup args, and logs:

[[% include 'snippets/contributing/collect-extdns-info.sh' %]]

Kubernetes resources — set RESOURCE to the resource(s) relevant to your source (e.g. ingress, "ingress,service", "gateway,httproute", dnsendpoint):

[[% include 'snippets/contributing/collect-resources.sh' %]]

---

Checklist before submitting

• I have searched existing issues and tried to find a fix myself
• I am using the latest release, or have checked the staging image to confirm the bug is still reproducible
• I have provided the actual process flags (not Helm values)
• I have provided kubectl get <resource> -o yaml output (with status)
• I have provided external-dns debug logs
• I have described what DNS records exist and what I expected

---

Notes on third-party controllers

If you are using AWS Load Balancer Controller, Flux, Terraform, or similar tools alongside external-dns, note that multiple controllers may be reading and modifying the same Kubernetes objects at runtime. external-dns maintainers can only reason about what external-dns sees in the API server — please provide normalized Kubernetes objects as described above, rather than the configuration of the surrounding tooling.

Contributors and maintainers are very unlikely to be running the same stack. Bug reporters should assume zero shared context — no cluster access, no cloud account, no Helm values, and no knowledge of any third-party controllers in use. A well-detailed report — see the checklist above — minimizes guesswork and significantly increases the chance of resolution.