sigs.k8s.io/external-dns@v0.14.1/README.md (about) 1 --- 2 hide: 3 - toc 4 - navigation 5 --- 6 7 <p align="center"> 8 <img src="docs/img/external-dns.png" width="40%" align="center" alt="ExternalDNS"> 9 </p> 10 11 # ExternalDNS 12 13 [](https://github.com/kubernetes-sigs/external-dns/actions) [](https://coveralls.io/github/kubernetes-sigs/external-dns) [](https://github.com/kubernetes-sigs/external-dns/releases) [](https://godoc.org/github.com/kubernetes-sigs/external-dns) [](https://goreportcard.com/report/github.com/kubernetes-sigs/external-dns) [](https://kubernetes-sigs.github.io/external-dns/) 14 15 16 ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers. 17 18 ## What It Does 19 20 Inspired by [Kubernetes DNS](https://github.com/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](https://kubernetes.io/docs/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](https://aws.amazon.com/route53/) or [Google Cloud DNS](https://cloud.google.com/dns/docs/). 21 22 In a broader sense, ExternalDNS allows you to control DNS records dynamically via Kubernetes resources in a DNS provider-agnostic way. 23 24 The [FAQ](docs/faq.md) contains additional information and addresses several questions about key concepts of ExternalDNS. 25 26 To see ExternalDNS in action, have a look at this [video](https://www.youtube.com/watch?v=9HQ2XgL9YVI) or read this [blogpost](https://codemine.be/posts/20190125-devops-eks-externaldns/). 27 28 ## The Latest Release 29 30 ExternalDNS allows you to keep selected zones (via `--domain-filter`) synchronized with Ingresses and Services of `type=LoadBalancer` and nodes in various DNS providers: 31 * [Google Cloud DNS](https://cloud.google.com/dns/docs/) 32 * [AWS Route 53](https://aws.amazon.com/route53/) 33 * [AWS Cloud Map](https://docs.aws.amazon.com/cloud-map/) 34 * [AzureDNS](https://azure.microsoft.com/en-us/services/dns) 35 * [BlueCat](https://bluecatnetworks.com) 36 * [Civo](https://www.civo.com) 37 * [CloudFlare](https://www.cloudflare.com/dns) 38 * [RcodeZero](https://www.rcodezero.at/) 39 * [DigitalOcean](https://www.digitalocean.com/products/networking) 40 * [DNSimple](https://dnsimple.com/) 41 * [Infoblox](https://www.infoblox.com/products/dns/) 42 * [Dyn](https://dyn.com/dns/) 43 * [OpenStack Designate](https://docs.openstack.org/designate/latest/) 44 * [PowerDNS](https://www.powerdns.com/) 45 * [CoreDNS](https://coredns.io/) 46 * [Exoscale](https://www.exoscale.com/dns/) 47 * [Oracle Cloud Infrastructure DNS](https://docs.cloud.oracle.com/iaas/Content/DNS/Concepts/dnszonemanagement.htm) 48 * [Linode DNS](https://www.linode.com/docs/networking/dns/) 49 * [RFC2136](https://tools.ietf.org/html/rfc2136) 50 * [NS1](https://ns1.com/) 51 * [TransIP](https://www.transip.eu/domain-name/) 52 * [VinylDNS](https://www.vinyldns.io) 53 * [Vultr](https://www.vultr.com) 54 * [OVH](https://www.ovh.com) 55 * [Scaleway](https://www.scaleway.com) 56 * [Akamai Edge DNS](https://learn.akamai.com/en-us/products/cloud_security/edge_dns.html) 57 * [GoDaddy](https://www.godaddy.com) 58 * [Gandi](https://www.gandi.net) 59 * [ANS Group SafeDNS](https://portal.ans.co.uk/safedns/) 60 * [IBM Cloud DNS](https://www.ibm.com/cloud/dns) 61 * [TencentCloud PrivateDNS](https://cloud.tencent.com/product/privatedns) 62 * [TencentCloud DNSPod](https://cloud.tencent.com/product/cns) 63 * [Plural](https://www.plural.sh/) 64 * [Pi-hole](https://pi-hole.net/) 65 66 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. 67 68 Note that all flags can be replaced with environment variables; for instance, 69 `--dry-run` could be replaced with `EXTERNAL_DNS_DRY_RUN=1`. 70 71 ## New providers 72 73 No new provider will be added to ExternalDNS _in-tree_. 74 75 ExternalDNS has introduced a webhook system, which can be used to add a new provider. 76 See PR #3063 for all the discussions about it. 77 78 Known providers using webhooks: 79 80 | Provider | Repo | 81 | -------- | ----------- | 82 | IONOS | https://github.com/ionos-cloud/external-dns-ionos-webhook | 83 | Adguard Home Provider | https://github.com/muhlba91/external-dns-provider-adguard | 84 | STACKIT | https://github.com/stackitcloud/external-dns-stackit-webhook | 85 | GleSYS | https://github.com/glesys/external-dns-glesys | 86 | Hetzner | https://github.com/mconfalonieri/external-dns-hetzner-webhook | 87 | Bizfly Cloud | https://github.com/bizflycloud/external-dns-bizflycloud-webhook | 88 | Netcup | https://github.com/mrueg/external-dns-netcup-webhook | 89 | Gcore | https://github.com/G-Core/external-dns-gcore-webhook | 90 91 ## Status of providers 92 93 ExternalDNS supports multiple DNS providers which have been implemented by the [ExternalDNS contributors](https://github.com/kubernetes-sigs/external-dns/graphs/contributors). Maintaining all of those in a central repository is a challenge and we have limited resources to test changes. This means that it is very hard to test all providers for possible regressions and, as written in the [Contributing](#Contributing) section, we encourage contributors to step in as maintainers for the individual providers and help by testing the integrations. 94 95 End-to-end testing of ExternalDNS is currently 96 [performed](https://github.com/zalando-incubator/kubernetes-on-aws/blob/dev/test/e2e/external_dns.go) 97 in the separate 98 [kubernetes-on-aws](https://github.com/zalando-incubator/kubernetes-on-aws) 99 repository. 100 101 We define the following stability levels for providers: 102 103 - **Stable**: Used for smoke tests before a release, used in production and maintainers are active. 104 - **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. 105 - **Alpha**: Community provided with no support from the maintainers apart from reviewing PRs. 106 107 The following table clarifies the current status of the providers according to the aforementioned stability levels: 108 109 | Provider | Status | Maintainers | 110 | -------- | ------ | ----------- | 111 | Google Cloud DNS | Stable | | 112 | AWS Route 53 | Stable | | 113 | AWS Cloud Map | Beta | | 114 | Akamai Edge DNS | Beta | | 115 | AzureDNS | Beta | | 116 | BlueCat | Alpha | @seanmalloy @vinny-sabatini | 117 | Civo | Alpha | @alejandrojnm | 118 | CloudFlare | Beta | | 119 | RcodeZero | Alpha | | 120 | DigitalOcean | Alpha | | 121 | DNSimple | Alpha | | 122 | Infoblox | Alpha | @saileshgiri | 123 | Dyn | Alpha | | 124 | OpenStack Designate | Alpha | | 125 | PowerDNS | Alpha | | 126 | CoreDNS | Alpha | | 127 | Exoscale | Alpha | | 128 | Oracle Cloud Infrastructure DNS | Alpha | | 129 | Linode DNS | Alpha | | 130 | RFC2136 | Alpha | | 131 | NS1 | Alpha | | 132 | TransIP | Alpha | | 133 | VinylDNS | Alpha | | 134 | RancherDNS | Alpha | | 135 | OVH | Alpha | | 136 | Scaleway DNS | Alpha | @Sh4d1 | 137 | Vultr | Alpha | | 138 | UltraDNS | Alpha | | 139 | GoDaddy | Alpha | | 140 | Gandi | Alpha | @packi | 141 | SafeDNS | Alpha | @assureddt | 142 | IBMCloud | Alpha | @hughhuangzh | 143 | TencentCloud | Alpha | @Hyzhou | 144 | Plural | Alpha | @michaeljguarino | 145 | Pi-hole | Alpha | @tinyzimmer | 146 147 ## Kubernetes version compatibility 148 149 A [breaking change](https://github.com/kubernetes-sigs/external-dns/pull/2281) was added in external-dns v0.10.0. 150 151 | ExternalDNS | <= 0.9.x | >= 0.10.0 | 152 | ------------------------------ | :----------------: | :----------------: | 153 | Kubernetes <= 1.18 | :white_check_mark: | :x: | 154 | Kubernetes >= 1.19 and <= 1.21 | :white_check_mark: | :white_check_mark: | 155 | Kubernetes >= 1.22 | :x: | :white_check_mark: | 156 157 ## Running ExternalDNS: 158 159 The are two ways of running ExternalDNS: 160 161 * Deploying to a Cluster 162 * Running Locally 163 164 ### Deploying to a Cluster 165 166 The following tutorials are provided: 167 168 * [Akamai Edge DNS](docs/tutorials/akamai-edgedns.md) 169 * [Alibaba Cloud](docs/tutorials/alibabacloud.md) 170 * AWS 171 * [AWS Load Balancer Controller](docs/tutorials/aws-load-balancer-controller.md) 172 * [Route53](docs/tutorials/aws.md) 173 * [Same domain for public and private Route53 zones](docs/tutorials/public-private-route53.md) 174 * [Cloud Map](docs/tutorials/aws-sd.md) 175 * [Kube Ingress AWS Controller](docs/tutorials/kube-ingress-aws.md) 176 * [Azure DNS](docs/tutorials/azure.md) 177 * [Azure Private DNS](docs/tutorials/azure-private-dns.md) 178 * [Civo](docs/tutorials/civo.md) 179 * [Cloudflare](docs/tutorials/cloudflare.md) 180 * [BlueCat](docs/tutorials/bluecat.md) 181 * [CoreDNS](docs/tutorials/coredns.md) 182 * [DigitalOcean](docs/tutorials/digitalocean.md) 183 * [DNSimple](docs/tutorials/dnsimple.md) 184 * [Dyn](docs/tutorials/dyn.md) 185 * [Exoscale](docs/tutorials/exoscale.md) 186 * [ExternalName Services](docs/tutorials/externalname.md) 187 * Google Kubernetes Engine 188 * [Using Google's Default Ingress Controller](docs/tutorials/gke.md) 189 * [Using the Nginx Ingress Controller](docs/tutorials/nginx-ingress.md) 190 * [Headless Services](docs/tutorials/hostport.md) 191 * [Infoblox](docs/tutorials/infoblox.md) 192 * [Istio Gateway Source](docs/tutorials/istio.md) 193 * [Kubernetes Security Context](docs/tutorials/security-context.md) 194 * [Linode](docs/tutorials/linode.md) 195 * [Nginx Ingress Controller](docs/tutorials/nginx-ingress.md) 196 * [NS1](docs/tutorials/ns1.md) 197 * [NS Record Creation with CRD Source](docs/tutorials/ns-record.md) 198 * [MX Record Creation with CRD Source](docs/tutorials/mx-record.md) 199 * [OpenStack Designate](docs/tutorials/designate.md) 200 * [Oracle Cloud Infrastructure (OCI) DNS](docs/tutorials/oracle.md) 201 * [PowerDNS](docs/tutorials/pdns.md) 202 * [RcodeZero](docs/tutorials/rcodezero.md) 203 * [RancherDNS (RDNS)](docs/tutorials/rdns.md) 204 * [RFC2136](docs/tutorials/rfc2136.md) 205 * [TransIP](docs/tutorials/transip.md) 206 * [VinylDNS](docs/tutorials/vinyldns.md) 207 * [OVH](docs/tutorials/ovh.md) 208 * [Scaleway](docs/tutorials/scaleway.md) 209 * [Vultr](docs/tutorials/vultr.md) 210 * [UltraDNS](docs/tutorials/ultradns.md) 211 * [GoDaddy](docs/tutorials/godaddy.md) 212 * [Gandi](docs/tutorials/gandi.md) 213 * [SafeDNS](docs/tutorials/UKFast_SafeDNS.md) 214 * [IBM Cloud](docs/tutorials/ibmcloud.md) 215 * [Nodes as source](docs/tutorials/nodes.md) 216 * [TencentCloud](docs/tutorials/tencentcloud.md) 217 * [Plural](docs/tutorials/plural.md) 218 * [Pi-hole](docs/tutorials/pihole.md) 219 220 ### Running Locally 221 222 See the [contributor guide](docs/contributing/getting-started.md) for details on compiling 223 from source. 224 225 #### Setup Steps 226 227 Next, run an application and expose it via a Kubernetes Service: 228 229 ```console 230 kubectl run nginx --image=nginx --port=80 231 kubectl expose pod nginx --port=80 --target-port=80 --type=LoadBalancer 232 ``` 233 234 Annotate the Service with your desired external DNS name. Make sure to change `example.org` to your domain. 235 236 ```console 237 kubectl annotate service nginx "external-dns.alpha.kubernetes.io/hostname=nginx.example.org." 238 ``` 239 240 Optionally, you can customize the TTL value of the resulting DNS record by using the `external-dns.alpha.kubernetes.io/ttl` annotation: 241 242 ```console 243 kubectl annotate service nginx "external-dns.alpha.kubernetes.io/ttl=10" 244 ``` 245 246 For more details on configuring TTL, see [here](docs/ttl.md). 247 248 Use the internal-hostname annotation to create DNS records with ClusterIP as the target. 249 250 ```console 251 kubectl annotate service nginx "external-dns.alpha.kubernetes.io/internal-hostname=nginx.internal.example.org." 252 ``` 253 254 If the service is not of type Loadbalancer you need the --publish-internal-services flag. 255 256 Locally run a single sync loop of ExternalDNS. 257 258 ```console 259 external-dns --txt-owner-id my-cluster-id --provider google --google-project example-project --source service --once --dry-run 260 ``` 261 262 This should output the DNS records it will modify to match the managed zone with the DNS records you desire. It also assumes you are running in the `default` namespace. See the [FAQ](docs/faq.md) for more information regarding namespaces. 263 264 Note: TXT records will have the `my-cluster-id` value embedded. Those are used to ensure that ExternalDNS is aware of the records it manages. 265 266 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: 267 268 ```console 269 external-dns --txt-owner-id my-cluster-id --provider google --google-project example-project --source service 270 ``` 271 272 Check 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: 273 274 ```console 275 dig +short nginx.example.org. 276 104.155.60.49 277 ``` 278 279 Now 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: 280 * Change the desired hostname by modifying the Service's annotation. 281 * Recreate the Service and see that the DNS record will be updated to point to the new load balancer IP. 282 * Add another Service to create more DNS records. 283 * Remove Services to clean up your managed zone. 284 285 The [tutorials](docs/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. 286 287 # Note 288 289 If using a txt registry and attempting to use a CNAME the `--txt-prefix` must be set to avoid conflicts. Changing `--txt-prefix` will result in lost ownership over previously created records. 290 291 If `externalIPs` list is defined for a `LoadBalancer` service, this list will be used instead of an assigned load balancer IP to create a DNS record. It's useful when you run bare metal Kubernetes clusters behind NAT or in a similar setup, where a load balancer IP differs from a public IP (e.g. with [MetalLB](https://metallb.universe.tf)). 292 293 ## Contributing 294 295 Are you interested in contributing to external-dns? We, the maintainers and community, would love your 296 suggestions, contributions, and help! Also, the maintainers can be contacted at any time to learn more 297 about how to get involved. 298 299 We also encourage ALL active community participants to act as if they are maintainers, even if you don't have 300 "official" write permissions. This is a community effort, we are here to serve the Kubernetes community. If you 301 have an active interest and you want to get involved, you have real power! Don't assume that the only people who 302 can get things done around here are the "maintainers". We also would love to add more "official" maintainers, so 303 show us what you can do! 304 305 The external-dns project is currently in need of maintainers for specific DNS providers. Ideally each provider 306 would have at least two maintainers. It would be nice if the maintainers run the provider in production, but it 307 is not strictly required. Provider listed [here](https://github.com/kubernetes-sigs/external-dns#status-of-providers) 308 that do not have a maintainer listed are in need of assistance. 309 310 Read the [contributing guidelines](CONTRIBUTING.md) and have a look at [the contributing docs](docs/contributing/getting-started.md) to learn about building the project, the project structure, and the purpose of each package. 311 312 For an overview on how to write new Sources and Providers check out [Sources and Providers](docs/contributing/sources-and-providers.md). 313 314 ## Heritage 315 316 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: 317 318 * Kops' [DNS Controller](https://github.com/kubernetes/kops/tree/HEAD/dns-controller) 319 * Zalando's [Mate](https://github.com/linki/mate) 320 * Molecule Software's [route53-kubernetes](https://github.com/wearemolecule/route53-kubernetes) 321 322 ### User Demo How-To Blogs and Examples 323 324 * A full demo on GKE Kubernetes. See [How-to Kubernetes with DNS management (ssl-manager pre-req)](https://medium.com/@jpantjsoha/how-to-kubernetes-with-dns-management-for-gitops-31239ea75d8d) 325 * Run external-dns on GKE with workload identity. See [Kubernetes, ingress-nginx, cert-manager & external-dns](https://blog.atomist.com/kubernetes-ingress-nginx-cert-manager-external-dns/) 326 * [ExternalDNS integration with Azure DNS using workload identity](https://cloudchronicles.blog/blog/ExternalDNS-integration-with-Azure-DNS-using-workload-identity/)