Merge pull request #30436 from ravisantoshgudimetla/windows-pods

[docs][windows]: Pod OS field update

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -126,6 +126,7 @@ different Kubernetes components.
 | `GracefulNodeShutdown` | `true` | Beta | 1.21 | |
 | `HPAContainerMetrics` | `false` | Alpha | 1.20 | |
 | `HPAScaleToZero` | `false` | Alpha | 1.16 | |
+| `IdentifyPodOS` | `false` | Alpha | 1.23 | |
 | `IndexedJob` | `false` | Alpha | 1.21 | 1.21 |
 | `IndexedJob` | `true` | Beta | 1.22 | |
 | `InTreePluginAWSUnregister` | `false` | Alpha | 1.21 | |
@@ -801,6 +802,8 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `HyperVContainer`: Enable
   [Hyper-V isolation](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container)
   for Windows containers.
+- `IdentifyPodOS`: Allows the Pod OS field to be specified. This helps in identifying the OS of the pod
+  authoritatively during the API server admission time. In Kubernetes {{< skew currentVersion >}}, the allowed values for the `pod.spec.os.name` are `windows` and `linux`.
 - `ImmutableEphemeralVolumes`: Allows for marking individual Secrets and ConfigMaps as
   immutable for better safety and performance.
 - `InTreePluginAWSUnregister`: Stops registering the aws-ebs in-tree plugin in kubelet

content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md

@@ -153,6 +153,37 @@ section refers to several key workload enablers and how they map to Windows.
   * `emptyDir` volumes
   * Named pipe host mounts
   * Resource limits
+  * OS field: 
+              {{< feature-state for_k8s_version="v1.23" state="alpha" >}}
+               `.spec.os.name` should be set to `windows` to indicate that the current Pod uses Windows containers.
+               `IdentifyPodOS` feature gate needs to be enabled for this field to be recognized and used by control plane
+               components and kubelet.
+               {{< note >}}
+              If the `IdentifyPodOS` feature gate is enabled and you set the `.spec.os.name` field to `windows`, you must not set the following fields in the `.spec` of that Pod:
+               * `spec.hostPID`
+               * `spec.hostIPC`
+               * `spec.securityContext.seLinuxOptions`
+               * `spec.securityContext.seccompProfile`
+               * `spec.securityContext.fsGroup`
+               * `spec.securityContext.fsGroupChangePolicy`
+               * `spec.securityContext.sysctls`
+               * `spec.shareProcessNamespace`
+               * `spec.securityContext.runAsUser`
+               * `spec.securityContext.runAsGroup`
+               * `spec.securityContext.supplementalGroups`
+               * `spec.containers[*].securityContext.seLinuxOptions`
+               * `spec.containers[*].securityContext.seccompProfile`
+               * `spec.containers[*].securityContext.capabilities`
+               * `spec.containers[*].securityContext.readOnlyRootFilesystem`
+               * `spec.containers[*].securityContext.privileged`
+               * `spec.containers[*].securityContext.allowPrivilegeEscalation`
+               * `spec.containers[*].securityContext.procMount`
+               * `spec.containers[*].securityContext.runAsUser`
+               * `spec.containers[*].securityContext.runAsGroup`
+
+            Note: In this table, wildcards (*) indicate all elements in a list. For example, spec.containers[*].securityContext refers to the Security Context object for all defined containers. If not, Pod API validation would fail causing admission failures.
+            {{< /note >}}
+
 * [Workload resources](/docs/concepts/workloads/controllers/) including:
   * ReplicaSet
   * Deployments

content/en/docs/setup/production-environment/windows/user-guide-windows-containers.md

@@ -160,7 +160,21 @@ Users today need to use some combination of taints and node selectors in order t
 keep Linux and Windows workloads on their respective OS-specific nodes. 
 This likely imposes a burden only on Windows users. The recommended approach is outlined below, 
 with one of its main goals being that this approach should not break compatibility for existing Linux workloads.
+ {{< note >}}
+If the `IdentifyPodOS` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is
+enabled, you can (and should) set `.spec.os.name` for a Pod to indicate the operating system
+that the containers in that Pod are designed for. For Pods that run Linux containers, set
+`.spec.os.name` to `linux`. For Pods that run Windows containers, set `.spec.os.name`
+to Windows.
 
+The scheduler does not use the value of `.spec.os.name` when assigning Pods to nodes. You should
+use normal Kubernetes mechanisms for
+[assigning pods to nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)
+to ensure that the control plane for your cluster places pods onto nodes that are running the
+appropriate operating system.
+ no effect on the scheduling of the Windows pods, so taints and tolerations and node selectors are still required
+ to ensure that the Windows pods land onto appropriate Windows nodes.
+ {{< /note >}}
 ### Ensuring OS-specific workloads land on the appropriate container host
 
 Users can ensure Windows containers can be scheduled on the appropriate host using Taints and Tolerations.