Improve documentation for using Node-local DNS Cache add-on #17944

sftim · 2019-12-04T18:42:17Z

The Node-local DNS Cache is a very simple add-on, essentially one DaemonSet and a related ConfigMap.

I haven't used tried using this feature but I did spot that the existing documentation was a bit far from the style guide, so I'm proposing these changes.
I think there's more work needed (what fills in the missing information? what are appropriate values? is link-local autoconfiguration the risk I think it is?); I'm aiming for these changes to be a first set of improvements.
Preview of new page

Reviewers: I've seen various names and capitalizations for this add-on. For documentation, I selected the name “Node-local DNS Cache” because it avoids the risk of looking like a Kubernetes feature flag or object. I don't want readers trying to kubectl get NodeLocalDNSCache, or even having to make a decision on whether that makes sense.

Relevant to #14822
/sig network

sftim · 2019-12-04T18:43:34Z

content/en/docs/tasks/administer-cluster/nodelocaldns.md

+In detail:

-* With the current DNS architecture, it is possible that Pods with the highest DNS QPS have to reach out to a different node, if there is no local kube-dns/CoreDNS instance.  
-Having a local cache will help improve the latency in such scenarios.
+* With the current DNS architecture, it is possible that Pods with the
+  highest DNS QPS have to reach out to a different node, if there is no
+  local kube-dns / CoreDNS instance.
+  Having a local cache help improve the latency in such scenarios.

