Skip to content

Commit 2569335

Browse files
Copilotrawahars
andauthored
Document LCOW V2 shim build and test instructions in README
Agent-Logs-Url: https://github.com/microsoft/hcsshim/sessions/e7380912-54b3-452e-9960-469c319b8394 Co-authored-by: rawahars <65640262+rawahars@users.noreply.github.com>
1 parent 635e456 commit 2569335

1 file changed

Lines changed: 52 additions & 0 deletions

File tree

README.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,58 @@ To trial using the shim out with ctr.exe:
6868
C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!"
6969
```
7070

71+
### Containerd Shim V2 (LCOW)
72+
73+
`containerd-shim-lcow-v2` is the V2 rewrite of the Windows containerd shim. The V1 shim
74+
([`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
76+
WCOW and host-process containers. In the V2 model that monolith is split into focused,
77+
per-platform shims. Today only the LCOW shim
78+
([`containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2)) has been published; additional
79+
shims for the other platforms will follow.
80+
81+
From a caller's perspective, V2 shims implement the same containerd
82+
[Runtime V2 API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md)
83+
as the V1 shim and are dropped in alongside containerd in the same way. Internally the
84+
V2 shim is restructured around a sandbox / task / shimdiag service split, with the LCOW
85+
shim instance backed 1:1 by a Linux utility VM.
86+
87+
The LCOW V2 shim requires Windows Server 2025 (build 26100) or later.
88+
89+
#### Building
90+
91+
The LCOW V2 shim sources are guarded by the `lcow` build tag, so the tag must be passed
92+
to `go build`:
93+
94+
```powershell
95+
C:\> $env:GOOS="windows"
96+
C:\> go build -tags lcow .\cmd\containerd-shim-lcow-v2
97+
```
98+
99+
Place the resulting `containerd-shim-lcow-v2.exe` in the same directory as `containerd.exe`,
100+
the same as for the V1 shim.
101+
102+
#### Running unit tests
103+
104+
The shim's unit tests (and the rest of the `lcow`-tagged packages) are run with the
105+
`lcow` build tag:
106+
107+
```powershell
108+
C:\> go test -tags lcow ./...
109+
```
110+
111+
#### Running parity tests
112+
113+
The repository ships parity tests under [`./test/parity`](./test/parity) that feed
114+
identical inputs through the legacy V1 and the new V2 pipelines and assert that the
115+
resulting HCS ComputeSystem documents are equivalent. They live in the `test` Go
116+
module and are also built with the `lcow` tag:
117+
118+
```powershell
119+
C:\> cd test
120+
C:\> go test -tags lcow ./parity/...
121+
```
122+
71123
## Contributing
72124

73125
This project welcomes contributions and suggestions. Most contributions require you to agree to a

0 commit comments

Comments
 (0)