hide: - toc - navigation

ExternalDNS

ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers.

Documentation

This README is a part of the complete documentation, available here and DeepWiki.

What It Does

Inspired by Kubernetes DNS, Kubernetes' cluster-internal DNS server, ExternalDNS makes Kubernetes resources discoverable via public DNS servers. Like KubeDNS, it retrieves a list of resources (Services, Ingresses, etc.) from the Kubernetes API to determine a desired list of DNS records. Unlike KubeDNS, however, it's not a DNS server itself, but merely configures other DNS providers accordingly—e.g. AWS Route 53 or Google Cloud DNS.

In a broader sense, ExternalDNS allows you to control DNS records dynamically via Kubernetes resources in a DNS provider-agnostic way.

The FAQ contains additional information and addresses several questions about key concepts of ExternalDNS.

To see ExternalDNS in action, have a look at this video or read this blogpost.

The Latest Release

• current release process

ExternalDNS allows you to keep selected zones (via --domain-filter) synchronized with Ingresses and Services of type=LoadBalancer and nodes in various DNS providers:

• Google Cloud DNS
• AWS Route 53
• AWS Cloud Map
• AzureDNS
• Civo
• CloudFlare
• DNSimple
• PowerDNS
• CoreDNS
• Exoscale
• Oracle Cloud Infrastructure DNS
• Linode DNS
• RFC2136
• NS1
• TransIP
• OVHcloud
• Scaleway
• Akamai Edge DNS
• GoDaddy
• Gandi
• Plural
• Pi-hole
• Alibaba Cloud DNS
• Myra Security DNS

ExternalDNS is, by default, aware of the records it is managing, therefore it can safely manage non-empty hosted zones. We strongly encourage you to set --txt-owner-id to a unique value that doesn't change for the lifetime of your cluster. You might also want to run ExternalDNS in a dry run mode (--dry-run flag) to see the changes to be submitted to your DNS Provider API.

Note that all flags can be replaced with environment variables; for instance, --dry-run could be replaced with EXTERNAL_DNS_DRY_RUN=1.

New providers

No new provider will be added to ExternalDNS in-tree.

ExternalDNS has introduced a webhook system, which can be used to add a new provider. See PR #3063 for all the discussions about it.

Some known providers using webhooks are the ones in the table below.

NOTE: The maintainers of ExternalDNS have not reviewed those providers, use them at your own risk and following the license and usage recommendations provided by the respective projects. The maintainers of ExternalDNS take no responsibility for any issue or damage from the usage of any externally developed webhook.

Status of in-tree providers

ExternalDNS supports multiple DNS providers which have been implemented by the ExternalDNS contributors. Maintaining all of those in a central repository is a challenge, which introduces lots of toil and potential risks.

This mean that external-dns has begun the process to move providers out of tree. See #4347 for more details. Those who are interested can create a webhook provider based on an in-tree provider and after submit a PR to reference it here.

We define the following stability levels for providers:

• Stable: Used for smoke tests before a release, used in production and maintainers are active.
• Beta: Community supported, well tested, but maintainers have no access to resources to execute integration tests on the real platform and/or are not using it in production.
• Alpha: Community provided with no support from the maintainers apart from reviewing PRs.

The following table clarifies the current status of the providers according to the aforementioned stability levels:

Kubernetes version compatibility

Breaking changes were introduced in external-dns in the following versions:

• v0.10.0: use of networking.k8s.io/ingresses instead of extensions/ingresses (see #2281)
• v0.18.0: use of discovery.k8s.io/endpointslices instead of endpoints (see #5493)
• v0.19.0: don't expose internal ipv6 by default (see #5575) and disable legacy listeners on traefik.containo.us API Group (see #5565)

Running ExternalDNS

There are two ways of running ExternalDNS:

• Deploying to a Cluster
• Running Locally

Deploying to a Cluster

The following tutorials are provided:

• Akamai Edge DNS
• Alibaba Cloud
• AWS
• AWS Load Balancer Controller
• Route53
  • Same domain for public and private Route53 zones
• Cloud Map
• Kube Ingress AWS Controller
• Azure DNS
• Azure Private DNS
• Civo
• Cloudflare
• CoreDNS
• DNSimple
• Exoscale
• ExternalName Services
• Google Kubernetes Engine
• Using Google's Default Ingress Controller
• Using the Nginx Ingress Controller
• Headless Services
• IONOS Cloud
• Istio Gateway Source
• [Linode](docs/tutorials/li