Cannot find page about adding Windows nodes

[cqpr-nnit]

Everytime I try to go to https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes/ I get redirected to https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/ - Where is the guide to adding windows nodes?

[neolit123]

/sig docs windows cluster-lifecycle
/kind bug

seems like a link problem?
old page for 1.23 is here
https://v1-23.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes

[sftim]

/remove-kind bug

There is now no specific guide for creating Windows nodes (nor is there one for creating Linux nodes). SIG Windows opted to remove the guide that did exist, in PR #33324

If someone wants to write a new task page about adding a node to an existing cluster, we (SIG Docs) welcome it. That page could use tabs to cover Linux-specific vs Windows-specific details.

If the redirect is confusing, we could remove it.

/remove-sig windows
/remove-sig cluster-lifecycle

[sftim]

/retitle Cannot find page about adding Windows nodes

[ashish-jaiswar]

/assign

[ashish-jaiswar]

/unassign

[RA489]

/sig windows
/sig cluster-lifecycle

[neolit123]

There is now no specific guide for creating Windows nodes (nor is there one for creating Linux nodes). SIG Windows opted to remove the guide that did exist, in PR #33324

as discussed in the sig windows meeting yesterday, the removal of the old page with idea to have single linux / windows page might have been a bit too early. the windows setup is still quite different around cni.

we may have to have to link to external resources such as the Calico for Windows guide and tagging these parts as 'third party' at a k8s.io page.

@marosset @jsturtevant

[sftim]

A couple of things:

• We could use a tutorial or task page on adding a node to your cluster anyway. https://github.com/kelseyhightower/kubernetes-the-hard-way/blob/master/docs/09-bootstrapping-kubernetes-workers.md could be an inspiration
  I don't want something GCE-specific, but I am happy to go into more detail specifically for nodes (we've decided as a project that we won't yet host an entire KTHW-style walkthrough of setting up a working cluster with a control plane, addons, etc).
  Adding a custom node is a task that folks legitimately might want to learn independently from the rest of those steps.
  • If we had that page, we could split it into the Windows and Linux versions as these stories are pretty different.
  • we wouldn't cover much about network plugin setup, because you're adding one node to a cluster and I assume your cluster was working before you started. We'd instead list prerequisites.
