|
| 1 | +--- |
| 2 | +title: Create a Windows HostProcess Pod |
| 3 | +content_type: task |
| 4 | +weight: 20 |
| 5 | +min-kubernetes-server-version: 1.22 |
| 6 | +--- |
| 7 | + |
| 8 | +<!-- overview --> |
| 9 | + |
| 10 | +{{< feature-state for_k8s_version="v1.22" state="alpha" >}} |
| 11 | + |
| 12 | +Windows HostProcess containers enable you to run containerized |
| 13 | +workloads on a Windows host. These containers operate as |
| 14 | +normal processes but have access to the host network namespace, |
| 15 | +storage, and devices when given the appropriate user privileges. |
| 16 | +HostProcess containers can be used to deploy network plugins, |
| 17 | +storage configurations, device plugins, kube-proxy, and other |
| 18 | +components to Windows nodes without the need for dedicated proxies or |
| 19 | +the direct installation of host services. |
| 20 | + |
| 21 | +Administrative tasks such as installation of security patches, event |
| 22 | +log collection, and more can be performed without requiring cluster operators to |
| 23 | +log onto each Window node. HostProcess containers can run as any user that is |
| 24 | +available on the host or is in the domain of the host machine, allowing administrators |
| 25 | +to restrict resource access through user permissions. While neither filesystem or process |
| 26 | +isolation are supported, a new volume is created on the host upon starting the container |
| 27 | +to give it a clean and consolidated workspace. HostProcess containers can also be built on |
| 28 | +top of existing Windows base images and do not inherit the same |
| 29 | +[compatibility requirements](https://docs.microsoft.com/virtualization/windowscontainers/deploy-containers/version-compatibility) |
| 30 | +as Windows server containers, meaning that the version of the base images does not need |
| 31 | +to match that of the host. HostProcess containers also support |
| 32 | +[volume mounts](./create-hostprocess-pod#volume-mounts) within the container volume. |
| 33 | + |
| 34 | +### When should I use a Windows HostProcess container? |
| 35 | + |
| 36 | +- When you need to perform tasks which require the networking namespace of the host. |
| 37 | +HostProcess containers have access to the host's network interfaces and IP addresses. |
| 38 | +- You need access to resources on the host such as the filesystem, event logs, etc. |
| 39 | +- Installation of specific device drivers or Windows services. |
| 40 | +- Consolidation of administrative tasks and security policies. This reduces the degree of |
| 41 | +privileges needed by Windows nodes. |
| 42 | + |
| 43 | + |
| 44 | +## {{% heading "prerequisites" %}} |
| 45 | + |
| 46 | +{{% version-check %}} |
| 47 | + |
| 48 | +To enable HostProcess containers while in Alpha you need to pass the following feature gate flag to |
| 49 | +**kubelet** and **kube-apiserver**. |
| 50 | +See [Features Gates](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#overview) |
| 51 | +documentation for more details. |
| 52 | + |
| 53 | +``` |
| 54 | +--feature-gates=WindowsHostProcessContainers=true |
| 55 | +``` |
| 56 | + |
| 57 | +You can use the latest version of Containerd (v1.5.4+) with the following settings using the containerd |
| 58 | +v2 configuration. Add these annotations to any runtime configurations were you wish to enable the |
| 59 | +HostProcess container feature. |
| 60 | + |
| 61 | + |
| 62 | +``` |
| 63 | +[plugins] |
| 64 | + [plugins."io.containerd.grpc.v1.cri"] |
| 65 | + [plugins."io.containerd.grpc.v1.cri".containerd] |
| 66 | + [plugins."io.containerd.grpc.v1.cri".containerd.default_runtime] |
| 67 | + container_annotations = ["microsoft.com/hostprocess-container"] |
| 68 | + pod_annotations = ["microsoft.com/hostprocess-container"] |
| 69 | + [plugins."io.containerd.grpc.v1.cri".containerd.runtimes] |
| 70 | + [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runhcs-wcow-process] |
| 71 | + container_annotations = ["microsoft.com/hostprocess-container"] |
| 72 | + pod_annotations = ["microsoft.com/hostprocess-container"] |
| 73 | +``` |
| 74 | + |
| 75 | +The current versions of containerd ship with a version of hcsshim that does not have support. |
| 76 | +You will need to build a version of hcsshim from the main branch following the |
| 77 | +[instructions in hcsshim](https://github.com/Microsoft/hcsshim/#containerd-shim). |
| 78 | +Once the containerd shim is built you can replace the file in your contianerd installation. |
| 79 | +For example if you followed the instructions to |
| 80 | +[install containerd](/docs/setup/production-environment/container-runtimes/#containerd) |
| 81 | +replace the `containerd-shim-runhcs-v1.exe` is installed at `$Env:ProgramFiles\containerd` with the newly built shim. |
| 82 | + |
| 83 | +## Limitations |
| 84 | + |
| 85 | +- HostProcess containers require version 1.5.4 or higher of the containerd {{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}. |
| 86 | +- As of v1.22 HostProcess pods can only contain HostProcess containers. This is a current limitation |
| 87 | +of the Windows OS; non-privileged Windows containers cannot share a vNIC with the host IP namespace. |
| 88 | +- HostProcess containers run as a process on the host and do not have any degree of |
| 89 | +isolation other than resource constraints imposed on the HostProcess user account. Neither |
| 90 | +filesystem or Hyper-V isolation are supported for HostProcess containers. |
| 91 | +- Volume mounts are supported and are mounted under the container volume. |
| 92 | +See [Volume Mounts](#volume-mounts) |
| 93 | +- A limited set of host user accounts are available for HostProcess containers by default. |
| 94 | +See [Choosing a User Account](#choosing-a-user-account). |
| 95 | +- Resource limits (disk, memory, cpu count) are supported in the same fashion as processes |
| 96 | +on the host. |
| 97 | +- Both Named pipe mounts and Unix domain sockets are **not** currently supported and should instead |
| 98 | +be accessed via their path on the host (e.g. \\\\.\\pipe\\\*) |
| 99 | + |
| 100 | +## HostProcess Pod configuration requirements |
| 101 | + |
| 102 | +Enabling a Windows HostProcess pod requires setting the right configurations in the pod security |
| 103 | +configuration. Of the policies defined in the [Pod Security Standards](/docs/concepts/security/pod-security-standards) |
| 104 | +HostProcess pods are disallowed by the baseline and restricted policies. It is therefore recommended |
| 105 | +that HostProcess pods run in alignment with the privileged profile. |
| 106 | + |
| 107 | +When running under the privileged policy, here are |
| 108 | +the configurations which need to be set to enable the creation of a HostProcess pod: |
| 109 | + |
| 110 | +<table> |
| 111 | + <caption style="display:none">Privileged policy specification</caption> |
| 112 | + <tbody> |
| 113 | + <tr> |
| 114 | + <td><strong>Control</strong></td> |
| 115 | + <td><strong>Policy</strong></td> |
| 116 | + </tr> |
| 117 | + <tr> |
| 118 | + <td style="white-space: nowrap"><a href="/docs/concepts/security/pod-security-standards">Windows HostProcess</a></td> |
| 119 | + <td> |
| 120 | + <p>Windows pods offer the ability to run <a href="/docs/tasks/configure-pod-container/create-hostprocess-pod"> |
| 121 | + HostProcess containers</a> which enables privileged access to the Windows node. </p> |
| 122 | + <p><strong>Allowed Values</strong></p> |
| 123 | + <ul> |
| 124 | + <li><code>true</code></li> |
| 125 | + </ul> |
| 126 | + </td> |
| 127 | + </tr> |
| 128 | + <tr> |
| 129 | + <td style="white-space: nowrap"><a href="/docs/concepts/security/pod-security-standards">Host Networking</a></td> |
| 130 | + <td> |
| 131 | + <p>Will be in host network by default initially. Support |
| 132 | + to set network to a different compartment may be desirable in |
| 133 | + the future.</p> |
| 134 | + <p><strong>Allowed Values</strong></p> |
| 135 | + <ul> |
| 136 | + <li><code>true</code></li> |
| 137 | + </ul> |
| 138 | + </td> |
| 139 | + </tr> |
| 140 | + <tr> |
| 141 | + <td style="white-space: nowrap"><a href="/docs/tasks/configure-pod-container/configure-runasusername/">runAsUsername</a></td> |
| 142 | + <td> |
| 143 | + <p>Specification of which user the HostProcess container should run as is required for the pod spec.</p> |
| 144 | + <p><strong>Allowed Values</strong></p> |
| 145 | + <ul> |
| 146 | + <li><code>NT AUTHORITY\SYSTEM</code></li> |
| 147 | + <li><code>NT AUTHORITY\Local service</code></li> |
| 148 | + <li><code>NT AUTHORITY\NetworkService</code></li> |
| 149 | + </ul> |
| 150 | + </td> |
| 151 | + </tr> |
| 152 | + <tr> |
| 153 | + <td style="white-space: nowrap"><a href="/docs/concepts/security/pod-security-standards">runAsNonRoot</a></td> |
| 154 | + <td> |
| 155 | + <p>Because HostProcess containers have privileged access to the host, the <tt>runAsNonRoot</tt> field cannot be set to true.</p> |
| 156 | + <p><strong>Allowed Values</strong></p> |
| 157 | + <ul> |
| 158 | + <li>Undefined/Nil</li> |
| 159 | + <li><code>false</code></li> |
| 160 | + </ul> |
| 161 | + </td> |
| 162 | + </tr> |
| 163 | + </tbody> |
| 164 | +</table> |
| 165 | + |
| 166 | +### Example Manifest (excerpt) |
| 167 | + |
| 168 | +```yaml |
| 169 | +spec: |
| 170 | + securityContext: |
| 171 | + windowsOptions: |
| 172 | + hostProcess: true |
| 173 | + runAsUserName: "NT AUTHORITY\\Local service" |
| 174 | + hostNetwork: true |
| 175 | + containers: |
| 176 | + - name: test |
| 177 | + image: image1:latest |
| 178 | + command: |
| 179 | + - ping |
| 180 | + - -t |
| 181 | + - 127.0.0.1 |
| 182 | + nodeSelector: |
| 183 | + "kubernetes.io/os": windows |
| 184 | +``` |
| 185 | +
|
| 186 | +## Volume Mounts |
| 187 | +
|
| 188 | +HostProcess containers support the ability to mount volumes within the container volume space. |
| 189 | +Applications running inside the container can access volume mounts directly via relative or |
| 190 | +absolute paths. An environment variable `$CONTAINER_SANDBOX_MOUNT_POINT` is set upon container |
| 191 | +creation and provides the absolute host path to the container volume. Relative paths are based |
| 192 | +upon the `Pod.containers.volumeMounts.mountPath` configuration. |
| 193 | + |
| 194 | +### Example {#volume-mount-example} |
| 195 | + |
| 196 | +To access service account tokens the following path structures are supported within the container: |
| 197 | + |
| 198 | +`.\var\run\secrets\kubernetes.io\serviceaccount\` |
| 199 | +
|
| 200 | +`$CONTAINER_SANDBOX_MOUNT_POINT\var\run\secrets\kubernetes.io\serviceaccount\` |
| 201 | + |
| 202 | +## Choosing a User Account |
| 203 | + |
| 204 | +HostProcess containers support the ability to run as one of three supported Windows service accounts: |
| 205 | + |
| 206 | +- **[LocalSystem](https://docs.microsoft.com/en-us/windows/win32/services/localsystem-account)** |
| 207 | +- **[LocalService](https://docs.microsoft.com/en-us/windows/win32/services/localservice-account)** |
| 208 | +- **[NetworkService](https://docs.microsoft.com/en-us/windows/win32/services/networkservice-account)** |
| 209 | + |
| 210 | +You should select an appropriate Windows service account for each HostProcess |
| 211 | +container, aiming to limit the degree of privileges so as to avoid accidental (or even |
| 212 | +malicious) damage to the host. The LocalSystem service account has the highest level |
| 213 | +of privilege of the three and should be used only if absolutely necessary. Where possible, |
| 214 | +use the LocalService service account as it is the least privileged of the three options. |
0 commit comments