search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.37k stars 14.15k forks source link

Unclear wording in “DNS for Services and Pods” page #44178

Open aceeric opened 7 months ago

aceeric commented 7 months ago

This is a suggestion regarding: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy

Specifically (emphasis added):

"Default": The Pod inherits the name resolution configuration from the node that the Pods run on

This is a truly minor observation that recognizes that the word "node" is often used to refer to a machine (either bare metal or virtualized) in a clustered (i.e. networked) enviroment.

A node is a also Kubernetes abstraction. I think what the documentation is saying is that The Pod inherits the name resolution configuration from the underlying host that the Pods run on. In other words, when you're trying to understand DNS for the first time, the language leads you to believe that the Kubernetes node knows something about name resolution which I don't think is correct. If I am right, then it seems clearer to avoid the overloaded term node here.

There could be a convention in the k8s docs that lower node refers to host and upper Node refers to the Kubernetes abstraction but I don't see that used in the docs...

k8s-ci-robot commented 7 months ago

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
sftim commented 7 months ago

There could be a convention in the k8s docs that lower node refers to host and upper Node refers to the Kubernetes abstraction

Yes, there is.

sftim commented 7 months ago

/language en

sftim commented 7 months ago

(A Node is an API object representing a node)

aceeric commented 7 months ago

Respectfully - here is a good example that illustrates interchangeable use of lower "node" and upper "Node" to refer to only the Kubernetes Node abstraction. But anyway that's not the point. The point is the existing docs seem to indicate that the Kubernetes Node conveys something about DNS to the Pod which - I don't think it does. Hence, it seems more accurate to say the Pod inherits the name resolution configuration from the underlying host that the Pods run on, which was the main point of the issue.

sftim commented 7 months ago

My opinion: we need a way to help readers know that, within Kubernetes docs, “node” means what @aceeric is using ”underlying host” to mean. If the node is a VM then we do not mean the DNS resolver configuration comes from the physical server that is providing virtualization.

I'm not keen on the proposed switch to “underlying host”, though.

The whole entry:

"Default": The Pod inherits the name resolution configuration from the node that the Pods run on. See related discussion for more details.

is misleading in a few ways, as is https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/

A more thorough review and revision would be ideal.

sftim commented 7 months ago

/retitle Unclear wording in “DNS for Services and Pods” page

k8s-triage-robot commented 4 months ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

vaibhav2107 commented 4 months ago

/remove-lifecycle stale

k8s-triage-robot commented 1 month ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 2 weeks ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten