Skip to content

Commit 13eb233

Browse files
authored
Clarify V2 shims details in README
Updated the README to clarify the purpose and implementation details of the V2 shims, including corrections to the descriptions and formatting. Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>
1 parent e8caeb4 commit 13eb233

1 file changed

Lines changed: 34 additions & 42 deletions

File tree

README.md

Lines changed: 34 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -72,18 +72,11 @@ C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/window
7272

7373
The V2 shims are the rewrite of the Windows containerd shim. The V1 shim
7474
([`containerd-shim-runhcs-v1`](./cmd/containerd-shim-runhcs-v1)) is a single, monolithic
75-
binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW, process-isolated
75+
binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW (Windows Containers on Windows), process-isolated
7676
WCOW and host-process containers. In the V2 model that monolith is split into focused,
77-
per-platform shims, each backed 1:1 by a sandbox:
77+
per-platform shims, each backed 1:1 by a sandbox.
7878

79-
- [`containerd-shim-process-v2`](#containerd-shim-process-v2) — process-isolated Windows
80-
Server containers (Argons) and Host Process Containers.
81-
- [`containerd-shim-wcow-v2`](#containerd-shim-wcow-v2) — Hyper-V isolated Windows
82-
containers (UVM + Argons / Host Process Containers running inside the UVM).
83-
- [`containerd-shim-lcow-v2`](#containerd-shim-lcow-v2) — Linux Containers on Windows
84-
(UVM + Linux containers).
85-
86-
V2 shims are dropped in alongside containerd in the same way as the V1 shim, but the
79+
V2 shims are used with containerd in the same way as the V1 shim, but the
8780
API surface they expose is different. The V1 shim implemented only the containerd
8881
[Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md),
8982
and used it to manage both the sandbox lifecycle and the container/process (task)
@@ -103,48 +96,47 @@ that creates the pod; sibling workload tasks set `"io.kubernetes.cri.container-t
10396
"sandbox" *physically* corresponds to depends on the shim, and is described in each
10497
subsection below.
10598

99+
#### containerd-shim-lcow-v2
100+
101+
- **Purpose:** Runs Linux Containers on Windows (LCOW) — a Linux utility VM hosting Linux
102+
containers.
103+
- **Sandbox:** The Linux UVM. Each shim instance is backed 1:1 by a single UVM. This shim supports running
104+
*multiple pods in the same UVM*, so a single shim instance may host more than one
105+
CRI pods.
106+
- **Tasks:** Linux containers and processes running inside the UVM, identified via the
107+
same CRI annotations described above.
108+
- **Implementation:** [`./cmd/containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2).
109+
- **Build Tag:** lcow
110+
- **Platform requirement:** Windows Server 2025 (build 26100) or later.
111+
112+
#### containerd-shim-wcow-v2
113+
114+
- **Purpose:** Runs Hyper-V isolated Windows containers (WCOW) — a Windows utility VM hosting
115+
Process and/or Host Process Containers inside it.
116+
- **Sandbox:** The Windows utility VM (UVM). Each shim instance is backed 1:1 by a single UVM.
117+
- **Tasks:** the Windows containers and processes running inside the UVM, identified
118+
via the standard CRI annotations described above.
119+
- **Implementation:** coming soon.
120+
- **Build Tag:** wcow
121+
106122
#### containerd-shim-process-v2
107123

108-
- **Purpose:** runs Argons (process-isolated Windows Server containers) and Host
124+
- **Purpose:** Runs Process-isolated Windows Server containers and Host
109125
Process Containers — workloads that execute directly on the host with no utility VM.
110-
- **Sandbox:** a *pause container*. The pause container is a minimal, long-lived
126+
- **Sandbox:** A *pause container*. The pause container is a minimal, long-lived
111127
container that owns the pod's shared resources (such as the network namespace) and
112128
keeps them alive while sibling workload containers are started, stopped or replaced.
113129
This is the standard Kubernetes pod model: the pause container is the sandbox that
114130
the rest of the pod attaches to.
115131
- **Tasks:** the actual workload containers belonging to the pod, linked back to the
116132
pause via the `io.kubernetes.cri.sandbox-id` annotation.
117133
- **Implementation:** coming soon.
118-
119-
#### containerd-shim-wcow-v2
120-
121-
- **Purpose:** runs Hyper-V isolated Windows containers — a Windows utility VM hosting
122-
Argons and/or Host Process Containers inside it.
123-
- **Sandbox:** the Windows utility VM (UVM) itself, created on `RunPodSandbox` and torn
124-
down when the pod is removed. Each shim instance is backed 1:1 by a single UVM.
125-
- **Tasks:** the Windows containers and processes running inside the UVM, identified
126-
via the standard CRI annotations described above.
127-
- **Implementation:** coming soon.
128-
129-
#### containerd-shim-lcow-v2
130-
131-
- **Purpose:** runs Linux Containers on Windows — a Linux utility VM hosting Linux
132-
containers.
133-
- **Sandbox:** the Linux UVM. Unlike `containerd-shim-wcow-v2`, LCOW supports running
134-
*multiple pods in the same UVM*, so a single shim instance may host more than one
135-
CRI pod's worth of containers. This is the key behavioral difference from the WCOW
136-
V2 shim.
137-
- **Tasks:** Linux containers and processes running inside the UVM, identified via the
138-
same CRI annotations described above.
139-
- **Implementation:** [`./cmd/containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2).
140-
The sandbox service, task service and `shimdiag` service are wired up under that
141-
directory (`main.go`, `manager.go`, `service/`).
142-
- **Platform requirement:** Windows Server 2025 (build 26100) or later.
134+
- **Build Tag:** process
143135

144136
##### Building
145137

146-
The LCOW V2 shim sources are guarded by the `lcow` build tag, so the tag must be passed
147-
to `go build`:
138+
The V2 shim sources are guarded by the build tags as mentioned above, so the tag must be passed
139+
to `go build`. For example the `LCOW` shim has `lcow` tag-
148140

149141
```powershell
150142
C:\> $env:GOOS="windows"
@@ -156,8 +148,8 @@ the same as for the V1 shim.
156148

157149
##### Running unit tests
158150

159-
The shim's unit tests (and the rest of the `lcow`-tagged packages) are run with the
160-
`lcow` build tag:
151+
The shim's unit tests (and the rest of the tagged packages) are run with the
152+
shim specific build tag:
161153

162154
```powershell
163155
C:\> go test -tags lcow ./...
@@ -168,7 +160,7 @@ C:\> go test -tags lcow ./...
168160
The repository ships parity tests under [`./test/parity`](./test/parity) that feed
169161
identical inputs through the legacy V1 and the new V2 pipelines and assert that the
170162
resulting HCS ComputeSystem documents are equivalent. They live in the `test` Go
171-
module and are also built with the `lcow` tag:
163+
module and are also built with the build tag:
172164

173165
```powershell
174166
C:\> cd test

0 commit comments

Comments
 (0)