From 5ead4bf8e8668543ec1835b01aa022469eff0761 Mon Sep 17 00:00:00 2001
From: Geoffrey Cline <gcline@amazon.com>
Date: Fri, 5 Feb 2021 23:25:02 +0000
Subject: [PATCH] revise docs for service DNS

---
 .../services-networking/dns-pod-service.md    | 52 ++++++++++++++-----
 .../dns-debugging-resolution.md               | 27 ++++++++++
 2 files changed, 67 insertions(+), 12 deletions(-)

diff --git a/content/en/docs/concepts/services-networking/dns-pod-service.md b/content/en/docs/concepts/services-networking/dns-pod-service.md
index f02aede0e1..2888064c2e 100644
--- a/content/en/docs/concepts/services-networking/dns-pod-service.md
+++ b/content/en/docs/concepts/services-networking/dns-pod-service.md
@@ -7,8 +7,8 @@ content_type: concept
 weight: 20
 ---
 <!-- overview -->
-This page provides an overview of DNS support by Kubernetes.
-
+Kubernetes creates DNS records for services and pods. You can contact
+services with consistent DNS names instead of IP addresses. 
 
 <!-- body -->
 
@@ -18,19 +18,47 @@ Kubernetes DNS schedules a DNS Pod and Service on the cluster, and configures
 the kubelets to tell individual containers to use the DNS Service's IP to
 resolve DNS names.
 
-### What things get DNS names?
-
 Every Service defined in the cluster (including the DNS server itself) is
-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:
+assigned a DNS name. By default, a client Pod's DNS search list includes the 
+Pod's own namespace and the cluster's default domain. 
 
-Assume a Service named `foo` in the Kubernetes namespace `bar`. A Pod running
-in namespace `bar` can look up this service by querying a DNS service for
-`foo`. A Pod running in namespace `quux` can look up this service by doing a
-DNS query for `foo.bar`.
+### Namespaces of Services 
 
-The following sections detail the supported record types and layout that is
+A DNS query may return different results based on the namespace of the pod making 
+it. DNS queries that don't specify a namespace are limited to the pod's 
+namespace. Access services in other namespaces by specifying it in the DNS query. 
+
+For example, consider a pod in a `test` namespace. A `data` service is in 
+the `prod` namespace. 
+
+A query for `data` returns no results, because it uses the pod's `test` namespace. 
+
+A query for `data.prod` returns the intended result, because it specifies the 
+namespace. 
+
+DNS queries may be expanded using the pod's `/etc/resolv.conf`. Kubelet 
+sets this file for each pod. For example, a query for just `data` may be 
+expanded to `data.test.cluster.local`. The values of the `search` option 
+are used to expand queries. To learn more about DNS queries, see 
+[the `resolv.conf` manual page.](https://www.man7.org/linux/man-pages/man5/resolv.conf.5.html) 
+
+```
+nameserver 10.32.0.10
+search <namespace>.svc.cluster.local svc.cluster.local cluster.local
+options ndots:5
+```
+
+In summary, a pod in the _test_ namespace can successfully resolve either 
+`data.prod` or `data.prod.cluster.local`.
+
+### DNS Records
+
+What objects get DNS records?
+
+1. Services
+2. Pods
+
+The following sections detail the supported DNS record types and layout that is
 supported.  Any other layout or names or queries that happen to work are
 considered implementation details and are subject to change without warning.
 For more up-to-date specification, see
diff --git a/content/en/docs/tasks/administer-cluster/dns-debugging-resolution.md b/content/en/docs/tasks/administer-cluster/dns-debugging-resolution.md
index 8680abad43..faed4e1cb1 100644
--- a/content/en/docs/tasks/administer-cluster/dns-debugging-resolution.md
+++ b/content/en/docs/tasks/administer-cluster/dns-debugging-resolution.md
@@ -25,6 +25,12 @@ kube-dns.
 
 {{< codenew file="admin/dns/dnsutils.yaml" >}}
 
+{{< note >}}
+This example creates a pod in the `default` namespace. DNS name resolution for 
+services depends on the namespace of the pod. For more information, review
+[DNS for Services and Pods](/docs/concepts/services-networking/dns-pod-service/#what-things-get-dns-names). 
+{{< /note >}}
+
 Use that manifest to create a Pod:
 
 ```shell
@@ -247,6 +253,27 @@ linux/amd64, go1.10.3, 2e322f6
 172.17.0.18:41675 - [07/Sep/2018:15:29:11 +0000] 59925 "A IN kubernetes.default.svc.cluster.local. udp 54 false 512" NOERROR qr,aa,rd,ra 106 0.000066649s
 ```
 
+### Are you in the right namespace for the service?
+
+DNS queries that don't specify a namespace are limited to the pod's 
+namespace. 
+
+If the namespace of the pod and service differ, the DNS query must include 
+the namespace of the service.
+
+This query is limited to the pod's namespace:
+```shell
+kubectl exec -i -t dnsutils -- nslookup <service-name>
+```
+
+This query specifies the namespace:
+```shell
+kubectl exec -i -t dnsutils -- nslookup <service-name>.<namespace>
+```
+
+To learn more about name resolution, see 
+[DNS for Services and Pods](/docs/concepts/services-networking/dns-pod-service/#what-things-get-dns-names). 
+
 ## Known issues
 
 Some Linux distributions (e.g. Ubuntu) use a local DNS resolver by default (systemd-resolved).