mirror of
https://github.com/kubernetes-sigs/external-dns.git
synced 2025-08-06 01:26:59 +02:00
Update docs to latest changes (#563)
* Minor changes to docs and faq * Other minor changes * better docs * Addressed comments
This commit is contained in:
Raffaele Di Fazio
Henning Jacobs
parent
c18c1c79ec
commit
a104993630
@ -35,7 +35,7 @@ ExternalDNS' current release is `v0.5`. This version allows you to keep selected
|
||||
* [OpenStack Designate](https://docs.openstack.org/designate/latest/)
|
||||
* [PowerDNS](https://www.powerdns.com/)
|
||||
|
||||
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.5` 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.
|
||||
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.5` (or greater) 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
|
||||
|
||||
37
docs/faq.md
37
docs/faq.md
@ -1,6 +1,6 @@
|
||||
# Frequently asked questions
|
||||
|
||||
### When would ExternalDNS become useful to me?
|
||||
### How is ExternalDNS useful to me?
|
||||
|
||||
You've probably created many deployments. Typically, you expose your deployment to the Internet by creating a Service with `type=LoadBalancer`. Depending on your environment, this usually assigns a random publicly available endpoint to your service that you can access from anywhere in the world. On Google Container Engine, this is a public IP address:
|
||||
|
||||
@ -28,17 +28,26 @@ ExternalDNS can solve this for you as well.
|
||||
|
||||
### Which DNS providers are supported?
|
||||
|
||||
So far, Google CloudDNS and AWS Route 53 with ALIAS records. There's interest in supporting CoreDNS and Azure DNS. We're open to discussing/adding other providers if the community believes it would be valuable.
|
||||
Currently, the following providers are supported:
|
||||
|
||||
Initial support for Google CloudDNS is available since the `v0.1` release. Initial support for AWS Route 53 is available in the `v0.2` release (CNAME based) and ALIAS is targeted for the `v0.3` release.
|
||||
- Google CloudDNS
|
||||
- AWS Route 53
|
||||
- AzureDNS
|
||||
- CloudFlare
|
||||
- DigitalOcean
|
||||
- DNSimple
|
||||
- Infoblox
|
||||
- Dyn
|
||||
- OpenStack Designate
|
||||
- PowerDNS
|
||||
|
||||
There are no plans regarding other providers at the moment.
|
||||
As stated in the README, we are currently looking for stable maintainers for those providers, to ensure that bugfixes and new features will be available for all of those.
|
||||
|
||||
### Which Kubernetes objects are supported?
|
||||
|
||||
Services exposed via `type=LoadBalancer` and for the hostnames defined in Ingress objects. It also seems useful to expose Services with `type=NodePort` to point to your cluster's nodes directly, but there's no commitment to doing this yet.
|
||||
Services exposed via `type=LoadBalancer` and for the hostnames defined in Ingress objects as well as headless hostPort services. An initial effort to support type `NodePort` was started as of May 2018 and it is in progress at the time of writing.
|
||||
|
||||
### How do I specify DNS name for my Kubernetes objects?
|
||||
### How do I specify a DNS name for my Kubernetes objects?
|
||||
|
||||
There are three sources of information for ExternalDNS to decide on DNS name. ExternalDNS will pick one in order as listed below:
|
||||
|
||||
@ -50,7 +59,7 @@ There are three sources of information for ExternalDNS to decide on DNS name. Ex
|
||||
|
||||
### Can I specify multiple global FQDN templates?
|
||||
|
||||
Yes, yes you can. Pass in a comma separated list to `--fqdn-template`. Beaware this will double (triple, etc) the amount of DNS entries based on how many services, ingresses and so on you have and will get you faster towards the API request limit of your DNS provider.
|
||||
Yes, you can. Pass in a comma separated list to `--fqdn-template`. Beaware this will double (triple, etc) the amount of DNS entries based on how many services, ingresses and so on you have and will get you faster towards the API request limit of your DNS provider.
|
||||
|
||||
### Which Service and Ingress controllers are supported?
|
||||
|
||||
@ -65,11 +74,11 @@ Regarding Ingress, we'll support:
|
||||
|
||||
For Ingress objects, ExternalDNS will attempt to discover the target hostname of the relevant Ingress Controller automatically. If you are using an Ingress Controller that is not listed above you may have issues with ExternalDNS not discovering Endpoints and consequently not creating any DNS records. As a workaround, it is possible to force create an Endpoint by manually specifying a target host/IP for the records to be created by setting the annotation `external-dns.alpha.kubernetes.io/target` in the Ingress object.
|
||||
|
||||
Another reason you may want to override the ingress hostname or IP address is if you have an external mechanism for handling failover across ingress endpoints. Possible scenarios for this would include using [keepalived-vip](https://github.com/kubernetes/contrib/tree/master/keepalived-vip) to manage failover faster than DNS TTLs might expire.
|
||||
Another reason you may want to override the ingress hostname or IP address is if you have an external mechanism for handling failover across ingress endpoints. Possible scenarios for this would include using [keepalived-vip](https://github.com/kubernetes/contrib/tree/master/keepalived-vip) to manage failover faster than DNS TTLs might expire.
|
||||
|
||||
Note that if you set the target to a hostname, then a CNAME record will be created. In this case, the hostname specified in the Ingress object's annotation must already exist. (i.e.: You have a Service resource for your Ingress Controller with the `external-dns.alpha.kubernetes.io/hostname` annotation set to the same value.)
|
||||
Note that if you set the target to a hostname, then a CNAME record will be created. In this case, the hostname specified in the Ingress object's annotation must already exist. (i.e. you have a Service resource for your Ingress Controller with the `external-dns.alpha.kubernetes.io/hostname` annotation set to the same value.)
|
||||
|
||||
### What about those other projects?
|
||||
### What about other projects similar to ExternalDNS?
|
||||
|
||||
ExternalDNS is a joint effort to unify different projects accomplishing the same goals, namely:
|
||||
|
||||
@ -91,11 +100,11 @@ For now ExternalDNS uses TXT records to label owned records, and there might be
|
||||
|
||||
### Does anyone use ExternalDNS in production?
|
||||
|
||||
Yes — Zalando replaced [Mate](https://github.com/linki/mate) with ExternalDNS since its v0.3 release, which now runs in production-level clusters. We are planning to document a step-by-step tutorial on how the switch from Mate to ExternalDNS has occurred.
|
||||
Yes, multiple companies are using ExternalDNS in production. Zalando, as an example, has been using it in production since its v0.3 release, mostly using the AWS provider.
|
||||
|
||||
### How can we start using ExternalDNS?
|
||||
|
||||
Check out the following descriptive tutorials on how to run ExternalDNS in [GKE](tutorials/gke.md) and [AWS](tutorials/aws.md).
|
||||
Check out the following descriptive tutorials on how to run ExternalDNS in [GKE](tutorials/gke.md) and [AWS](tutorials/aws.md) or any other supported provider.
|
||||
|
||||
### Why is ExternalDNS only adding a single IP address in Route 53 on AWS when using the `nginx-ingress-controller`? How do I get it to use the FQDN of the ELB assigned to my `nginx-ingress-controller` Service instead?
|
||||
|
||||
@ -135,11 +144,11 @@ spec:
|
||||
|
||||
### I have a Service/Ingress but it's ignored by ExternalDNS. Why?
|
||||
|
||||
TODO (https://github.com/kubernetes-incubator/external-dns/issues/267)
|
||||
ExternalDNS can be configured to only use Services or Ingresses as source. In case Services or Ingresses seem to be ignored in your setup, consider checking how the flag `--source` was configured when deployed. For reference, see the issue https://github.com/kubernetes-incubator/external-dns/issues/267.
|
||||
|
||||
### I'm using an ELB with TXT registry but the CNAME record clashes with the TXT record. How to avoid this?
|
||||
|
||||
TODO (https://github.com/kubernetes-incubator/external-dns/issues/262)
|
||||
CNAMEs cannot co-exist with other records, therefore you can use the `--txt-prefix` flag which makes sure to create a TXT record with a name following the pattern `prefix.<CNAME record>`. For reference, see the issue https://github.com/kubernetes-incubator/external-dns/issues/262.
|
||||
|
||||
### Which permissions do I need when running ExternalDNS on a GCE or GKE node.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
|
||||
[Initial discussion](https://docs.google.com/document/d/1ML_q3OppUtQKXan6Q42xIq2jelSoIivuXI8zExbc6ec/edit#heading=h.1pgkuagjhm4p)
|
||||
|
||||
This document describes the initial design proposal
|
||||
This document describes the initial design proposal.
|
||||
|
||||
External DNS is purposed to fill the existing gap of creating DNS records for Kubernetes resources. While there exist alternative solutions, this project is meant to be a standard way of managing DNS records for Kubernetes. The current project is a fusion of the following projects and driven by its maintainers:
|
||||
|
||||
@ -41,8 +41,6 @@ DNS records will be automatically created in multiple situations:
|
||||
|
||||
### Annotations
|
||||
|
||||
TODO:*This should probably be placed in a separate file*.
|
||||
|
||||
Record configuration should occur via resource annotations. Supported annotations:
|
||||
|
||||
| Annotations | |
|
||||
@ -63,8 +61,6 @@ Record configuration should occur via resource annotations. Supported annotation
|
||||
|
||||
External DNS should be compatible with annotations used by three above mentioned projects. The idea is that resources created and tagged with annotations for other projects should continue to be valid and now managed by External DNS.
|
||||
|
||||
TODO:*Add complete list here*
|
||||
|
||||
**Mate**
|
||||
|
||||
Mate does not require services/ingress to be tagged. Therefore, it is not safe to run both Mate and External-DNS simultaneously. The idea is that initial release (?) of External DNS will support Mate annotations, which indicates the hostname to be created. Therefore the switch should be simple.
|
||||
|
||||
@ -31,7 +31,7 @@ This tutorial describes how to setup ExternalDNS for usage within a Kubernetes c
|
||||
}
|
||||
```
|
||||
|
||||
When running on AWS, you need to make sure that your nodes (on which External DNS runs) have the IAM instance profile with the above IAM role assigned (either directly or via something like `kube2iam`).
|
||||
When running on AWS, you need to make sure that your nodes (on which External DNS runs) have the IAM instance profile with the above IAM role assigned (either directly or via something like [kube2iam](https://github.com/jtblin/kube2iam)).
|
||||
|
||||
## Set up a hosted zone
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user