kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

1.22 Windows HostProcess containers update (#30699) 

* Transferred applicable modifications for 1.23 over to 1.22.

* kublet -> kubelet

* Update content/en/docs/tasks/configure-pod-container/create-hostprocess-pod.md

Co-authored-by: Mark Rossetti <marosset@microsoft.com>

Co-authored-by: Mark Rossetti <marosset@microsoft.com>
This commit is contained in:
Brandon Smith 2021-12-05 20:02:33 -08:00 committed by GitHub
parent 798aae5127
commit 1c90494c38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 59 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
content/en/docs/tasks/configure-pod-container/create-hostprocess-pod.md
View File

@ -9,100 +9,80 @@ min-kubernetes-server-version: 1.22
{{< feature-state for_k8s_version="v1.22" state="alpha" >}} {{< feature-state for_k8s_version="v1.22" state="alpha" >}}
Windows HostProcess containers enable you to run containerized Windows HostProcess containers enable you to run containerized
workloads on a Windows host. These containers operate as workloads on a Windows host. These containers operate as
normal processes but have access to the host network namespace, normal processes but have access to the host network namespace,
storage, and devices when given the appropriate user privileges. storage, and devices when given the appropriate user privileges.
HostProcess containers can be used to deploy network plugins, HostProcess containers can be used to deploy network plugins,
storage configurations, device plugins, kube-proxy, and other storage configurations, device plugins, kube-proxy, and other
components to Windows nodes without the need for dedicated proxies or components to Windows nodes without the need for dedicated proxies or
the direct installation of host services. the direct installation of host services.
Administrative tasks such as installation of security patches, event Administrative tasks such as installation of security patches, event
log collection, and more can be performed without requiring cluster operators to log collection, and more can be performed without requiring cluster operators to
log onto each Window node. HostProcess containers can run as any user that is log onto each Window node. HostProcess containers can run as any user that is
available on the host or is in the domain of the host machine, allowing administrators available on the host or is in the domain of the host machine, allowing administrators
to restrict resource access through user permissions. While neither filesystem or process to restrict resource access through user permissions. While neither filesystem or process
isolation are supported, a new volume is created on the host upon starting the container isolation are supported, a new volume is created on the host upon starting the container
to give it a clean and consolidated workspace. HostProcess containers can also be built on to give it a clean and consolidated workspace. HostProcess containers can also be built on
top of existing Windows base images and do not inherit the same top of existing Windows base images and do not inherit the same
[compatibility requirements](https://docs.microsoft.com/virtualization/windowscontainers/deploy-containers/version-compatibility) [compatibility requirements](https://docs.microsoft.com/virtualization/windowscontainers/deploy-containers/version-compatibility)
as Windows server containers, meaning that the version of the base images does not need as Windows server containers, meaning that the version of the base images does not need
to match that of the host. HostProcess containers also support to match that of the host. It is, however, recommended that you use the same base image
version as your Windows Server container workloads to ensure you do not have any unused
images taking up space on the node. HostProcess containers also support
[volume mounts](./create-hostprocess-pod#volume-mounts) within the container volume. [volume mounts](./create-hostprocess-pod#volume-mounts) within the container volume.
### When should I use a Windows HostProcess container? ### When should I use a Windows HostProcess container?
- When you need to perform tasks which require the networking namespace of the host. - When you need to perform tasks which require the networking namespace of the host.
HostProcess containers have access to the host's network interfaces and IP addresses. HostProcess containers have access to the host's network interfaces and IP addresses.
- You need access to resources on the host such as the filesystem, event logs, etc. - You need access to resources on the host such as the filesystem, event logs, etc.
- Installation of specific device drivers or Windows services. - Installation of specific device drivers or Windows services.
- Consolidation of administrative tasks and security policies. This reduces the degree of - Consolidation of administrative tasks and security policies. This reduces the degree of
privileges needed by Windows nodes. privileges needed by Windows nodes.
## {{% heading "prerequisites" %}} ## {{% heading "prerequisites" %}}% version-check %}}
{{% version-check %}} To enable HostProcess containers while in Alpha you need to
pass the following feature gate flag to
To enable HostProcess containers while in Alpha you need to pass the following feature gate flag to **kubelet** and **kube-apiserver**.
**kubelet** and **kube-apiserver**.
See [Features Gates](/docs/reference/command-line-tools-reference/feature-gates/#overview) See [Features Gates](/docs/reference/command-line-tools-reference/feature-gates/#overview)
documentation for more details. documentation for more details.
``` ```powershell
--feature-gates=WindowsHostProcessContainers=true --feature-gates=WindowsHostProcessContainers=true
``` ```
You can use the latest version of Containerd (v1.5.4+) with the following settings using the containerd The kubelet will communicate with containerd directly by
v2 configuration. Add these annotations to any runtime configurations were you wish to enable the passing the hostprocess flag via CRI. You can use the
HostProcess container feature. latest version of containerd (v1.6+) to run HostProcess containers.
[How to install containerd.](/docs/setup/production-environment/container-runtimes/#containerd)
```
[plugins]
[plugins."io.containerd.grpc.v1.cri"]
[plugins."io.containerd.grpc.v1.cri".containerd]
[plugins."io.containerd.grpc.v1.cri".containerd.default_runtime]
container_annotations = ["microsoft.com/hostprocess-container"]
pod_annotations = ["microsoft.com/hostprocess-container"]
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runhcs-wcow-process]
container_annotations = ["microsoft.com/hostprocess-container"]
pod_annotations = ["microsoft.com/hostprocess-container"]
```
The current versions of containerd ship with a version of hcsshim that does not have support.
You will need to build a version of hcsshim from the main branch following the
[instructions in hcsshim](https://github.com/Microsoft/hcsshim/#containerd-shim).
Once the containerd shim is built you can replace the file in your contianerd installation.
For example if you followed the instructions to
[install containerd](/docs/setup/production-environment/container-runtimes/#containerd)
replace the `containerd-shim-runhcs-v1.exe` is installed at `$Env:ProgramFiles\containerd` with the newly built shim.
## Limitations ## Limitations
- HostProcess containers require version 1.5.4 or higher of the containerd {{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}. - HostProcess containers require containerd 1.6 or higher for the
- As of v1.22 HostProcess pods can only contain HostProcess containers. This is a current limitation {{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}.
- As of v1.22 HostProcess pods can only contain HostProcess containers. This is a current limitation
of the Windows OS; non-privileged Windows containers cannot share a vNIC with the host IP namespace. of the Windows OS; non-privileged Windows containers cannot share a vNIC with the host IP namespace.
- HostProcess containers run as a process on the host and do not have any degree of - HostProcess containers run as a process on the host and do not have any degree of
isolation other than resource constraints imposed on the HostProcess user account. Neither isolation other than resource constraints imposed on the HostProcess user account. Neither
filesystem or Hyper-V isolation are supported for HostProcess containers. filesystem or Hyper-V isolation are supported for HostProcess containers.
- Volume mounts are supported and are mounted under the container volume. - Volume mounts are supported and are mounted under the container volume. See [Volume Mounts](#volume-mounts)
See [Volume Mounts](#volume-mounts) - A limited set of host user accounts are available for HostProcess containers by default.
- A limited set of host user accounts are available for HostProcess containers by default.
See [Choosing a User Account](#choosing-a-user-account). See [Choosing a User Account](#choosing-a-user-account).
- Resource limits (disk, memory, cpu count) are supported in the same fashion as processes - Resource limits (disk, memory, cpu count) are supported in the same fashion as processes
on the host. on the host.
- Both Named pipe mounts and Unix domain sockets are **not** currently supported and should instead - Both Named pipe mounts and Unix domain sockets are **not** currently supported and should instead
be accessed via their path on the host (e.g. \\\\.\\pipe\\\*) be accessed via their path on the host (e.g. \\\\.\\pipe\\\*)
## HostProcess Pod configuration requirements ## HostProcess Pod configuration requirements
Enabling a Windows HostProcess pod requires setting the right configurations in the pod security Enabling a Windows HostProcess pod requires setting the right configurations in the pod security
configuration. Of the policies defined in the [Pod Security Standards](/docs/concepts/security/pod-security-standards) configuration. Of the policies defined in the [Pod Security Standards](/docs/concepts/security/pod-security-standards)
HostProcess pods are disallowed by the baseline and restricted policies. It is therefore recommended HostProcess pods are disallowed by the baseline and restricted policies. It is therefore recommended
that HostProcess pods run in alignment with the privileged profile. that HostProcess pods run in alignment with the privileged profile.
When running under the privileged policy, here are When running under the privileged policy, here are
the configurations which need to be set to enable the creation of a HostProcess pod: the configurations which need to be set to enable the creation of a HostProcess pod:
@ -185,10 +165,10 @@ spec:
## Volume Mounts ## Volume Mounts
HostProcess containers support the ability to mount volumes within the container volume space. HostProcess containers support the ability to mount volumes within the container volume space.
Applications running inside the container can access volume mounts directly via relative or Applications running inside the container can access volume mounts directly via relative or
absolute paths. An environment variable `$CONTAINER_SANDBOX_MOUNT_POINT` is set upon container absolute paths. An environment variable `$CONTAINER_SANDBOX_MOUNT_POINT` is set upon container
creation and provides the absolute host path to the container volume. Relative paths are based creation and provides the absolute host path to the container volume. Relative paths are based
upon the `Pod.containers.volumeMounts.mountPath` configuration. upon the `Pod.containers.volumeMounts.mountPath` configuration.
### Example {#volume-mount-example} ### Example {#volume-mount-example}
@ -199,13 +179,22 @@ To access service account tokens the following path structures are supported wit
`$CONTAINER_SANDBOX_MOUNT_POINT\var\run\secrets\kubernetes.io\serviceaccount\` `$CONTAINER_SANDBOX_MOUNT_POINT\var\run\secrets\kubernetes.io\serviceaccount\`
## Resource Limits
Resource limits (disk, memory, cpu count) are applied to the job and are job wide.
For example, with a limit of 10MB set, the memory allocated for any HostProcess job object
will be capped at 10MB. This is the same behavior as other Windows container types.
These limits would be specified the same way they are currently for whatever orchestrator
or runtime is being used. The only difference is in the disk resource usage calculation
used for resource tracking due to the difference in how HostProcess containers are bootstrapped.
## Choosing a User Account ## Choosing a User Account
HostProcess containers support the ability to run as one of three supported Windows service accounts: HostProcess containers support the ability to run as one of three supported Windows service accounts:
- **[LocalSystem](https://docs.microsoft.com/en-us/windows/win32/services/localsystem-account)** - **[LocalSystem](https://docs.microsoft.com/windows/win32/services/localsystem-account)**
- **[LocalService](https://docs.microsoft.com/en-us/windows/win32/services/localservice-account)** - **[LocalService](https://docs.microsoft.com/windows/win32/services/localservice-account)**
- **[NetworkService](https://docs.microsoft.com/en-us/windows/win32/services/networkservice-account)** - **[NetworkService](https://docs.microsoft.com/windows/win32/services/networkservice-account)**
You should select an appropriate Windows service account for each HostProcess You should select an appropriate Windows service account for each HostProcess
container, aiming to limit the degree of privileges so as to avoid accidental (or even container, aiming to limit the degree of privileges so as to avoid accidental (or even