• 💭 a blog article about setting up your cluster to include Windows nodes?
  • would be very welcome (especially if it focused on deploying a hybrid cluster, so we're neutral on the Pod OS)

[marosset]

There is now no specific guide for creating Windows nodes (nor is there one for creating Linux nodes). SIG Windows opted to remove the guide that did exist, in PR #33324

@sftim - IIRC SIG-Windows opted to remove this content based on some of the review comments in #32862 (review)

The way we interpreted these was pages in k/website were discouraged from providing step-by-step instructions for configuring none K8s-owned components (like CNI solutions). Did we mis-understand that?

SIG-Windows is in the process of moving a lot of the docs that got removed to https://github.com/kubernetes-sigs/sig-windows-tools/blob/master/guides/ and were hoping to link to this guide from k/website.
Our thinking here was that having these guides hosted in a k-sigs repository would have more of a community-owned feeling.

[sftim]

The way we interpreted these was pages in k/website were discouraged from providing step-by-step instructions for configuring none K8s-owned components (like CNI solutions). Did we mis-understand that?

It's OK to provide step-by-step guides, but we don't like to give details where we're picking a particular solution from the ecosystem.
For example, https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#preparing-the-hosts says that you need a compatible container runtime. What we don't say is something like:

For this example, we'll use Acme Containers.
Go to acmecontainers.com and download it, then run acmesetup.sh.
We'll walk you through configuring this interactively, but you can also do a scripted deploy…

because that's not very fair on every other CRI-compatible container runtime that we didn't pick.
Node OS, different story. We support 2 OS kernel flavors, so we can document the story for a Linux node and for a Windows node.

There'll come a point where we suggest setting up networking, and that's where ideally we send folks off to https://landscape.cncf.io/ to pick something (if we're not happy with https://landscape.cncf.io/ then the fix is to work on improvements to that site instead - it's open source IIRC).

The existing guide for setting up a Windows-compatible cluster did need work - it covered lots of detail outside the specific topic of cluster setup - and I'm glad it got looked at, but that doesn't mean we can never have a guide to deploying a Windows node. A page on that, that follows our style and content guides, would be a nice addition to this site.

Hope that's more clear.

[sftim]

If we do add a page on setting up a Windows node, this should be part of an ambition to also document adding a Linux node (in about the same detail).

[sftim]

Duplicated by #37266

[k8s-triage-robot]

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

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

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[neolit123]

this ticket has been open for ~2 years.

@sftim @marosset @jsturtevant

We have some guides here https://github.com/kubernetes-sigs/sig-windows-tools/blob/master/guides/guide-for-adding-windows-node.md and are still working on cleaning them up.

After the cleanup we can revisit linking to the guides from www.k8s.io

i think we should add a link [1] from this section to the external guide at the sig-windows-tools repo.
ALA If you are joining Windows nodes, please follow [this guide]...

this ticket can then be renamed or closed to follow this AI.
it would fall under the umbrella:

• Overhaul Windows documentation #31428

https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/ has task pages for node upgrades.

Ideally we'd have two more task pages:

1. adding a Linux node to your cluster
2. adding a Windows node to your cluster

This issue is about the second page (adding a Windows node)

if we agree, i can PR the link [1].

[sftim]

I don't like the idea of setting a precedent that we'll have GA features where we tacitly accept that they don't get documented.

In other works, I soft disagree with hyperlinking to external docs like #34476 (comment) suggests. Every other GA feature we either document appropriately or are tracking work to fix that.

If we can't staff documenting the Windows support, we should look at improving that (getting it documented), or deprecating the support. The former is the ideal way forward, but equally I can't see a push from any vendor or community members towards really improving the docs. When something has been under maintained this long, the case for deprecation grows ever stronger.
(if we did deprecate the Windows node support and that change ends up encouraging vendor or volunteer participation, we could always undeprecate it).

[sftim]

Anyway, there are compromises that don't set the problematic precedent. For example:

New suggestion:

• drop the existing redirect
• redirect to a new page explaining that the documentation for Windows node setup is incomplete, and that (if you read through it) does help people discover what's available

[sftim]

Also see #34476 (comment)

[neolit123]

i don't disagree that that proposed separate tasks pages are the way to go, it's just not clear to me how would the Windows task page look like given the tight coupling with external solutions.

In other works, I soft disagree with hyperlinking to external docs like #34476 (comment) suggests. Every other GA feature we either document appropriately or are tracking work to fix that.

the page literally branches into 3 pages with external dependencies for CNI installation:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#join-nodes

are you suggesting that the contents of the page should be in a k8s.io task but at the end of it we are still going to link to the sig-windows tools repo for CNI installation?

should we also talk about the Windows CNI story here:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#pod-network
and again, link to the sig-windows-tools guides?

[sftim]

at the end of it we are still going to link to the sig-windows tools repo for CNI installation?

That's the precedent we don't wish to set. If a SIG wants to document a feature, they should put the docs on the Kubernetes website itself.

(relevant detail: the Linux Foundation exams permit reading the docs, but don't allow following such hyperlinks)

[sftim]

If Microsoft have advice about Windows and Kubernetes, we can link to that (eg if Microsoft recommend a particular network plugin), because Microsoft clearly are the OS vendor and you need an OS in order to install Kubernetes nodes.

See https://kubernetes.io/docs/contribute/style/content-guide/#what-s-allowed for the formal policy.

[sftim]

Ideally, move this discussion to another issue, and close this support query.

[neolit123]

That's the precedent we don't wish to set. If a SIG wants to document a feature, they should put the docs on the Kubernetes website itself.

i'm bit confused how that is degrading to the documentation.

today we still link to external pages for CNI installation.
i.e. if someone wants kubeadm + Callico they go to the kubeadm "create a cluster page", reach the CNI step, open the "addons page" click Callico which takes them externally.

the difference here is that SIG Windows owns a wrapper guide located at sig-windows-tools.

(relevant detail: the Linux Foundation exams permit reading the docs, but don't allow following such hyperlinks)

not relevant to Windows nodes i would assume.

[neolit123]

i can send a PR that:

• creates the Linux task page by moving / refactoring the existing "join node" contents from the "create a cluster" page:
  https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#join-nodes
• creates the Windows task page by taking the content from https://github.com/kubernetes-sigs/sig-windows-tools/blob/master/guides/guide-for-adding-windows-node.md
• at the end of the Windows page we add note/disclaimer whatever that says that CNI on Windows needs special handling and we link to the various CNI choices at:
  https://github.com/kubernetes-sigs/sig-windows-tools/blob/master/guides/guide-for-adding-windows-node.md#networking-configuration
• adds tabs in the https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#join-nodes to choose between OS for joining nodes.

if that doesn't sound right i don't understand how the Windows documentation can improve anytime soon.
also i don't think it's a GA blocker given CNI setup is external to kubeadm.

[sftim]

Yep, that sounds good.

i.e. if someone wants kubeadm + Callico they go to the kubeadm "create a cluster page", reach the CNI step, open the "addons page" click Callico which takes them externally.

This is fine; you need a network plugin to have a working cluster, and the install guide for Calico is (should be) external. We wouldn't dual source it.

wrapper guide located at sig-windows-tools

We cannot - even at a stretch - call that linking to canonical vendor documentation.

@neolit123 I think you're correct to surmise that the Linux Foundation exams don't expect you to manage Windows nodes, but I also don't want to find that there's a CKWA qualification coming or something and that we now need to change our docs policies. The policies aim to be vendor neutral and that's as it should be. We try not to pick winners, even if the winner is down to the Linux Foundation using Linux.

[tengqm]

I'd vote for adding a task for Windows nodes, documenting whatever people need to know from Kubernetes's side. Speaking of external dependencies, especially CNI or similar stuff, it is still fine to install hyperlinks.

[divya-mohan0209]

Summarizing my understanding of the situation here (please correct me if I'm wrong):

Currently, we do not have a section in our docs dedicated to adding Windows/Linux nodes. We are discussing how to create one for Windows because kubeadm support for Windows is becoming generally available. However, we are faced with two problems:

• Problem 1: Lack of a page dedicated to the addition of Linux nodes.
• Problem 2: There are very specific steps required for the installation of the CNI (i.e. Calico, Flannel) as outlined here. While our docs policies allow including content that's needed for Kubernetes to function, the Linux Foundation exams do not allow following hyperlinks to external links.

My two cents:

As SIG Docs, we do not want to set the precedent of having GA features incompletely documented or be prescriptive about vendors/projects. Therefore, in the spirit of staying vendor-neutral, I mostly agree with the approach outlined in this comment, even though it isn't 100% ideal. This is, of course, with the caveat of special handling being documented explicitly and hyperlinking to the GitHub repo for sig-windows-tools. If and when we find a better way to include those documents in the future, we improve the content on our website by adhering to the docs policies.

[neolit123]

thanks for the comments.

now tracked in:
#47884

/close

[k8s-ci-robot]

@neolit123: Closing this issue.

In response to this:

thanks for the comments.

now tracked in:
#47884

/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-sigs/prow repository.

[sftim]

/reopen
(momentarily)

[k8s-ci-robot]

@sftim: Reopened this issue.

In response to this:

/reopen
(momentarily)

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-sigs/prow repository.

[sftim]

See #44248 instead
/close not-planned

[k8s-ci-robot]

@sftim: Closing this issue, marking it as "Not Planned".

In response to this:

See #44248 instead
/close not-planned

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-sigs/prow repository.