From 5ac7ec0be8ea07aafb748a40e4456eefb340731b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 4 May 2026 12:44:53 +0000 Subject: [PATCH 1/6] Initial plan From 86a8073dd556c4c3cf49213f7aa50ba8487a656c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 4 May 2026 12:47:54 +0000 Subject: [PATCH 2/6] 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> --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/README.md b/README.md index ae66682637..ab55de4f3a 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,58 @@ To trial using the shim out with ctr.exe: C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!" ``` +### Containerd Shim V2 (LCOW) + +`containerd-shim-lcow-v2` is the V2 rewrite of the Windows containerd shim. The V1 shim +([`containerd-shim-runhcs-v1`](./cmd/containerd-shim-runhcs-v1)) is a single, monolithic +binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW, process-isolated +WCOW and host-process containers. In the V2 model that monolith is split into focused, +per-platform shims. Today only the LCOW shim +([`containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2)) has been published; additional +shims for the other platforms will follow. + +From a caller's perspective, V2 shims implement the same containerd +[Runtime V2 API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md) +as the V1 shim and are dropped in alongside containerd in the same way. Internally the +V2 shim is restructured around a sandbox / task / shimdiag service split, with the LCOW +shim instance backed 1:1 by a Linux utility VM. + +The LCOW V2 shim requires Windows Server 2025 (build 26100) or later. + +#### Building + +The LCOW V2 shim sources are guarded by the `lcow` build tag, so the tag must be passed +to `go build`: + +```powershell +C:\> $env:GOOS="windows" +C:\> go build -tags lcow .\cmd\containerd-shim-lcow-v2 +``` + +Place the resulting `containerd-shim-lcow-v2.exe` in the same directory as `containerd.exe`, +the same as for the V1 shim. + +#### Running unit tests + +The shim's unit tests (and the rest of the `lcow`-tagged packages) are run with the +`lcow` build tag: + +```powershell +C:\> go test -tags lcow ./... +``` + +#### Running parity tests + +The repository ships parity tests under [`./test/parity`](./test/parity) that feed +identical inputs through the legacy V1 and the new V2 pipelines and assert that the +resulting HCS ComputeSystem documents are equivalent. They live in the `test` Go +module and are also built with the `lcow` tag: + +```powershell +C:\> cd test +C:\> go test -tags lcow ./parity/... +``` + ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a From fde33d851f16e100b9ecb56ed0aad2fe1f1afba3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 4 May 2026 12:58:29 +0000 Subject: [PATCH 3/6] docs: clarify V1 vs V2 shim API split (Sandbox + Task) Agent-Logs-Url: https://github.com/microsoft/hcsshim/sessions/17ff81be-962e-4625-8805-33cb1bc244b9 Co-authored-by: rawahars <65640262+rawahars@users.noreply.github.com> --- README.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ab55de4f3a..f2275469c8 100644 --- a/README.md +++ b/README.md @@ -78,11 +78,19 @@ per-platform shims. Today only the LCOW shim ([`containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2)) has been published; additional shims for the other platforms will follow. -From a caller's perspective, V2 shims implement the same containerd -[Runtime V2 API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md) -as the V1 shim and are dropped in alongside containerd in the same way. Internally the -V2 shim is restructured around a sandbox / task / shimdiag service split, with the LCOW -shim instance backed 1:1 by a Linux utility VM. +V2 shims are dropped in alongside containerd in the same way as the V1 shim, but the +API surface they expose is different. The V1 shim implemented only the containerd +[Task API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md), +and used it to manage both the utility VM (sandbox) lifecycle and the container/process +(task) lifecycle through a single service. The V2 shim instead splits these +responsibilities across the two APIs that containerd now provides for this purpose: +the [Sandbox API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md#sandbox-api) +is used to manage the utility VM, while the +[Task API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md#task-api) +is used to manage containers and processes running inside it. Internally the LCOW V2 +shim implements these as separate sandbox and task services (alongside an auxiliary +`shimdiag` service used for diagnostics), with each shim instance backed 1:1 by a +Linux utility VM. The LCOW V2 shim requires Windows Server 2025 (build 26100) or later. From 221d63d3c3e090a8279dd5b4474fcac673e0f3cb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 4 May 2026 13:31:18 +0000 Subject: [PATCH 4/6] docs: fix containerd Runtime V2 / Sandbox API doc links Agent-Logs-Url: https://github.com/microsoft/hcsshim/sessions/393701a4-b956-481b-8a8a-8eaefcc7c445 Co-authored-by: rawahars <65640262+rawahars@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f2275469c8..503c895239 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ delta.tar.gz initrd.img rootfs.tar.gz ### Containerd Shim -For info on the [Runtime V2 API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md). +For info on the [Runtime V2 API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md). Contrary to the typical Linux architecture of shim -> runc, the runhcs shim is used both to launch and manage the lifetime of containers. @@ -80,13 +80,13 @@ shims for the other platforms will follow. V2 shims are dropped in alongside containerd in the same way as the V1 shim, but the API surface they expose is different. The V1 shim implemented only the containerd -[Task API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md), +[Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md), and used it to manage both the utility VM (sandbox) lifecycle and the container/process (task) lifecycle through a single service. The V2 shim instead splits these responsibilities across the two APIs that containerd now provides for this purpose: -the [Sandbox API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md#sandbox-api) +the [Sandbox API](https://github.com/containerd/containerd/blob/main/docs/sandbox-api.md) is used to manage the utility VM, while the -[Task API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md#task-api) +[Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md) is used to manage containers and processes running inside it. Internally the LCOW V2 shim implements these as separate sandbox and task services (alongside an auxiliary `shimdiag` service used for diagnostics), with each shim instance backed 1:1 by a From be280360034d04ddbb756eec81e456b2d473bd62 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 6 May 2026 15:40:23 +0000 Subject: [PATCH 5/6] README: restructure Containerd Shim V2 section to cover all three shims Agent-Logs-Url: https://github.com/microsoft/hcsshim/sessions/198310fe-d2c4-4b83-9e54-7bb35706d579 Co-authored-by: rawahars <65640262+rawahars@users.noreply.github.com> --- README.md | 87 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 67 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 503c895239..19e34cd8ed 100644 --- a/README.md +++ b/README.md @@ -68,33 +68,80 @@ To trial using the shim out with ctr.exe: C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!" ``` -### Containerd Shim V2 (LCOW) +### Containerd Shim V2 -`containerd-shim-lcow-v2` is the V2 rewrite of the Windows containerd shim. The V1 shim +The V2 shims are the rewrite of the Windows containerd shim. The V1 shim ([`containerd-shim-runhcs-v1`](./cmd/containerd-shim-runhcs-v1)) is a single, monolithic binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW, process-isolated WCOW and host-process containers. In the V2 model that monolith is split into focused, -per-platform shims. Today only the LCOW shim -([`containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2)) has been published; additional -shims for the other platforms will follow. +per-platform shims, each backed 1:1 by a sandbox: + +- [`containerd-shim-process-v2`](#containerd-shim-process-v2) — process-isolated Windows + Server containers (Argons) and Host Process Containers. +- [`containerd-shim-wcow-v2`](#containerd-shim-wcow-v2) — Hyper-V isolated Windows + containers (UVM + Argons / Host Process Containers running inside the UVM). +- [`containerd-shim-lcow-v2`](#containerd-shim-lcow-v2) — Linux Containers on Windows + (UVM + Linux containers). V2 shims are dropped in alongside containerd in the same way as the V1 shim, but the API surface they expose is different. The V1 shim implemented only the containerd [Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md), -and used it to manage both the utility VM (sandbox) lifecycle and the container/process -(task) lifecycle through a single service. The V2 shim instead splits these -responsibilities across the two APIs that containerd now provides for this purpose: -the [Sandbox API](https://github.com/containerd/containerd/blob/main/docs/sandbox-api.md) -is used to manage the utility VM, while the +and used it to manage both the sandbox lifecycle and the container/process (task) +lifecycle through a single service. Each V2 shim instead splits these responsibilities +across the two APIs that containerd now provides for this purpose: the +[Sandbox API](https://github.com/containerd/containerd/blob/main/docs/sandbox-api.md) +is used to manage the sandbox, while the [Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md) -is used to manage containers and processes running inside it. Internally the LCOW V2 -shim implements these as separate sandbox and task services (alongside an auxiliary -`shimdiag` service used for diagnostics), with each shim instance backed 1:1 by a -Linux utility VM. - -The LCOW V2 shim requires Windows Server 2025 (build 26100) or later. - -#### Building +is used to manage containers and processes running inside it. Internally each V2 shim +implements these as separate sandbox and task services, alongside an auxiliary +`shimdiag` service used for diagnostics. + +All three shims honor the same CRI pod model. A task annotated with +`"io.kubernetes.cri.container-type": "sandbox"` is treated as the pause/infra container +that creates the pod; sibling workload tasks set `"io.kubernetes.cri.container-type": +"container"` and reference their pause via `"io.kubernetes.cri.sandbox-id"`. What a +"sandbox" *physically* corresponds to depends on the shim, and is described in each +subsection below. + +#### containerd-shim-process-v2 + +- **Purpose:** runs Argons (process-isolated Windows Server containers) and Host + Process Containers — workloads that execute directly on the host with no utility VM. +- **Sandbox:** a *pause container*. The pause container is a minimal, long-lived + container that owns the pod's shared resources (such as the network namespace) and + keeps them alive while sibling workload containers are started, stopped or replaced. + This is the standard Kubernetes pod model: the pause container is the sandbox that + the rest of the pod attaches to. +- **Tasks:** the actual workload containers belonging to the pod, linked back to the + pause via the `io.kubernetes.cri.sandbox-id` annotation. +- **Implementation:** coming soon. + +#### containerd-shim-wcow-v2 + +- **Purpose:** runs Hyper-V isolated Windows containers — a Windows utility VM hosting + Argons and/or Host Process Containers inside it. +- **Sandbox:** the Windows utility VM (UVM) itself, created on `RunPodSandbox` and torn + down when the pod is removed. Each shim instance is backed 1:1 by a single UVM. +- **Tasks:** the Windows containers and processes running inside the UVM, identified + via the standard CRI annotations described above. +- **Implementation:** coming soon. + +#### containerd-shim-lcow-v2 + +- **Purpose:** runs Linux Containers on Windows — a Linux utility VM hosting Linux + containers. +- **Sandbox:** the Linux UVM. Unlike `containerd-shim-wcow-v2`, LCOW supports running + *multiple pods in the same UVM*, so a single shim instance may host more than one + CRI pod's worth of containers. This is the key behavioral difference from the WCOW + V2 shim. +- **Tasks:** Linux containers and processes running inside the UVM, identified via the + same CRI annotations described above. +- **Implementation:** [`./cmd/containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2). + The sandbox service, task service and `shimdiag` service are wired up under that + directory (`main.go`, `manager.go`, `service/`). +- **Platform requirement:** Windows Server 2025 (build 26100) or later. + +##### Building The LCOW V2 shim sources are guarded by the `lcow` build tag, so the tag must be passed to `go build`: @@ -107,7 +154,7 @@ C:\> go build -tags lcow .\cmd\containerd-shim-lcow-v2 Place the resulting `containerd-shim-lcow-v2.exe` in the same directory as `containerd.exe`, the same as for the V1 shim. -#### Running unit tests +##### Running unit tests The shim's unit tests (and the rest of the `lcow`-tagged packages) are run with the `lcow` build tag: @@ -116,7 +163,7 @@ The shim's unit tests (and the rest of the `lcow`-tagged packages) are run with C:\> go test -tags lcow ./... ``` -#### Running parity tests +##### Running parity tests The repository ships parity tests under [`./test/parity`](./test/parity) that feed identical inputs through the legacy V1 and the new V2 pipelines and assert that the From c04a42a39abe6bcb36103454cf2832c85dac001b Mon Sep 17 00:00:00 2001 From: Harsh Rawat Date: Thu, 7 May 2026 00:56:14 +0530 Subject: [PATCH 6/6] 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 --- README.md | 76 +++++++++++++++++++++++++------------------------------ 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 19e34cd8ed..7610b56027 100644 --- a/README.md +++ b/README.md @@ -72,18 +72,11 @@ C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/window The V2 shims are the rewrite of the Windows containerd shim. The V1 shim ([`containerd-shim-runhcs-v1`](./cmd/containerd-shim-runhcs-v1)) is a single, monolithic -binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW, process-isolated +binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW (Windows Containers on Windows), process-isolated WCOW and host-process containers. In the V2 model that monolith is split into focused, -per-platform shims, each backed 1:1 by a sandbox: +per-platform shims, each backed 1:1 by a sandbox. -- [`containerd-shim-process-v2`](#containerd-shim-process-v2) — process-isolated Windows - Server containers (Argons) and Host Process Containers. -- [`containerd-shim-wcow-v2`](#containerd-shim-wcow-v2) — Hyper-V isolated Windows - containers (UVM + Argons / Host Process Containers running inside the UVM). -- [`containerd-shim-lcow-v2`](#containerd-shim-lcow-v2) — Linux Containers on Windows - (UVM + Linux containers). - -V2 shims are dropped in alongside containerd in the same way as the V1 shim, but the +V2 shims are used with containerd in the same way as the V1 shim, but the API surface they expose is different. The V1 shim implemented only the containerd [Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md), and used it to manage both the sandbox lifecycle and the container/process (task) @@ -103,11 +96,34 @@ that creates the pod; sibling workload tasks set `"io.kubernetes.cri.container-t "sandbox" *physically* corresponds to depends on the shim, and is described in each subsection below. +#### containerd-shim-lcow-v2 + +- **Purpose:** Runs Linux Containers on Windows (LCOW) — a Linux utility VM hosting Linux + containers. +- **Sandbox:** The Linux UVM. Each shim instance is backed 1:1 by a single UVM. This shim supports running + *multiple pods in the same UVM*, so a single shim instance may host more than one + CRI pods. +- **Tasks:** Linux containers and processes running inside the UVM, identified via the + same CRI annotations described above. +- **Implementation:** [`./cmd/containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2). +- **Build Tag:** lcow +- **Platform requirement:** Windows Server 2025 (build 26100) or later. + +#### containerd-shim-wcow-v2 + +- **Purpose:** Runs Hyper-V isolated Windows containers (WCOW) — a Windows utility VM hosting + Process and/or Host Process Containers inside it. +- **Sandbox:** The Windows utility VM (UVM). Each shim instance is backed 1:1 by a single UVM. +- **Tasks:** the Windows containers and processes running inside the UVM, identified + via the standard CRI annotations described above. +- **Implementation:** coming soon. +- **Build Tag:** wcow + #### containerd-shim-process-v2 -- **Purpose:** runs Argons (process-isolated Windows Server containers) and Host +- **Purpose:** Runs Process-isolated Windows Server containers and Host Process Containers — workloads that execute directly on the host with no utility VM. -- **Sandbox:** a *pause container*. The pause container is a minimal, long-lived +- **Sandbox:** A *pause container*. The pause container is a minimal, long-lived container that owns the pod's shared resources (such as the network namespace) and keeps them alive while sibling workload containers are started, stopped or replaced. This is the standard Kubernetes pod model: the pause container is the sandbox that @@ -115,36 +131,12 @@ subsection below. - **Tasks:** the actual workload containers belonging to the pod, linked back to the pause via the `io.kubernetes.cri.sandbox-id` annotation. - **Implementation:** coming soon. - -#### containerd-shim-wcow-v2 - -- **Purpose:** runs Hyper-V isolated Windows containers — a Windows utility VM hosting - Argons and/or Host Process Containers inside it. -- **Sandbox:** the Windows utility VM (UVM) itself, created on `RunPodSandbox` and torn - down when the pod is removed. Each shim instance is backed 1:1 by a single UVM. -- **Tasks:** the Windows containers and processes running inside the UVM, identified - via the standard CRI annotations described above. -- **Implementation:** coming soon. - -#### containerd-shim-lcow-v2 - -- **Purpose:** runs Linux Containers on Windows — a Linux utility VM hosting Linux - containers. -- **Sandbox:** the Linux UVM. Unlike `containerd-shim-wcow-v2`, LCOW supports running - *multiple pods in the same UVM*, so a single shim instance may host more than one - CRI pod's worth of containers. This is the key behavioral difference from the WCOW - V2 shim. -- **Tasks:** Linux containers and processes running inside the UVM, identified via the - same CRI annotations described above. -- **Implementation:** [`./cmd/containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2). - The sandbox service, task service and `shimdiag` service are wired up under that - directory (`main.go`, `manager.go`, `service/`). -- **Platform requirement:** Windows Server 2025 (build 26100) or later. +- **Build Tag:** process ##### Building -The LCOW V2 shim sources are guarded by the `lcow` build tag, so the tag must be passed -to `go build`: +The V2 shim sources are guarded by the build tags as mentioned above, so the tag must be passed +to `go build`. For example the `LCOW` shim has `lcow` tag- ```powershell C:\> $env:GOOS="windows" @@ -156,8 +148,8 @@ the same as for the V1 shim. ##### Running unit tests -The shim's unit tests (and the rest of the `lcow`-tagged packages) are run with the -`lcow` build tag: +The shim's unit tests (and the rest of the tagged packages) are run with the +shim specific build tag: ```powershell C:\> go test -tags lcow ./... @@ -168,7 +160,7 @@ C:\> go test -tags lcow ./... The repository ships parity tests under [`./test/parity`](./test/parity) that feed identical inputs through the legacy V1 and the new V2 pipelines and assert that the resulting HCS ComputeSystem documents are equivalent. They live in the `test` Go -module and are also built with the `lcow` tag: +module and are also built with the build tag: ```powershell C:\> cd test