From f061cd3175644243f17e0d583c08d6ce7922fefe Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 19:23:25 -0500 Subject: [PATCH 01/15] Create contributing-on-windows.md --- contributors/guide/contributing-on-windows.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 contributors/guide/contributing-on-windows.md diff --git a/contributors/guide/contributing-on-windows.md b/contributors/guide/contributing-on-windows.md new file mode 100644 index 000000000..376dd47c2 --- /dev/null +++ b/contributors/guide/contributing-on-windows.md @@ -0,0 +1 @@ + From d221f13bc2b8b0ecb952946c4b3d38da3e3f9296 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 19:35:59 -0500 Subject: [PATCH 02/15] Update README.md --- contributors/guide/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 38afef67d..59caa9a91 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -31,6 +31,7 @@ Welcome to Kubernetes! - [Code Review](#code-review) - [Testing](#testing) - [Security](#security) + - [Contributing on Windows Node support](#contributing-on-windows-node-support) - [Documentation](#documentation) - [Issues Management or Triage](#issues-management-or-triage) - [Kubernetes Contributor Playground](#kubernetes-contributor-playground) @@ -242,6 +243,8 @@ If you're looking to run e2e tests on your own infrastructure, [kubetest](https: - [Security Release Page](https://git.k8s.io/sig-release/security-release-process-documentation/security-release-process.md) - outlines the procedures for the handling of security issues. - [Security and Disclosure Information](https://kubernetes.io/docs/reference/issues-security/security/) - check this page if you wish to report a security vulnerability. +## Contributing on Windows Node support +If you would like to contribute to the effort of supporting Windows Nodes in Kubernetes and scheduling Windows containers, we have a dedicated [reference guide](./contributing-on-windows.md). ## Documentation From 6dda1ac0cd54cccf414fb9d49dd4d23bcc8d17db Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 21:04:31 -0500 Subject: [PATCH 03/15] Update sigs.yaml --- sigs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigs.yaml b/sigs.yaml index 9001d84d6..278eda5f5 100644 --- a/sigs.yaml +++ b/sigs.yaml @@ -2133,7 +2133,7 @@ sigs: - name: Windows dir: sig-windows mission_statement: > - Focuses on supporting Windows Server Containers for Kubernetes. + Focuses on supporting Windows Node and scheduling Windows Server containers on Kubernetes. charter_link: label: windows leadership: From 458a23054e9073ae4aab71b13367912f3510d25a Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 21:07:08 -0500 Subject: [PATCH 04/15] Delete api-tracking.md no longer need this file since the content is now in the KEP and the user-facing documentation --- sig-windows/api-tracking.md | 76 ------------------------------------- 1 file changed, 76 deletions(-) delete mode 100644 sig-windows/api-tracking.md diff --git a/sig-windows/api-tracking.md b/sig-windows/api-tracking.md deleted file mode 100644 index 34052adcc..000000000 --- a/sig-windows/api-tracking.md +++ /dev/null @@ -1,76 +0,0 @@ -# Windows & Kubernetes APIs - -This document will grow into an API by API list of work that needs to be done to clarify Windows & Linux differences. This will be used to help clarify what needs to be eventually implemented (need a tracking issue), or not implemented (need a doc note). - - -## Volumes - -`V1.Pod.Volumes` - -Out of the various volume types, these should all be possible on Windows but tests are lacking: - -- EmptyDirVolumeSource -- Secret -- hostPath - -The main gaps in Windows Server 2016 & 1709 are that symlinks are pretty much broken. The only ones that work are SMB/CIFS mount points. Workarounds need to be investigated. - -`V1.Container.volumeMounts` -Mounting volumes across some (but not all) containers will need changes to Windows. Not ready in Windows Server 2016/1709. - -### Links - -- [FlexVolume does not work on Windows node](https://github.com/kubernetes/kubernetes/issues/56875) -- [feature proposal add SMB(cifs) volume plugin](https://github.com/kubernetes/kubernetes/issues/56005) -- [add NFS volume support for Windows](https://github.com/kubernetes/kubernetes/issues/56188) - -## V1.Pod.Resources & V1.Container.ResourceRequirements - -`V1.Container.ResourceRequirements.limits.cpu` -`V1.Container.ResourceRequirements.limits.memory` - -Windows schedules CPU based on CPU count & percentage of cores. We need this represented because it can help optimize app performance. CPU count is immutable once set but you can change % of core allocations. - -`V1.Container.ResourceRequirements.requests.cpu` -`V1.Container.ResourceRequirements.requests.memory` - -Also of note, requests aren't supported. Will pod eviction policies in the kubelet ensure reserves are met by not overprovisioning the node? - -Windows can either expose a NUMA topology matching the host (best performance) or fake it to be 1 big NUMA node (suboptimal). We should think of a way to turn this on/off later - probably q2 2018 - -### Links -[Kubernetes Container Runtime Interface (CRI) doesn't support WindowsContainerConfig and WindowsContainerResources](https://github.com/kubernetes/kubernetes/issues/56734) - - - -## Networking features - -`V1.Pod.dnsPolicy` - I think only ClusterFirst is implemented - -`V1.Pod.hostNetwork` - Not feasible on Windows Server 2016 / 1709 - -## IPC & Pid - -`V1.Pod.hostIPC`, `v1.pod.hostpid` - -How important are these? They're not implemented in Windows Server 2016 / 1709, and I'm not too sure if they'd be helpful or not. - -For cases where a pod/container need to talk to the host docker / containerd daemon we could map a named pipe as a volume which would offer the same functionality as the unix socket to the Linux daemons. It works in moby but isn't hooked up in the kubelet yet. - -## Security - -- `V1.Container.SecurityContext.Capabilities` -- `V1.Container.SecurityContext.seLinuxOptions` - -These don't have Windows equivalents since the permissions model is substantially different - -`V1.Container.SecurityContext.readOnlyRootFilesystem` - -This is probably doable if needed but not possible in Windows Server 2016 / 1709. - -### User Mapping - -There are a few fields that refer to uid/gid. These probably need to be supplemented with a Windows SID (string) and username (string) - -`V1.podSecurityContext.runAsUser` provides a UID -`V1.podSecurityContext.supplementalGroups` provides GID \ No newline at end of file From b60a31b80a88f6d7e04740d86677619b19e3859a Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 21:41:21 -0500 Subject: [PATCH 05/15] Update contributing-on-windows.md --- contributors/guide/contributing-on-windows.md | 89 ++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/contributors/guide/contributing-on-windows.md b/contributors/guide/contributing-on-windows.md index 376dd47c2..0cf9aa2b4 100644 --- a/contributors/guide/contributing-on-windows.md +++ b/contributors/guide/contributing-on-windows.md @@ -1 +1,88 @@ - +# Contributing on Windows Node support + +Contains a list of common resources when contributing to supporting Windows Node and Windows Server containers in Kubernetes. + +## Joining the community of other contributors + +The best way to get in contact with the contributors working on Windows support is through the Kubernetes Slack. To get a Slack invite, visit [http://slack.k8s.io/](http://slack.k8s.io/) . Once you're logged in, join us in the [#SIG-Windows](https://kubernetes.slack.com/messages/sig-windows) channel. + +To get access to shared documents, meeting calendar, and additional discussions, be sure to also join the [SIG-Windows Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-windows). + +View the leadership team in SIG-Windows and other subprojects in the [getting started](https://github.com/kubernetes/community/tree/master/sig-windows) guide. + +## Find work in progress + +To get a handle on current work, you can view [outstanding PRs](https://github.com/kubernetes/kubernetes/pulls?q=is%3Apr+is%3Aopen+label%3Asig%2Fwindows+is%3Apr). + +View the SIG-Windows project board, tracking detailed [issues across Kubernetes releases](https://github.com/orgs/kubernetes/projects/8). + +## Building Kubernetes for Windows from Source + +The Kubernetes build scripts have not been ported to Windows, so it's best to run in a Linux VM where you can run the same Docker container used in the official Kubernetes builds. This simplifies the steps, but means that you cannot build under Windows Subsystem for Linux (WSL). + +It's best to skim over the [Building Kubernetes](https://github.com/kubernetes/kubernetes/blob/master/build/README.md) guide if you have never built Kubernetes before to get the latest info. These steps are a summary focused on cross-building the Windows node binaries (kubelet & kube-proxy). + +### Build Prerequisites + +At least 60GB of disk space is required, and 16GB of memory (or memory + swap). + +Once you have a VM, install Git, [Docker-CE](https://docs.docker.com/install/), and make. The build scripts will pull a Docker container with the required version of golang and other needed tools preinstalled. + +If you're using Ubuntu, then install the following packages: git, build-essential, [Docker-CE](https://docs.docker.com/install/linux/docker-ce/ubuntu/). + +### Building Kubernetes binaries for Windows + +You can build individual components such as kubelet, kube-proxy, or kubectl by running `./build/run.sh make KUBE_BUILD_PLATFORMS=windows/amd64` such as `./build/run.sh make kubelet KUBE_BUILD_PLATFORMS=windows/amd64` + +If you would like to build all binaries at once, then run `./build/run.sh make cross KUBE_BUILD_PLATFORMS=windows/amd64` + +Once the build completes, the files will be in `_output/dockerized/bin`. + +### Updating the Node binaries + +Once you have binaries built, the easiest way to test them is to replace them on an existing cluster. This section assumes you already have a cluster in the cloud of your choice. To update the binaries on an existing node, follow these steps: + +1. Drain & cordon a node with `kubectl drain ` +2. Connect to the node with SSH or Windows Remote Desktop, and start PowerShell +3. On the node, run `Stop-Service kubelet -Force` +4. Copy kubelet.exe and kube-proxy.exe to a cloud storage account, or use SSH to copy them directly to the node. +5. Overwrite the existing kubelet & kube-proxy binaries. If you don't know where they are, run `sc.exe qc kubelet` or `sc.exe qc kube-proxy` and look at the BINARY_PATH_NAME returned. +6. Start the updated kubelet & kube-proxy with `Start-Service kubelet` + +## Creating a PR + +Congratulations on contributing to the SIG-Windows ecosystem. If there is a PR you would like to build, it's easy. You can create a working branch, pull the changes from GitHub in a patch, apply, then build. + +The detailed steps here are based off an example PR on GitHub: [https://github.com/kubernetes/kubernetes/pull/74788](https://github.com/kubernetes/kubernetes/pull/74788). Be sure to replace the URL and steps with the PR you want to test. + +1. Make sure your local clone is up-to-date with master: `git checkout master ; git pull master` +2. Create a branch in your repo: `git checkout -b pr74788` +3. Get the patch for the PR you want. Append `.patch` to the URL, and download it with curl: `curl -L -o pr74788.patch https://github.com/kubernetes/kubernetes/pull/74788.patch` +4. Merge it with `patch -p1 < pr74788.patch` +5. If there are errors, fix them as needed. Once you're done, delete the `.patch` file and then `git commit` the rest to your local branch. +6. Deploy your own cluster, including Windows Nodes +7. Test Your Changes + +## Running Tests + +For the most up-to-date steps on how to build and run tests, please go to [https://github.com/kubernetes-sigs/windows-testing](https://github.com/kubernetes-sigs/windows-testing). It has everything you need to build and run tests, as well as links to the SIG-Windows configurations used on [TestGrid](https://testgrid.k8s.io/sig-windows). + +## Reporting Issues + +You can open issues on [GitHub](https://github.com/kubernetes/kubernetes/issues/new/choose) and assign them to SIG-Windows by commenting on the issue with `/sig windows`. You should first search the list of issues in case it was reported previously and comment with your experience on the issue and add additional logs. SIG-Windows Slack is also a great avenue to get some initial support prior to creating a ticket. + +It is important you include as much information as possible with your issue. That includes environment details, detailed steps on how to reproduce the issue, and logs. + +## Gathering Logs + +Logs are an important element of troubleshooting issues in Kubernetes. Make sure to include them any time you seek troubleshooting assistance from other contributors. + +### Collecting Networking Logs +1. On the node before creating the pod for the first time. +2. `start-bitstransfer https://raw.githubusercontent.com/Microsoft/SDN/master/Kubernetes/windows/debug/collectlogs.ps1` +3. Execute collectlogs.ps1 in a PowerShell window +4 Start the trace by running `C:\k\debug\starthnstrace.cmd` +5. Reproduce the issue +6. Run `netsh trace stop` +7. Execute collectlogs.ps1 in a PowerShell window again +8. Include in your ticket `C:\server.etl` From 678269443ff825295d54e585facfa935c4727116 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 21:41:54 -0500 Subject: [PATCH 06/15] Update contributing-on-windows.md --- contributors/guide/contributing-on-windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributors/guide/contributing-on-windows.md b/contributors/guide/contributing-on-windows.md index 0cf9aa2b4..2194d775b 100644 --- a/contributors/guide/contributing-on-windows.md +++ b/contributors/guide/contributing-on-windows.md @@ -1,6 +1,6 @@ # Contributing on Windows Node support -Contains a list of common resources when contributing to supporting Windows Node and Windows Server containers in Kubernetes. +Contains a list of common resources when contributing in the effort to support Windows Node and Windows Server containers in Kubernetes. ## Joining the community of other contributors From 2b6fb0f375626af93f4eef1f87bfaa8ec25a78f0 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 21:52:21 -0500 Subject: [PATCH 07/15] Update contributing-on-windows.md --- contributors/guide/contributing-on-windows.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/contributors/guide/contributing-on-windows.md b/contributors/guide/contributing-on-windows.md index 2194d775b..365847e22 100644 --- a/contributors/guide/contributing-on-windows.md +++ b/contributors/guide/contributing-on-windows.md @@ -2,6 +2,18 @@ Contains a list of common resources when contributing in the effort to support Windows Node and Windows Server containers in Kubernetes. +- [Joining the community of other contributors](#joining-the-community-of-other-contributors) +- [Find work in progress](#find-work-in-progress) +- [Building Kubernetes for Windows from Source](#building-kubernetes-for-windows-from-source) + - [Build Prerequisites](#build-prerequisites) + - [Building Kubernetes binaries for Windows](#building-kubernetes-binaries-for-windows) + - [Updating the Node binaries](#updating-the-node-binaries) +- [Creating a PR](#creating-a-pr) +- [Running Tests](#running-tests) +- [Reporting Issues](#reporting-issues) +- [Gathering Logs](#gathering-logs) + - [Collecting Networking Logs](#collecting-networking-logs) + ## Joining the community of other contributors The best way to get in contact with the contributors working on Windows support is through the Kubernetes Slack. To get a Slack invite, visit [http://slack.k8s.io/](http://slack.k8s.io/) . Once you're logged in, join us in the [#SIG-Windows](https://kubernetes.slack.com/messages/sig-windows) channel. From 43aa0b651837f434b7c16a5b16e7b88c119798de Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 02:58:43 +0000 Subject: [PATCH 08/15] updating sigs.yaml --- sig-windows/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sig-windows/README.md b/sig-windows/README.md index 91dcaac97..89ebcbe57 100644 --- a/sig-windows/README.md +++ b/sig-windows/README.md @@ -8,7 +8,7 @@ To understand how this file is generated, see https://git.k8s.io/community/gener ---> # Windows Special Interest Group -Focuses on supporting Windows Server Containers for Kubernetes. +Focuses on supporting Windows Node and scheduling Windows Server containers on Kubernetes. ## Meetings * Regular SIG Meeting: [Tuesdays at 12:30 Eastern Standard Time (EST)](https://docs.google.com/document/d/1FQx0BPlkkl1Bn0c9ocVBxYIKojpmrS1CFP5h0DI68AE/edit) (weekly). [Convert to your timezone](http://www.thetimezoneconverter.com/?t=12:30&tz=Eastern%20Standard%20Time%20%28EST%29). From 4096d4ac20ca3a253dba651e7449df6429481a4c Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Tue, 12 Mar 2019 22:12:55 -0500 Subject: [PATCH 09/15] Update README.md --- sig-windows/README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/sig-windows/README.md b/sig-windows/README.md index 89ebcbe57..3f2a56a03 100644 --- a/sig-windows/README.md +++ b/sig-windows/README.md @@ -52,24 +52,20 @@ Note that the links to display team membership will only work if you are a membe ## Getting Started -If you're looking for information on building and running containers on Windows, you can get started at http://aka.ms/windowscontainers . +If you're looking for information on building and running containers on Windows, you can get started at http://aka.ms/windowscontainers. -Kubernetes 1.9 includes beta support for Windows Server containers and has an up-to-date [Getting Started Guide for Windows](https://kubernetes.io/docs/getting-started-guides/windows/) . +Kubernetes 1.14 includes stable support for Windows Server containers and has an up-to-date [Getting Started Guide for Windows](https://kubernetes.io/docs/getting-started-guides/windows/) . -Some additional guides are available, but may refer to older releases: - -* Using host gateway networking: https://docs.microsoft.com/en-us/virtualization/windowscontainers/kubernetes/getting-started-kubernetes-windows -* Using OVN as demonstrated at Google Cloud Next '17: https://github.com/apprenda/kubernetes-ovn-heterogeneous-cluster +Additional information and guides are available in the [KEPs for SIG-Windows](https://github.com/kubernetes/enhancements/tree/master/keps/sig-windows) ## Contributing -We're currently using a public [Trello board](https://trello.com/b/rjTqrwjl/windows-k8s-roadmap) in the weekly SIG-Windows meeting to track items with active progress for each release. That's a great place to start to get the most up-to-date status, then feel free to join us on the Slack channel anytime with questions. +To get yourself familiar with contributing, please read the [SIG-Windows Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md#contributing-on-windows-node-support) + +We're currently using a [GitHub project](https://github.com/orgs/kubernetes/projects/8) in the weekly SIG-Windows meeting to track items with active progress for each release. That's a great place to start to get the most up-to-date status, then feel free to join us on the Slack channel anytime with questions. As always, you can also find the active list of open issues and proposals [Open Code Issues and PRs for SIG/Windows](https://github.com/kubernetes/kubernetes/labels/sig%2Fwindows) on GitHub. -## API tracking -We also have an [API tracking](https://github.com/kubernetes/community/blob/master/sig-windows/api-tracking.md) document that we're building out to track areas where the APIs may not be implemented or need to change for Windows. - ## Meeting Recordings Past meetings are in the [Recorded Meetings Playlist on Youtube](https://www.youtube.com/playlist?list=PL69nYSiGNLP2OH9InCcNkWNu2bl-gmIU4&jct=LZ9EIvD4DGrhr2h4r0ItaBmco7gTgw) From d80405b008096a6509db0aaf52e73a9d4482f139 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 11:15:37 -0500 Subject: [PATCH 10/15] Create contributors-guide.md --- sig-windows/contributors-guide.md | 100 ++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 sig-windows/contributors-guide.md diff --git a/sig-windows/contributors-guide.md b/sig-windows/contributors-guide.md new file mode 100644 index 000000000..365847e22 --- /dev/null +++ b/sig-windows/contributors-guide.md @@ -0,0 +1,100 @@ +# Contributing on Windows Node support + +Contains a list of common resources when contributing in the effort to support Windows Node and Windows Server containers in Kubernetes. + +- [Joining the community of other contributors](#joining-the-community-of-other-contributors) +- [Find work in progress](#find-work-in-progress) +- [Building Kubernetes for Windows from Source](#building-kubernetes-for-windows-from-source) + - [Build Prerequisites](#build-prerequisites) + - [Building Kubernetes binaries for Windows](#building-kubernetes-binaries-for-windows) + - [Updating the Node binaries](#updating-the-node-binaries) +- [Creating a PR](#creating-a-pr) +- [Running Tests](#running-tests) +- [Reporting Issues](#reporting-issues) +- [Gathering Logs](#gathering-logs) + - [Collecting Networking Logs](#collecting-networking-logs) + +## Joining the community of other contributors + +The best way to get in contact with the contributors working on Windows support is through the Kubernetes Slack. To get a Slack invite, visit [http://slack.k8s.io/](http://slack.k8s.io/) . Once you're logged in, join us in the [#SIG-Windows](https://kubernetes.slack.com/messages/sig-windows) channel. + +To get access to shared documents, meeting calendar, and additional discussions, be sure to also join the [SIG-Windows Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-windows). + +View the leadership team in SIG-Windows and other subprojects in the [getting started](https://github.com/kubernetes/community/tree/master/sig-windows) guide. + +## Find work in progress + +To get a handle on current work, you can view [outstanding PRs](https://github.com/kubernetes/kubernetes/pulls?q=is%3Apr+is%3Aopen+label%3Asig%2Fwindows+is%3Apr). + +View the SIG-Windows project board, tracking detailed [issues across Kubernetes releases](https://github.com/orgs/kubernetes/projects/8). + +## Building Kubernetes for Windows from Source + +The Kubernetes build scripts have not been ported to Windows, so it's best to run in a Linux VM where you can run the same Docker container used in the official Kubernetes builds. This simplifies the steps, but means that you cannot build under Windows Subsystem for Linux (WSL). + +It's best to skim over the [Building Kubernetes](https://github.com/kubernetes/kubernetes/blob/master/build/README.md) guide if you have never built Kubernetes before to get the latest info. These steps are a summary focused on cross-building the Windows node binaries (kubelet & kube-proxy). + +### Build Prerequisites + +At least 60GB of disk space is required, and 16GB of memory (or memory + swap). + +Once you have a VM, install Git, [Docker-CE](https://docs.docker.com/install/), and make. The build scripts will pull a Docker container with the required version of golang and other needed tools preinstalled. + +If you're using Ubuntu, then install the following packages: git, build-essential, [Docker-CE](https://docs.docker.com/install/linux/docker-ce/ubuntu/). + +### Building Kubernetes binaries for Windows + +You can build individual components such as kubelet, kube-proxy, or kubectl by running `./build/run.sh make KUBE_BUILD_PLATFORMS=windows/amd64` such as `./build/run.sh make kubelet KUBE_BUILD_PLATFORMS=windows/amd64` + +If you would like to build all binaries at once, then run `./build/run.sh make cross KUBE_BUILD_PLATFORMS=windows/amd64` + +Once the build completes, the files will be in `_output/dockerized/bin`. + +### Updating the Node binaries + +Once you have binaries built, the easiest way to test them is to replace them on an existing cluster. This section assumes you already have a cluster in the cloud of your choice. To update the binaries on an existing node, follow these steps: + +1. Drain & cordon a node with `kubectl drain ` +2. Connect to the node with SSH or Windows Remote Desktop, and start PowerShell +3. On the node, run `Stop-Service kubelet -Force` +4. Copy kubelet.exe and kube-proxy.exe to a cloud storage account, or use SSH to copy them directly to the node. +5. Overwrite the existing kubelet & kube-proxy binaries. If you don't know where they are, run `sc.exe qc kubelet` or `sc.exe qc kube-proxy` and look at the BINARY_PATH_NAME returned. +6. Start the updated kubelet & kube-proxy with `Start-Service kubelet` + +## Creating a PR + +Congratulations on contributing to the SIG-Windows ecosystem. If there is a PR you would like to build, it's easy. You can create a working branch, pull the changes from GitHub in a patch, apply, then build. + +The detailed steps here are based off an example PR on GitHub: [https://github.com/kubernetes/kubernetes/pull/74788](https://github.com/kubernetes/kubernetes/pull/74788). Be sure to replace the URL and steps with the PR you want to test. + +1. Make sure your local clone is up-to-date with master: `git checkout master ; git pull master` +2. Create a branch in your repo: `git checkout -b pr74788` +3. Get the patch for the PR you want. Append `.patch` to the URL, and download it with curl: `curl -L -o pr74788.patch https://github.com/kubernetes/kubernetes/pull/74788.patch` +4. Merge it with `patch -p1 < pr74788.patch` +5. If there are errors, fix them as needed. Once you're done, delete the `.patch` file and then `git commit` the rest to your local branch. +6. Deploy your own cluster, including Windows Nodes +7. Test Your Changes + +## Running Tests + +For the most up-to-date steps on how to build and run tests, please go to [https://github.com/kubernetes-sigs/windows-testing](https://github.com/kubernetes-sigs/windows-testing). It has everything you need to build and run tests, as well as links to the SIG-Windows configurations used on [TestGrid](https://testgrid.k8s.io/sig-windows). + +## Reporting Issues + +You can open issues on [GitHub](https://github.com/kubernetes/kubernetes/issues/new/choose) and assign them to SIG-Windows by commenting on the issue with `/sig windows`. You should first search the list of issues in case it was reported previously and comment with your experience on the issue and add additional logs. SIG-Windows Slack is also a great avenue to get some initial support prior to creating a ticket. + +It is important you include as much information as possible with your issue. That includes environment details, detailed steps on how to reproduce the issue, and logs. + +## Gathering Logs + +Logs are an important element of troubleshooting issues in Kubernetes. Make sure to include them any time you seek troubleshooting assistance from other contributors. + +### Collecting Networking Logs +1. On the node before creating the pod for the first time. +2. `start-bitstransfer https://raw.githubusercontent.com/Microsoft/SDN/master/Kubernetes/windows/debug/collectlogs.ps1` +3. Execute collectlogs.ps1 in a PowerShell window +4 Start the trace by running `C:\k\debug\starthnstrace.cmd` +5. Reproduce the issue +6. Run `netsh trace stop` +7. Execute collectlogs.ps1 in a PowerShell window again +8. Include in your ticket `C:\server.etl` From f86a3a230ec8b51c3cfd8fbe19131c251def06bd Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 11:16:17 -0500 Subject: [PATCH 11/15] Update README.md --- sig-windows/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sig-windows/README.md b/sig-windows/README.md index 3f2a56a03..95420c8e7 100644 --- a/sig-windows/README.md +++ b/sig-windows/README.md @@ -60,7 +60,7 @@ Additional information and guides are available in the [KEPs for SIG-Windows](ht ## Contributing -To get yourself familiar with contributing, please read the [SIG-Windows Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md#contributing-on-windows-node-support) +To get yourself familiar with contributing, please read the [SIG-Windows Contributor guide](./contributors-guide.md) We're currently using a [GitHub project](https://github.com/orgs/kubernetes/projects/8) in the weekly SIG-Windows meeting to track items with active progress for each release. That's a great place to start to get the most up-to-date status, then feel free to join us on the Slack channel anytime with questions. From 219e8cfe5c80b39a6e6b6c204d99ed7e1f34080b Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 11:18:24 -0500 Subject: [PATCH 12/15] Update README.md --- sig-windows/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sig-windows/README.md b/sig-windows/README.md index 95420c8e7..9ea8aa75e 100644 --- a/sig-windows/README.md +++ b/sig-windows/README.md @@ -60,7 +60,7 @@ Additional information and guides are available in the [KEPs for SIG-Windows](ht ## Contributing -To get yourself familiar with contributing, please read the [SIG-Windows Contributor guide](./contributors-guide.md) +To get yourself familiar with contributing, please read the [Kubernetes Contributor Guide](../contributors/guide/README.md) and the [SIG-Windows Contributor guide](./contributors-guide.md) We're currently using a [GitHub project](https://github.com/orgs/kubernetes/projects/8) in the weekly SIG-Windows meeting to track items with active progress for each release. That's a great place to start to get the most up-to-date status, then feel free to join us on the Slack channel anytime with questions. From 90a89d05d5266f19b931db0b1a14ded635e46759 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 11:19:27 -0500 Subject: [PATCH 13/15] Delete contributing-on-windows.md --- contributors/guide/contributing-on-windows.md | 100 ------------------ 1 file changed, 100 deletions(-) delete mode 100644 contributors/guide/contributing-on-windows.md diff --git a/contributors/guide/contributing-on-windows.md b/contributors/guide/contributing-on-windows.md deleted file mode 100644 index 365847e22..000000000 --- a/contributors/guide/contributing-on-windows.md +++ /dev/null @@ -1,100 +0,0 @@ -# Contributing on Windows Node support - -Contains a list of common resources when contributing in the effort to support Windows Node and Windows Server containers in Kubernetes. - -- [Joining the community of other contributors](#joining-the-community-of-other-contributors) -- [Find work in progress](#find-work-in-progress) -- [Building Kubernetes for Windows from Source](#building-kubernetes-for-windows-from-source) - - [Build Prerequisites](#build-prerequisites) - - [Building Kubernetes binaries for Windows](#building-kubernetes-binaries-for-windows) - - [Updating the Node binaries](#updating-the-node-binaries) -- [Creating a PR](#creating-a-pr) -- [Running Tests](#running-tests) -- [Reporting Issues](#reporting-issues) -- [Gathering Logs](#gathering-logs) - - [Collecting Networking Logs](#collecting-networking-logs) - -## Joining the community of other contributors - -The best way to get in contact with the contributors working on Windows support is through the Kubernetes Slack. To get a Slack invite, visit [http://slack.k8s.io/](http://slack.k8s.io/) . Once you're logged in, join us in the [#SIG-Windows](https://kubernetes.slack.com/messages/sig-windows) channel. - -To get access to shared documents, meeting calendar, and additional discussions, be sure to also join the [SIG-Windows Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-windows). - -View the leadership team in SIG-Windows and other subprojects in the [getting started](https://github.com/kubernetes/community/tree/master/sig-windows) guide. - -## Find work in progress - -To get a handle on current work, you can view [outstanding PRs](https://github.com/kubernetes/kubernetes/pulls?q=is%3Apr+is%3Aopen+label%3Asig%2Fwindows+is%3Apr). - -View the SIG-Windows project board, tracking detailed [issues across Kubernetes releases](https://github.com/orgs/kubernetes/projects/8). - -## Building Kubernetes for Windows from Source - -The Kubernetes build scripts have not been ported to Windows, so it's best to run in a Linux VM where you can run the same Docker container used in the official Kubernetes builds. This simplifies the steps, but means that you cannot build under Windows Subsystem for Linux (WSL). - -It's best to skim over the [Building Kubernetes](https://github.com/kubernetes/kubernetes/blob/master/build/README.md) guide if you have never built Kubernetes before to get the latest info. These steps are a summary focused on cross-building the Windows node binaries (kubelet & kube-proxy). - -### Build Prerequisites - -At least 60GB of disk space is required, and 16GB of memory (or memory + swap). - -Once you have a VM, install Git, [Docker-CE](https://docs.docker.com/install/), and make. The build scripts will pull a Docker container with the required version of golang and other needed tools preinstalled. - -If you're using Ubuntu, then install the following packages: git, build-essential, [Docker-CE](https://docs.docker.com/install/linux/docker-ce/ubuntu/). - -### Building Kubernetes binaries for Windows - -You can build individual components such as kubelet, kube-proxy, or kubectl by running `./build/run.sh make KUBE_BUILD_PLATFORMS=windows/amd64` such as `./build/run.sh make kubelet KUBE_BUILD_PLATFORMS=windows/amd64` - -If you would like to build all binaries at once, then run `./build/run.sh make cross KUBE_BUILD_PLATFORMS=windows/amd64` - -Once the build completes, the files will be in `_output/dockerized/bin`. - -### Updating the Node binaries - -Once you have binaries built, the easiest way to test them is to replace them on an existing cluster. This section assumes you already have a cluster in the cloud of your choice. To update the binaries on an existing node, follow these steps: - -1. Drain & cordon a node with `kubectl drain ` -2. Connect to the node with SSH or Windows Remote Desktop, and start PowerShell -3. On the node, run `Stop-Service kubelet -Force` -4. Copy kubelet.exe and kube-proxy.exe to a cloud storage account, or use SSH to copy them directly to the node. -5. Overwrite the existing kubelet & kube-proxy binaries. If you don't know where they are, run `sc.exe qc kubelet` or `sc.exe qc kube-proxy` and look at the BINARY_PATH_NAME returned. -6. Start the updated kubelet & kube-proxy with `Start-Service kubelet` - -## Creating a PR - -Congratulations on contributing to the SIG-Windows ecosystem. If there is a PR you would like to build, it's easy. You can create a working branch, pull the changes from GitHub in a patch, apply, then build. - -The detailed steps here are based off an example PR on GitHub: [https://github.com/kubernetes/kubernetes/pull/74788](https://github.com/kubernetes/kubernetes/pull/74788). Be sure to replace the URL and steps with the PR you want to test. - -1. Make sure your local clone is up-to-date with master: `git checkout master ; git pull master` -2. Create a branch in your repo: `git checkout -b pr74788` -3. Get the patch for the PR you want. Append `.patch` to the URL, and download it with curl: `curl -L -o pr74788.patch https://github.com/kubernetes/kubernetes/pull/74788.patch` -4. Merge it with `patch -p1 < pr74788.patch` -5. If there are errors, fix them as needed. Once you're done, delete the `.patch` file and then `git commit` the rest to your local branch. -6. Deploy your own cluster, including Windows Nodes -7. Test Your Changes - -## Running Tests - -For the most up-to-date steps on how to build and run tests, please go to [https://github.com/kubernetes-sigs/windows-testing](https://github.com/kubernetes-sigs/windows-testing). It has everything you need to build and run tests, as well as links to the SIG-Windows configurations used on [TestGrid](https://testgrid.k8s.io/sig-windows). - -## Reporting Issues - -You can open issues on [GitHub](https://github.com/kubernetes/kubernetes/issues/new/choose) and assign them to SIG-Windows by commenting on the issue with `/sig windows`. You should first search the list of issues in case it was reported previously and comment with your experience on the issue and add additional logs. SIG-Windows Slack is also a great avenue to get some initial support prior to creating a ticket. - -It is important you include as much information as possible with your issue. That includes environment details, detailed steps on how to reproduce the issue, and logs. - -## Gathering Logs - -Logs are an important element of troubleshooting issues in Kubernetes. Make sure to include them any time you seek troubleshooting assistance from other contributors. - -### Collecting Networking Logs -1. On the node before creating the pod for the first time. -2. `start-bitstransfer https://raw.githubusercontent.com/Microsoft/SDN/master/Kubernetes/windows/debug/collectlogs.ps1` -3. Execute collectlogs.ps1 in a PowerShell window -4 Start the trace by running `C:\k\debug\starthnstrace.cmd` -5. Reproduce the issue -6. Run `netsh trace stop` -7. Execute collectlogs.ps1 in a PowerShell window again -8. Include in your ticket `C:\server.etl` From 4d24bba4d1d1573e00b2a1544f4d8459988a3925 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 11:20:55 -0500 Subject: [PATCH 14/15] Update README.md --- contributors/guide/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 59caa9a91..f785fd974 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -244,7 +244,7 @@ If you're looking to run e2e tests on your own infrastructure, [kubetest](https: - [Security and Disclosure Information](https://kubernetes.io/docs/reference/issues-security/security/) - check this page if you wish to report a security vulnerability. ## Contributing on Windows Node support -If you would like to contribute to the effort of supporting Windows Nodes in Kubernetes and scheduling Windows containers, we have a dedicated [reference guide](./contributing-on-windows.md). +If you would like to contribute to the effort of supporting Windows Nodes in Kubernetes and scheduling Windows containers, we have a dedicated [reference guide](../../sig-windows/contributors-guide.md.md). ## Documentation From db0a193383b85b349eacbf03874ffb0fe61e48b3 Mon Sep 17 00:00:00 2001 From: Michael Michael Date: Wed, 13 Mar 2019 11:21:47 -0500 Subject: [PATCH 15/15] Update README.md --- contributors/guide/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index f785fd974..b55e92cca 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -244,7 +244,7 @@ If you're looking to run e2e tests on your own infrastructure, [kubetest](https: - [Security and Disclosure Information](https://kubernetes.io/docs/reference/issues-security/security/) - check this page if you wish to report a security vulnerability. ## Contributing on Windows Node support -If you would like to contribute to the effort of supporting Windows Nodes in Kubernetes and scheduling Windows containers, we have a dedicated [reference guide](../../sig-windows/contributors-guide.md.md). +If you would like to contribute to the effort of supporting Windows Nodes in Kubernetes and scheduling Windows containers, we have a dedicated [reference guide](../../sig-windows/contributors-guide.md). ## Documentation