From 2367360321ee312aff4de0003740a0847bdf9a23 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Wed, 14 Jan 2015 21:54:04 -0800 Subject: [PATCH] Update DNS doc --- cluster/addons/dns/README.md | 7 ++-- docs/dns.md | 75 +++++++++++++++--------------------- 2 files changed, 34 insertions(+), 48 deletions(-) diff --git a/cluster/addons/dns/README.md b/cluster/addons/dns/README.md index 792f3ce688a..cf2c14630a7 100644 --- a/cluster/addons/dns/README.md +++ b/cluster/addons/dns/README.md @@ -47,7 +47,6 @@ between Kubernetes and SkyDNS. It finds the Kubernetes master through the that to etcd for SkyDNS to find. ## Known issues -DNS resolution does not work from nodes directly, but it DOES work for -containers. As best I (thockin) can figure out, this is some oddity around DNAT and -localhost in the kernel. I think I have a workaround, but it's not quite baked -as of the this writing (11/6/2014). +Kubernetes installs do not configure the nodes' resolv.conf files to use the +cluster DNS by default, because that process is inherently distro-specific. +This should probably be implemented eventually. diff --git a/docs/dns.md b/docs/dns.md index 542cba8602b..145e4691dda 100644 --- a/docs/dns.md +++ b/docs/dns.md @@ -1,51 +1,38 @@ -# DNS Integration with SkyDNS -Since Kubernetes services changed to assign a single IP address to each service, it is -now possible to use DNS to resolve a DNS name directly to a Kubernetes service, which -would then use Kubernetes' proxy to connect to an appropriate pod running the application -pointed to by the service definition. +# DNS Integration with Kubernetes + +As of kubernetes 0.8, DNS is offered as a cluster add-on. If enabled, a DNS +Pod and Service will be scheduled on the cluster, and the kubelets will be +configured to tell individual containers to use the DNS Service's IP. + +Every Service defined in the cluster (including the DNS server itself) will be +assigned a DNS name. By default, a client Pod's DNS search list will +include the Pod's own namespace and the cluster's default domain. This is best +illustrated by example: + +Assume a Service named `foo` in the kubernetes namespace `bar`. A Pod running +in namespace `bar` can look up this service by simply doing a DNS query for +`foo`. A Pod running in namespace `quux` can look up this service by doing a +DNS query for `foo.bar`. + +The cluster DNS server ([SkyDNS](https://github.com/skynetservices/skydns)) +supports forward lookups (A records) and service lookups (SRV records). ## How it Works -Version 2.0.1a of [SkyDNS](https://github.com/skynetservices/skydns) added a change that -allows it to poll the Kubernetes API looking for changes to the service definitions. Newly -added services are published in SkyDNS, and removed services are deleted from SkyDNS's -internal registry. -### Concrete Example -If you run the Guestbook example in the Kubernetes repository, you'll end up with a service -called `redismaster`. If you were also running SkyDNS with the `-kubernetes=true` flag and -`-master=http://my.kubernetes.master:8080` you would immediately be able to run queries against -the SkyDNS server for the `redismaster` service. By default, SkyDNS is authoratative for the -domain `skydns.local`, so a query to the SkyDNS server requesting redismaster.skydns.local will -return the IP Address of the `redismaster` service. +The DNS pod that runs holds 3 containers - skydns, etcd (which skydns uses), +and a kubernetes-to-skydns bridge called kube2sky. The kube2sky process +watches the kubernetes master for changes in Services, and then writes the +information to etcd, which skydns reads. This etcd instance is not linked to +any other etcd clusters that might exist, including the kubernetes master. -## Configuration -SkyDNS allows you to change the domain name that it will resolve by passing in a domain on the -command line using `-domain=mydomain.com` or by setting an environment variable `SKYDNS_DOMAIN`. +## Issues -If you change the Docker daemon on your Kubernetes minions to use SkyDNS for domain name resolution, -your pods will all be able to connect to services via DNS instead of using environment variables -or other configuration methods. To change Docker to use SkyDNS resolution, add `--dns=ip.of.skydns.server` -to the Docker startup command. -``` -docker -d --dns=10.2.0.5 ... -``` +The skydns service is reachable directly from kubernetes nodes (outside +of any container) and DNS resolution works if the skydns service is targetted +explicitly. However, nodes are not configured to use the cluster DNS service or +to search the cluster's DNS domain by default. This may be resolved at a later +time. -SkyDNS uses the etcd instance in Kubernetes as its storage backend, which means that you can run -multiple SkyDNS daemons if you wish to have more than one resolver on your cluster. You could run -a SkyDNS instance on each node in your Kubernetes cluster, and set Docker to use 127.0.0.1 as the -DNS resolver. +## For more information -## Starting SkyDNS in a Kubernetes Cluster -At a minimum, you need to provide the `-kubernetes` flag, and the `-master=http://my.kubernetes.master.ip:8080` -flag when you start SkyDNS. You may also wish to use `-domain=mydomain.com` to change the domain that -SkyDNS resolves. - -SkyDNS can act as your external resolver, too. If you set your domain to use the external IP address of -the server running SkyDNS and bind SkyDNS to listen on all interfaces, SkyDNS will serve DNS for -your domain. You could then use a mixture of manually created hosts in SkyDNS and Kubernetes service -resolution to serve your various DNS endpoints. A simple example might be to run a Wordpress pod in Kubernetes -and create a service called `blog` in Kubernetes. Then external DNS requests to `blog.mydomain.com` will -automatically resolve to the service proxy and be forwarded to the pods running Wordpress. - -Full documentation of the SkyDNS server is in the [SkyDNS repository](https://github.com/skynetservices/skydns) -and abbreviated information is available by typing `skydns --help`. +See [the docs for the cluster addon](cluster/addons/dns/README.md).