Create a Windows HostProcess Pod

FEATURE STATE: Kubernetes v1.22 [alpha]

Windows HostProcess containers enable you to run containerized workloads on a Windows host. These containers operate as normal processes but have access to the host network namespace, storage, and devices when given the appropriate user privileges. HostProcess containers can be used to deploy network plugins, storage configurations, device plugins, kube-proxy, and other components to Windows nodes without the need for dedicated proxies or the direct installation of host services.

Administrative tasks such as installation of security patches, event 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 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 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 top of existing Windows base images and do not inherit the same compatibility requirements 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 volume mounts within the container volume.

When should I use a Windows HostProcess container?

• 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.
• You need access to resources on the host such as the filesystem, event logs, etc.
• Installation of specific device drivers or Windows services.
• Consolidation of administrative tasks and security policies. This reduces the degree of privileges needed by Windows nodes.

Before you begin

Your Kubernetes server must be at or later than version 1.22. To check the version, enter kubectl version.

To enable HostProcess containers while in Alpha you need to pass the following feature gate flag to kubelet and kube-apiserver. See Features Gates documentation for more details.

--feature-gates=WindowsHostProcessContainers=true

You can use the latest version of Containerd (v1.5.4+) with the following settings using the containerd v2 configuration. Add these annotations to any runtime configurations were you wish to enable the HostProcess container feature.

[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. 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 replace the containerd-shim-runhcs-v1.exe is installed at $Env:ProgramFiles\containerd with the newly built shim.

Limitations

• HostProcess containers require version 1.5.4 or higher of the containerd 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.
• 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 filesystem or Hyper-V isolation are supported for HostProcess containers.
• Volume mounts are supported and are mounted under the container volume. See Volume Mounts
• A limited set of host user accounts are available for HostProcess containers by default. See Choosing a User Account.
• Resource limits (disk, memory, cpu count) are supported in the same fashion as processes on the host.
• 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\*)

HostProcess Pod configuration requirements

Enabling a Windows HostProcess pod requires setting the right configurations in the pod security configuration. Of the policies defined in the Pod Security Standards HostProcess pods are disallowed by the baseline and restricted policies. It is therefore recommended that HostProcess pods run in alignment with the privileged profile.

When running under the privileged policy, here are the configurations which need to be set to enable the creation of a HostProcess pod:

Example Manifest (excerpt)

spec:
  securityContext:
    windowsOptions:
      hostProcess: true
      runAsUserName: "NT AUTHORITY\\Local service"
  hostNetwork: true
  containers:
  - name: test
    image: image1:latest
    command:
      - ping
      - -t
      - 127.0.0.1
  nodeSelector:
    "kubernetes.io/os": windows

Volume Mounts

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 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 upon the Pod.containers.volumeMounts.mountPath configuration.

Example

To access service account tokens the following path structures are supported within the container:

.\var\run\secrets\kubernetes.io\serviceaccount\

$CONTAINER_SANDBOX_MOUNT_POINT\var\run\secrets\kubernetes.io\serviceaccount\

Choosing a User Account

HostProcess containers support the ability to run as one of three supported Windows service accounts:

• LocalSystem
• LocalService
• NetworkService

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 malicious) damage to the host. The LocalSystem service account has the highest level of privilege of the three and should be used only if absolutely necessary. Where possible, use the LocalService service account as it is the least privileged of the three options.

Last modified August 05, 2021 at 11:54 AM PST : Replace with relative path (8f301ea37)