Docs for Running Windows Containers in Kubernetes

[craiglpeters]

This is a...

• Feature Request
• Bug Report

Problem:
The ability to run Windows Containers in Kubernetes is moving towards GA in 1.14 (or possibly 1.15). Windows Containers aren't identical to Linux containers. They have their own limitations and require Windows nodes. The GA release will not run all Kubernetes services on Windows, so mixed Operating System clusters are required with Kubernetes Master running Linux. The documentation implications are significant since running mixed Operating System clusters is not currently covered.

This issue exists to discuss the best approach to addressing the potentially very broad impact on documentation.

Proposed Solution:
At least two major use cases need to be addressed:

1. New K8s operators creating clusters to run Windows Containers they've been running in some other way
   Those new to K8s need to understand how to stand up a mixed operating system cluster from scratch, and how to get their Windows Containers scheduled on the right nodes.

2. K8s operators with an existing K8s cluster who want to run both Linux and Windows containers
   Experienced K8s operators need to be educated about the limitations of Windows Containers, the variants on the user experience, how to add Windows nodes to their clusters, and how to get Linux and Windows containers to run on the right nodes and communicate with each other.

The proposal is to start by writing monolithic documentation addressing these two use cases first, and then to determine how to land it in the documentation. The alternative is to assess which existing docs need updates, and then plan those.

Page to Update:
https://kubernetes.io/... too many to list

Kubernetes Version:1.14

Additional Information:

• KEP For Windows Nodes in Kubernetes which includes some bullet points about topics to include in documentation
• Enhancement Issue
• PR for Documentation of Windows in Kubernetes for 1.13
• Kubernetes Windows Walkthrough
• Windows Containers Workshop

[jimangel]

My suggestion from the meeting today: It would be preferred to create a one or two page document that covers the "bulk" of your solutions. We would merge it in with our dev-1.14 branch upon release. I would recommend against touching a ton of minor docs until the k8s release has landed and those updates could be done in master.

The reasoning behind this is because we merge master periodically into dev-v1.14 and, with that, we need to resolve any conflicts. If your windows docs touch a ton of pages it will make the process more prone to merge conflicts / resolutions.

The minor updates (many pages) could be identified and made in master (hours) after we merge dev-1.14 w/ release (tentative 3/25).

[craiglpeters]

Please take a look at the draft outline (also circulated via the mailing list)

[neolit123]

/sig windows

[craiglpeters]

Here is placeholder PR for the changes to docs

[michmike]

documentation is now up and running.
You can view it in staging under https://5c914f680410ed000aeebc2e--kubernetes-io-vnext-staging.netlify.com/docs/setup/windows/add-windows-nodes/
/close

[k8s-ci-robot]

@michmike: Closing this issue.

In response to this:

documentation is now up and running.
You can view it in staging under https://5c914f680410ed000aeebc2e--kubernetes-io-vnext-staging.netlify.com/docs/setup/windows/add-windows-nodes/
/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.