Kubernetes cluster

you mean capitalization?

As per the style guide, let's try to avoid latin terms such as i.e. :) Maybe you can use 'such as' instead (felt it's more appropriate than 'that is' in this context)?

Aw, but I like id est! :-)

Sure. Updating to capitalize now and removing id est.

"that each is talking to a trusted " -> Seems to be missing a word..
Did you mean the following: "that each cluster is talking to a trusted"

Yeah, will fix that too. Updated commit coming momentarily.

new commit out. I didn't squash them to make it easier for you to see changes.

Suggestion: Made a few minor tweaks

"The normal process of bootstrappinng these components, especially worker nodes that need certificates so they can communicate safely with kube-apiserver, can be a challenging process as it is often outside of the scope of Kubernetes and require significant additional work. This in turn, can make it challenging to initialize or scale a cluster."

Updated. Also cleaned up some minor typo and grammatical/syntactical issues.

the system:bootstrappers group is not a requirement... CSR creation permissions can be granted to any user or group. we don't want to encourage someone using an alternate auth method to include a system:bootstrappers group just because of this statement.

We need to make it clear in this doc when we are using a specific group (like system:bootstrappers) as a fixed example for the particular flow this document is walking you through, and when we are stating a requirement that any authentication method they chose to use must conform to.

Instead, focus on the authorization requirements (authorized to create the CSR, and authorized for approval)

We can do that. I get what you are saying, but I do think this makes it far easier to understand. Rather than, "you must set up a role with the right permissions and a group and... ", it is easier for people to understand, "make sure your user authenticates as system:bootstrappers and this all will work."

Maybe something like:

Whichever method you choose, the requirement is that the kubelet be able to authenticate as a user who has the right to create and get CSRs. You can create such a group or user on your own. In the interest of standardization and simplicity, Kubernetes ships with bootstrap tokens authenticating to the `system:bootstrappers` group, which we strongly recommend you simply adopt.

typo, default role is system:node-bootstrapper (applies below as well)

Doh!

nit: nesting is odd, should all these sections drop a #?

Yeah, it is. Maybe tidy up with the next one.

In the title, clarify the section applies to 1.8+

Sure.

@kubernetes/sig-docs-en-reviews how many releases do we maintain legacy info like this on the website? current supported versions are 1.10+. Do we have a way to link to archived 1.8-era docs instead of including all this legacy info in a current docs page?

if we do end up needing to include this section, I would make it additive over the 1.8+ section and just include the role definitions for the missing system:certificates.k8s.io:certificatesigningrequests:nodeclient and system:certificates.k8s.io:certificatesigningrequests:selfnodeclient cluster roles.

I didn't understand this. Are you saying we should just say, "if you are running Kube <1.8, add the following roles..."? Can you create the system:* roles? I never have tried, always treating it as "privileged".

Yes. They're just roles

to renew its own client certificate

Good point.

to provide the bootstrap credentials ... don't imply the bootstrap credential must be a token

Fair.

note here that any valid authentication method can be used, not just tokens

👍

this list is confusing in combination with the section below... I would include a third option: * request serving certificates from the cluster signer, via the CSR API

Yeah, I struggled with a way to make this clear, and finally decided, let's get one in to capture the data and then improve it iteratively.

I would not include kube-proxy in this page.

This is the only one on which I beg to differ.

I get that the intent of this page was to document how Kubelet bootstrapping works. But from an end-user perspective, someone coming to this page views it as, "oh look! A page describing how to bootstrap TLS for my workers!" The fact that kube-proxy is technically a separate component is immaterial (and confusing) to the end-user (speaking from experience here... :-) ).

My opinion, anyways, but my perspective, despite a few years of running kube in anger and digging into its myriad components, remains one of "components shmomponents, I only care about the end-use case."

A few thoughts:

• kube-proxy is one of many things that can run on nodes... calling it out specifically here makes it seem more special than it is.
• I don't think we should advocate pointing kube-proxy at kubelet credentials on disk. cc @mikedanese, xref Clients using kubeconfigs that load certificates from disk should reload credentials on rotation kubernetes#70958 Guidelines for node-level plugin auth kubernetes#62747

kube-proxy is one of many things that can run on nodes... calling it out specifically here makes it seem more special than it is.

If I look at the docs for installing kube, at a minimum, each node will have:

• container runtime (historically docker, although that can be anything with CRI, but it must exist). Either way, this does not have to authenticate to the master plane, since it is controlled by kubelet
• kubelet - covered by this doc
• kube-proxy - subject of this discussion

(do you know how many times I had to edit this because of the damn MacBook Pro keyboard? What really bad hardware engineering...)

kube-proxy is required to do things correctly, it is part of the core control plane, and the docs tell me, "install container runtime, kubelet, kube-proxy."

Doesn't that make it special? What else might I run on a node that would make it a worker and is part of the control plane?

BTW, not trying to make a point "just because"; this really is how many of us users see it.

What else might I run on a node that would make it a worker and is part of the control plane?

A network plugin that requires speaking to the API server comes to mind. If we want a section that describes approaches for running other things on the node, and kube-proxy is given as an example, that seems more reasonable. The two approaches I would highlight would be to manually provision and provide credentials, or to run as a daemonset.

Would a network plugin be part of the official control plane?

If we want a section that describes approaches for running other things on the node, and kube-proxy is given as an example, that seems more reasonable.

Yeah, that works. Just mildly different from this one anyways. :-)

The two approaches I would highlight would be to manually provision and provide credentials, or to run as a daemonset.

In other words, get rid of the "shared credential" approach?

Let's move this all to the other open PR.

prefer referencing the issue filed for this behavior (kubernetes/kubernetes#68686) over a specific pull request

Sure.