ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers.
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 CloudDNS.
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.
ExternalDNS' current release is v0.4. This version allows you to keep selected zones (via --domain-filter) synchronized with Ingresses and Services of type=LoadBalancer in various cloud providers:
From this release, ExternalDNS can become aware of the records it is managing (enabled via --registry=txt), therefore ExternalDNS can safely manage non-empty hosted zones. We strongly encourage you to use v0.4 with --registry=txt enabled and --txt-owner-id set 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, or
--registry txt could be replaced with EXTERNAL_DNS_REGISTRY=txt.
The following tutorials are provided:
- AWS
- Azure
- Cloudflare
- DigitalOcean
- Google Container Engine
Make sure you have the following prerequisites:
- A local Go 1.7+ development environment.
- Access to a Google/AWS account with the DNS API enabled.
- Access to a Kubernetes cluster that supports exposing Services, e.g. GKE.
First, get ExternalDNS:
$ go get -u github.com/kubernetes-incubator/external-dnsNext, run an application and expose it via a Kubernetes Service:
$ kubectl run nginx --image=nginx --replicas=1 --port=80
$ kubectl expose deployment nginx --port=80 --target-port=80 --type=LoadBalancerAnnotate the Service with your desired external DNS name. Make sure to change example.org to your domain.
$ kubectl annotate service nginx "external-dns.alpha.kubernetes.io/hostname=nginx.example.org."Locally run a single sync loop of ExternalDNS.
$ external-dns --registry txt --txt-owner-id my-cluster-id --provider google --google-project example-project --source service --once --dry-runThis should output the DNS records it will modify to match the managed zone with the DNS records you desire. Note TXT records having my-cluster-id value embedded. Those are used to ensure that ExternalDNS is aware of the records it manages.
Once you're satisfied with the result, you can run ExternalDNS like you would run it in your cluster: as a control loop, and not in dry-run mode:
$ external-dns --registry txt --txt-owner-id my-cluster-id --provider google --google-project example-project --source serviceCheck that ExternalDNS has created the desired DNS record for your Service and that it points to its load balancer's IP. Then try to resolve it:
$ dig +short nginx.example.org.
104.155.60.49Now you can experiment and watch how ExternalDNS makes sure that your DNS records are configured as desired. Here are a couple of things you can try out:
- Change the desired hostname by modifying the Service's annotation.
- Recreate the Service and see that the DNS record will be updated to point to the new load balancer IP.
- Add another Service to create more DNS records.
- Remove Services to clean up your managed zone.
The tutorials section contains examples, including Ingress resources, and shows you how to set up ExternalDNS in different environments such as other cloud providers and alternative Ingress controllers.
ExternalDNS was built with extensibility in mind. Adding and experimenting with new DNS providers and sources of desired DNS records should be as easy as possible. It should also be possible to modify how ExternalDNS behaves—e.g. whether it should add records but never delete them.
Here's a rough outline on what is to come (subject to change):
- Support for Google CloudDNS
- Support for Kubernetes Services
- Support for AWS Route 53
- Support for Kubernetes Ingresses
- Support for AWS Route 53 via ALIAS
- Support for multiple zones
- Ownership System
- Support for AzureDNS
- Support for CloudFlare
- Support for DigitalOcean
- Multiple DNS names per Service
- Ability to replace Kops' DNS Controller
- Ability to replace Zalando's Mate
- Ability to replace Molecule Software's route53-kubernetes
- Support for CoreDNS and Azure DNS
- Support for record weights
- Support for different behavioral policies
- Support for Services with
type=NodePort - Support for TPRs
- Support for more advanced DNS record configurations
Have a look at the milestones to get an idea of where we currently stand.
We encourage you to get involved with ExternalDNS, as users as well as contributors. Read the contributing guidelines and have a look at the contributing docs to learn about building the project, the project structure, and the purpose of each package.
For an overview on how to write new Sources and Providers check out Sources and Providers.
Feel free to reach out to us on the Kubernetes slack in the #sig-network channel.
ExternalDNS is an effort to unify the following similar projects in order to bring the Kubernetes community an easy and predictable way of managing DNS records across cloud providers based on their Kubernetes resources:
- Kops' DNS Controller
- Zalando's Mate
- Molecule Software's route53-kubernetes
This is a Kubernetes Incubator project. The project was established 2017-Feb-9 (initial announcement here). The incubator team for the project is:
- Sponsor: sig-network
- Champion: Tim Hockin (@thockin)
- SIG: sig-network
For more information about sig-network, such as meeting times and agenda, check out the community site.
Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.