diff --git a/docs/legacy/kops-dns-controller.md b/docs/legacy/kops-dns-controller.md deleted file mode 100644 index 45fc7e12f..000000000 --- a/docs/legacy/kops-dns-controller.md +++ /dev/null @@ -1,84 +0,0 @@ -# Kops dns-controller annotations - -Kops includes a dns-controller, and this document describes the existing annotations and their behaviour. This -document is intended to allow us to see the use-cases identified by kops dns-controller, to ensure the same annotations -can be recognized (perhaps with a `--compatibilty` flag), and to ensure that we have comparable functionality. - -## Flags - -* `--dns`: `aws-route53,google-clouddns` - -The DNS flag lets us choose which DNS provider to use. - -* `--watch-ingress` boolean - -Turns ingress functionality on and off. For AWS at least, we are blocked on switching to a release -from the `kubernetes/ingress` project (instead of one from the `contrib` project). - -* `--zones` configures permitted zones, and also disambiguates when domain names are duplicated. It is a list that matches zones we are allowed to match. - - - `*` and `*/*` are wildcard, and match all zones - - - `example.com` matches zones with name=`example.com` - - - `example.com/1234` matches zones with id=`1234` and name=`example.com`. This is useful to disambiguate between -multiple zones named `example.com`. - - - `*/1234` matches the zone with id=`1234`. A zone has a unique name, so this is equivalent to `example.com/1234`, -but a little shorter - and less self-documenting! - -* Standard glog flags (--v, --logtostderr etc) - -* Standard kubectl_util client flags - - -## Annotations - -We define 2 primary annotations: - -* `dns.alpha.kubernetes.io/external` which is used to define a DNS record for accessing the resource publicly (i.e. public IPs) - -* `dns.alpha.kubernetes.io/internal` which is used to define a DNS record for accessing the resource from outside the cluster but inside the cloud, -i.e. it will typically use internal IPs for instances. - -These annotations may both be comma-separated lists of names. - -On a node, we also have a WIP annotation `dns.alpha.kubernetes.io/external-ip`, which configures the external ip -for a node (to work around [#42125](https://github.com/kubernetes/kubernetes/issues/42125)). That is an annotation -that lets us defined the equivalent of an address with type ExternalIP. - -## DNS record mappings - -The DNS record mappings try to "do the right thing", but what this means is different for each resource type. - -### Ingress - -We consult the `Status.LoadBalancer.Ingress` records on the ingress. For each one, we create a record. -If the record is an IP address, we add an A record. If the record is a hostname (AWS ELB), we use a CNAME. - -We would like to use an ALIAS, but we have not yet done this because of limitations of the DNS provider. - -### Pods - -For the external annotation, we will map a HostNetwork=true pod to the external IPs of the node. We create an A record. - -For the internal annotation, we will map a HostNetwork=true pod to the internal IPs of the node. We create an A record. - -We ignore pods that are not HostNetwork=true - -### Services - -* For a Service of Type=LoadBalancer, we look at Status.LoadBalancer.Ingress. We create CNAMEs to hostnames, - and A records for IP addresses. (We should create ALIASes for ELBs). We do this for both internal & external - names - there is no difference on GCE or AWS. - -* For a Service of Type=NodePort, we create A records for the node's internal/external IP addresses, as appropriate. - -(A canonical use for NodePort internal is having a prometheus server running inside EC2 monitoring your kubernetes cluster, -for NodePort external is to expose your service without an ELB). - - -### Nodes - -(We don't currently support annotations on the nodes themselves. We do set up internal "alias" records, -which is how we do JOINs for e.g. NodePort services) diff --git a/docs/tutorials/kops-dns-controller.md b/docs/tutorials/kops-dns-controller.md new file mode 100644 index 000000000..04da968bf --- /dev/null +++ b/docs/tutorials/kops-dns-controller.md @@ -0,0 +1,37 @@ +# kOps dns-controller compatibility mode + +kOps includes a dns-controller that is primarily used to bootstrap the cluster, but can also be used for provisioning DNS entries for Services and Ingress. + +ExternalDNS can be used as a drop-in replacement for dns-controller if you are running a non-gossip cluster. The flag `--compatibility kops-dns-controller` enables the dns-controller behaviour. + +## Annotations + +In kops-dns-controller compatibility mode, ExternalDNS supports two additional annotations: + +* `dns.alpha.kubernetes.io/external` which is used to define a DNS record for accessing the resource publicly (i.e. public IPs) + +* `dns.alpha.kubernetes.io/internal` which is used to define a DNS record for accessing the resource from outside the cluster but inside the cloud, +i.e. it will typically use internal IPs for instances. + +These annotations may both be comma-separated lists of names. + +## DNS record mappings + +The DNS record mappings try to "do the right thing", but what this means is different for each resource type. + +### Pods + +For the external annotation, ExternalDNS will map a HostNetwork=true Pod to the external IPs of the Node. + +For the internal annotation, ExternalDNS will map a HostNetwork=true Pod to the internal IPs of the Node. + +ExternalDNS ignore Pods that are not HostNetwork=true + +Annotations added to Pods will always result in an A record being created. + +### Services + +* For a Service of Type=LoadBalancer, ExternalDNS looks at Status.LoadBalancer.Ingress. It will create CNAMEs to hostnames, + and A records for IP addresses. It will do this for both internal and external names + +* For a Service of Type=NodePort, ExternalDNS will create A records for the Node's internal/external IP addresses, as appropriate. \ No newline at end of file