-* Skipping iptables DNAT and connection tracking will help reduce [conntrack races](https://github.com/kubernetes/kubernetes/issues/56903) and avoid UDP DNS entries filling up conntrack table.
+* Skipping iptables DNAT and connection tracking helps to reduce [conntrack races](https://github.com/kubernetes/kubernetes/issues/56903) and to avoid UDP DNS entries filling up conntrack table.

-* Connections from local caching agent to kube-dns servie can be upgraded to TCP. TCP conntrack entries will be removed on connection close in contrast with UDP entries that have to timeout ([default](https://www.kernel.org/doc/Documentation/networking/nf_conntrack-sysctl.txt) `nf_conntrack_udp_timeout` is 30 seconds)
+* Connections from local caching agent to kube-dns servie can be upgraded to TCP. TCP conntrack entries will be removed on connection close in contrast with UDP entries that have to time out ([default](https://www.kernel.org/doc/Documentation/networking/nf_conntrack-sysctl.txt) `nf_conntrack_udp_timeout` is 30 seconds)

-* Upgrading DNS queries from UDP to TCP would reduce tail latency attributed to dropped UDP packets and DNS timeouts usually up to 30s (3 retries + 10s timeout). Since the nodelocal cache listens for UDP DNS queries, applications don't need to be changed.
+* Upgrading DNS queries from UDP to TCP would reduce tail latency attributed to dropped UDP packets and DNS timeouts usually up to 30s (3 retries + 10s timeout). Since the node-local cache container listens for UDP DNS queries, you don't need to change applications.

 * Metrics & visibility into dns requests at a node level.

-* Negative caching can be re-enabled, thereby reducing number of queries to kube-dns service.
-
-## Architecture Diagram
+* Negative caching can be re-enabled, thereby reducing number of queries to the kube-dns service.

-This is the path followed by DNS Queries after NodeLocal DNSCache is enabled:


As this is a Task page I'm tempted to omit these details, or to move them to the end of the page. What do people think?

sftim · 2019-12-04T18:44:12Z

content/en/docs/tasks/administer-cluster/nodelocaldns.md


-{{< figure src="/images/docs/nodelocaldns.jpg" alt="NodeLocal DNSCache flow" title="Nodelocal DNSCache flow" caption="This image shows how NodeLocal DNSCache handles DNS queries." >}}
+{{< figure src="/images/docs/nodelocaldns.jpg" alt="Node-local DNS Cache query flow" title="Node-local DNS Cache query flow" caption="This image shows how Node-local DNS Cache handles DNS queries." >}}


It would be nice, but not essential, to redraw this in SVG. SVG diagrams are much more easy to localize.

sftim · 2019-12-04T18:44:47Z

content/en/docs/tasks/administer-cluster/nodelocaldns.md


 ## Configuration

-This feature can be enabled using the command:
-
-`KUBE_ENABLE_NODELOCAL_DNS=true go run hack/e2e.go -v --up`


I dropped this because the prerequisites don't explain what you need to do (eg: install Golang) to make it work.

netlify · 2019-12-04T18:51:08Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 6948e83

https://deploy-preview-17944--kubernetes-io-master-staging.netlify.com

sftim · 2019-12-16T15:12:34Z

/retest

k8s-ci-robot · 2020-01-11T18:36:14Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign sftim
You can assign the PR to them by writing /assign @sftim in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

content/en/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

kbhawkey · 2020-02-10T01:52:42Z

@sftim, Would you look into the build failure? Thanks!

1:36:29 PM: Total in 1951 ms
1:36:29 PM: Error: Error building site: "/opt/build/repo/content/en/docs/tasks/administer-cluster/nodelocaldns.md:88:6": failed to extract shortcode: shortcode "capture" has no .Inner, yet a closing tag was provided
1:36:29 PM: Function Dir: /opt/build/repo/functions
1:36:29 PM: Skipping functions preparation step: /opt/build/repo/functions not found
1:36:29 PM: Caching artifact

sftim · 2020-02-10T06:59:56Z

I'll rebase this
/retitle [WIP] Improve(?) documentation for using Node-local DNS Cache add-on

sftim · 2020-02-19T00:25:42Z

/retitle Improve documentation for using Node-local DNS Cache add-on

sftim · 2020-03-14T00:21:20Z

#18716 got there first

/close

k8s-ci-robot · 2020-03-14T00:21:22Z

@sftim: Closed this PR.

In response to this:

#18716 got there first

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

k8s-ci-robot · 2020-03-14T00:21:27Z

@sftim: PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

k8s-ci-robot requested review from bowei and Rajakavitha1 December 4, 2019 18:43

sftim commented Dec 4, 2019

View reviewed changes

sftim mentioned this pull request Dec 9, 2019

GA graduation criteria for NodeLocal DNSCache kubernetes/enhancements#1351

Merged

sftim force-pushed the 20191204_tweak_node_local_dns_addon_information branch from 4b24b52 to 3569dc7 Compare December 10, 2019 02:16

sftim force-pushed the 20191204_tweak_node_local_dns_addon_information branch from 3569dc7 to 3bb8c2c Compare January 11, 2020 18:35

k8s-ci-robot changed the title ~~Improve(?) documentation for using Node-local DNS Cache add-on~~ [WIP] Improve(?) documentation for using Node-local DNS Cache add-on Feb 10, 2020

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Feb 10, 2020

sftim force-pushed the 20191204_tweak_node_local_dns_addon_information branch 2 times, most recently from 03c4a57 to 4818d72 Compare February 19, 2020 00:19

sftim added 4 commits February 19, 2020 00:25

Reword Node-local DNS Cache add-on page

627697f

Rename concept page about Add-ons

461c985

Add Node-local DNS Cache add-on to list of add-ons

7a17d1c

Note minimum required version

6948e83

sftim force-pushed the 20191204_tweak_node_local_dns_addon_information branch from 4818d72 to 6948e83 Compare February 19, 2020 00:25

k8s-ci-robot changed the title ~~[WIP] Improve(?) documentation for using Node-local DNS Cache add-on~~ Improve documentation for using Node-local DNS Cache add-on Feb 19, 2020

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Feb 19, 2020

k8s-ci-robot closed this Mar 14, 2020

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 14, 2020

sftim deleted the 20191204_tweak_node_local_dns_addon_information branch June 9, 2021 17:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation for using Node-local DNS Cache add-on #17944

Improve documentation for using Node-local DNS Cache add-on #17944

sftim commented Dec 4, 2019 •

edited

Loading

sftim Dec 4, 2019

sftim Dec 4, 2019

sftim Dec 4, 2019

netlify bot commented Dec 4, 2019 •

edited

Loading

sftim commented Dec 16, 2019

k8s-ci-robot commented Jan 11, 2020

kbhawkey commented Feb 10, 2020

sftim commented Feb 10, 2020

sftim commented Feb 19, 2020

sftim commented Mar 14, 2020

k8s-ci-robot commented Mar 14, 2020

k8s-ci-robot commented Mar 14, 2020


		{{< figure src="/images/docs/nodelocaldns.jpg" alt="NodeLocal DNSCache flow" title="Nodelocal DNSCache flow" caption="This image shows how NodeLocal DNSCache handles DNS queries." >}}
		{{< figure src="/images/docs/nodelocaldns.jpg" alt="Node-local DNS Cache query flow" title="Node-local DNS Cache query flow" caption="This image shows how Node-local DNS Cache handles DNS queries." >}}

Improve documentation for using Node-local DNS Cache add-on #17944

Improve documentation for using Node-local DNS Cache add-on #17944

Conversation

sftim commented Dec 4, 2019 • edited Loading

sftim Dec 4, 2019

Choose a reason for hiding this comment

sftim Dec 4, 2019

Choose a reason for hiding this comment

sftim Dec 4, 2019

Choose a reason for hiding this comment

netlify bot commented Dec 4, 2019 • edited Loading

sftim commented Dec 16, 2019

k8s-ci-robot commented Jan 11, 2020

kbhawkey commented Feb 10, 2020

sftim commented Feb 10, 2020

sftim commented Feb 19, 2020

sftim commented Mar 14, 2020

k8s-ci-robot commented Mar 14, 2020

k8s-ci-robot commented Mar 14, 2020

sftim commented Dec 4, 2019 •

edited

Loading

netlify bot commented Dec 4, 2019 •

edited

Loading