Windows containers by hand. Part 1: Installing containerd without Docker or Kubernetes

All parts of the series “Windows containers by hand”

In the series Kubernetes for beginners Windows containers appeared as part of a cluster: part 36 explained what they are made of, part 37 how their network works, and in part 38 a ready-made script installed containerd and kubelet managed the containers from then on. In this series we go in the opposite direction, downward, removing one layer of tools at a time until only a container created by direct Windows calls is left.

Today is the first step: a Windows Server without Docker and without Kubernetes, on which we install containerd, the container network and nerdctl by hand. We will run a first container, give it a network, publish a port, mount host folders and files into it, limit memory and CPU and look at the isolation levels there are. All of it with process isolation: this is the main mode of Windows containers on a server, the same one pods run in under Kubernetes.

What a server silo and job objects are and how process isolation differs from Hyper-V isolation is covered in detail in part 36, and HNS, the service that builds the container network, in part 37. Here these concepts are used without being explained again. The script that does everything described below except installing the Containers feature, and the configuration files, are in the windows-containers-by-hand repository.


The test machine

What Value
Machine wincont-lab.example.com, 192.168.10.30, a Hyper-V virtual machine: 4 vCPU, 8 GB, 64 GB disk
OS Windows Server 2025 Datacenter, Server Core, build 10.0.26100.33650
containerd 2.4.2
nerdctl 2.4.2
CNI plugins Microsoft windows-container-networking 0.3.3
Images mcr.microsoft.com/windows/nanoserver:ltsc2025, servercore:ltsc2025, ASP.NET sample mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025

The machine is fresh: only updates are installed, and it has never had Docker or Kubernetes. All commands are run in PowerShell as administrator, locally or through Enter-PSSession.

Here is what we will have built by the end of this part:

   nerdctl            ctr ──────► CNI plugin nat.exe ──► HNS: nat network, 172.30.0.0/16
      │                │
      └───────┬────────┘
              ▼  \\.\pipe\containerd-containerd
   ┌─ containerd (Windows service) ─────────┐
   │ images and layers: windows snapshotter │
   └──────────┬─────────────────────────────┘
              ▼
   containerd-shim-runhcs-v1.exe (one shim per container)
              │
              ▼
   HCS (vmcompute service) → the container's server silo

At the top are two clients: ctr, which ships with containerd, and nerdctl with the commands familiar from Docker. containerd stores images and unpacks layers, while the container itself is created by a shim from the hcsshim project, which calls HCS, the Windows service that actually creates the server silo. containerd does not set up the network here: the CNI plugin is started by the client, ctr or nerdctl. containerd does this itself only for kubelet.


The Containers feature

Before installing anything, let's see what the system does not have:

Get-WindowsFeature Containers, Hyper-V | Format-Table Name, DisplayName, InstallState
Get-Service vmcompute, hns -ErrorAction SilentlyContinue
Get-ChildItem C:\Windows\System32\computecore.dll, C:\Windows\System32\vmcompute.exe, C:\Windows\System32\hcsdiag.exe -ErrorAction SilentlyContinue | Format-Table Name, Length
Name       DisplayName InstallState
----       ----------- ------------
Hyper-V    Hyper-V        Available
Containers Containers     Available

Name             Length
----             ------
computecore.dll 1031520

The vmcompute and hns services are absent, and so are the utilities. The only thing present is computecore.dll, the client library of the HCS API: every program that creates containers and virtual machines reaches HCS through it, and we will come back to it in part 5. HCS itself and HNS come with the Containers feature:

Install-WindowsFeature -Name Containers
Restart-Computer
WARNING: You must restart this server to finish the installation process.

Success Restart Needed Exit Code      Feature Result
------- -------------- ---------      --------------
True    Yes            SuccessRest... {Containers}

The Hyper-V feature is not needed for process isolation: containers run directly on the host kernel, without a virtual machine. After the reboot:

Get-Service vmcompute, hns | Format-Table Name, DisplayName, Status, StartType
Get-Module -ListAvailable HostNetworkingService | Format-Table Name, Version
Name      DisplayName                   Status StartType
----      -----------                   ------ ---------
hns       Host Network Service         Running    Manual
vmcompute Hyper-V Host Compute Service Stopped    Manual

Name                  Version
----                  -------
HostNetworkingService 1.0.0.1

vmcompute is HCS (Host Compute Service) itself; it starts on first use. vmcompute.exe, hcsdiag.exe and hnsdiag.exe have also appeared in System32, along with the HostNetworkingService module. The module has a peculiarity we will run into later: it contains only Get-* and Remove-* commands, so you can view HNS networks and endpoints, but you cannot create them with this module.


containerd

Download and verify

containerd publishes Windows builds on GitHub along with checksum files:

$v = '2.4.2'
$base = "https://github.com/containerd/containerd/releases/download/v$v"
Set-Location $env:TEMP
curl.exe -sSLO "$base/containerd-$v-windows-amd64.tar.gz"
curl.exe -sSLO "$base/containerd-$v-windows-amd64.tar.gz.sha256sum"
Get-Content "containerd-$v-windows-amd64.tar.gz.sha256sum"
(Get-FileHash "containerd-$v-windows-amd64.tar.gz" -Algorithm SHA256).Hash.ToLower()
tar.exe -tzf "containerd-$v-windows-amd64.tar.gz"
cae2a5caf41b32ebb9b741461c163e36ebfa1a9afea8d47c66b66a27b1eb2303  containerd-2.4.2-windows-amd64.tar.gz
cae2a5caf41b32ebb9b741461c163e36ebfa1a9afea8d47c66b66a27b1eb2303
bin/
bin/ctr.exe
bin/containerd-shim-runhcs-v1.exe
bin/containerd-stress.exe
bin/containerd.exe

curl.exe and tar.exe are part of Windows, so there is nothing to install. The checksums match. The archive contains four programs:

  • containerd.exe is the daemon itself;
  • ctr.exe is its debugging client, which can do everything the containerd API can, without any conveniences;
  • containerd-shim-runhcs-v1.exe is the shim for Windows: containerd starts one instance per container, and it is the shim that calls HCS. On Linux this place is taken by containerd-shim-runc-v2 with runc;
  • containerd-stress.exe is a load test we will not need.

We unpack it into C:\Program Files\containerd and add bin to the system PATH:

$dir = "$env:ProgramFiles\containerd"
New-Item -ItemType Directory $dir -Force | Out-Null
tar.exe -xzf "$env:TEMP\containerd-$v-windows-amd64.tar.gz" -C $dir
$p = [Environment]::GetEnvironmentVariable('Path', 'Machine')
[Environment]::SetEnvironmentVariable('Path', "$p;$dir\bin", 'Machine')
$env:Path += ";$dir\bin"
containerd --version
containerd github.com/containerd/containerd/v2 v2.4.2 b7a25261e029d68978bbf290df0a62fc819b3c51

Configuration

Without a configuration file containerd runs with its defaults, but it is more convenient to have them in front of you. On Windows containerd looks for it at C:\Program Files\containerd\config.toml:

containerd config default | Set-Content "$dir\config.toml" -Encoding ascii
Select-String -Path "$dir\config.toml" -Pattern "^root|^state|snapshotter = |default_runtime_name|bin_dirs|conf_dir|platforms|address = '\\" | ForEach-Object Line
root = 'C:\ProgramData\containerd\root'
state = 'C:\ProgramData\containerd\state'
    snapshotter = 'windows'
      default_runtime_name = 'runhcs-wcow-process'
      bin_dirs = ['C:\Program Files\containerd\cni\bin']
      conf_dir = 'C:\Program Files\containerd\cni\conf'
    platforms = ['windows(10.0.26100)/amd64', 'linux/amd64']
    address = '\\.\pipe\containerd-containerd'
  • root and state are where containerd keeps images, layers and metadata (root) and whatever lives only while the service is running (state). We will look at what is in root in part 3.
  • snapshotter = 'windows' is the way image layers are turned into the container's file system. The windows snapshotter lays out the layers in folders and makes the container's writable layer a separate virtual disk.
  • default_runtime_name = 'runhcs-wcow-process' is the default runtime: runhcs, a Windows container on Windows (WCOW), process isolation. Next to it the file describes runhcs-wcow-hypervisor, the same runtime with Hyper-V isolation. These two lines belong to the CRI section, that is, the settings kubelet uses; ctr and nerdctl choose isolation themselves, and their default is also process.
  • bin_dirs and conf_dir are where the CNI plugins and their configuration live. These folders do not exist yet.
  • platforms lists the images containerd agrees to download: Windows build 26100 and Linux. The build number in parentheses matters: from an image with several variants containerd picks the variant for its own build; the rules are covered in detail in part 39.
  • address is the named pipe through which clients talk to containerd. This is what nerdctl will see.

The service

containerd can register itself as a Windows service:

containerd --register-service
Start-Service containerd
Get-Service containerd | Format-Table Name, DisplayName, Status, StartType
Get-CimInstance Win32_Service -Filter "Name='containerd'" | Format-List PathName, StartName
ctr version
Name       DisplayName  Status StartType
----       -----------  ------ ---------
containerd containerd  Running Automatic

PathName  : "C:\Program Files\containerd\bin\containerd.exe" --run-service
StartName : LocalSystem

Client:
  Version:  v2.4.2
  Revision: b7a25261e029d68978bbf290df0a62fc819b3c51
  Go version: go1.27.2

Server:
  Version:  v2.4.2
  Revision: b7a25261e029d68978bbf290df0a62fc819b3c51
  UUID: a21bd28f-499d-4e16-8c0f-356a6ec8a297

The service starts automatically, under LocalSystem.


First container with ctr

ctr image pull mcr.microsoft.com/windows/nanoserver:ltsc2025
ctr image ls
└──index (05d1a7fb562f)                 complete   |++++++++++++++++++++++++++++++++++++++|
   └──manifest (6020b6edd804)           complete   |++++++++++++++++++++++++++++++++++++++|
      ├──config (bd66d3cd2318)          complete   |++++++++++++++++++++++++++++++++++++++|
      └──layer (a7eba7a59d48)           complete   |++++++++++++++++++++++++++++++++++++++|
application/vnd.docker.distribution.manifest.list.v2+json sha256:05d1a7fb562f998ed3bc23b21dbd95aa26b3dd10ae921e830449e2db657f6704
Pulling from OCI Registry (mcr.microsoft.com/windows/nanoserver:ltsc2025)  elapsed: 20.2s  total:  185.2  (9.2 MiB/s)

REF                                           TYPE                                                      DIGEST                                                                  SIZE      PLATFORMS     LABELS
mcr.microsoft.com/windows/nanoserver:ltsc2025 application/vnd.docker.distribution.manifest.list.v2+json sha256:05d1a7fb562f998ed3bc23b21dbd95aa26b3dd10ae921e830449e2db657f6704 185.2 MiB windows/amd64 -

ctr shows what the image consists of: an index with the list of variants, from it the manifest for our platform, and in the manifest the configuration and the single Nano Server layer, 185 MiB compressed. Let's run it:

ctr run --rm mcr.microsoft.com/windows/nanoserver:ltsc2025 hello cmd /c "ver & hostname & echo %USERNAME% & ipconfig"
cmd /c ver
Microsoft Windows [Version 10.0.26100.33674]
minwinpc
ContainerUser

Windows IP Configuration

Microsoft Windows [Version 10.0.26100.33650]

The container started and exited in under two seconds. The last line is the version of the host itself, and the revisions differ: 33674 in the image and 33650 on the host. For process isolation the build (26100) must match, while revisions may differ; part 36 explains why. The container has its own name (minwinpc) and its own default user (ContainerUser, which is not an administrator in Nano Server), and ipconfig is empty: ctr does not set up networking by itself, and the container has no adapters at all. We will give it a network through CNI.


Network: CNI and the nat plugin

How a container gets a network

CNI (Container Network Interface) is a specification, common to Linux and Windows, of how a runtime requests a network for a container. A plugin is an ordinary program. The runtime starts it, passes the command in environment variables (ADD to connect a container, DEL to disconnect it, CHECK to verify), along with the container ID and its network namespace, and sends JSON with the network configuration to its standard input. The plugin does its work and prints JSON with the assigned addresses. Kubernetes uses the same mechanism; that is how Calico from part 37 connects pods.

Microsoft ships three plugins for Windows: nat, sdnbridge and sdnoverlay. The last two are for clusters where container addresses are visible from other hosts: a bridge into the host network and an overlay network between hosts. For a single machine nat is what you need: containers get addresses from an internal subnet and reach the outside through network address translation (NAT), where the host replaces the container's internal address with its own and returns the replies. A home router works the same way.

$v = '0.3.3'
$zip = "windows-container-networking-cni-amd64-v$v.zip"
curl.exe -sSLO "https://github.com/microsoft/windows-container-networking/releases/download/v$v/$zip"
curl.exe -sSLO "https://github.com/microsoft/windows-container-networking/releases/download/v$v/$zip.sha256"
Get-Content "$zip.sha256"
(Get-FileHash $zip).Hash.ToLower()
$cni = "$env:ProgramFiles\containerd\cni"
New-Item -ItemType Directory "$cni\bin", "$cni\conf" -Force | Out-Null
tar.exe -xf $zip -C "$cni\bin"
Get-ChildItem "$cni\bin" | Format-Table Name, Length
12ce767c9bc5b8088021339bedd119a85d40bc2e18df5c55ca629b1ef4d346c5  ./release/windows-container-networking-cni-amd64-v0.3.3.zip
12ce767c9bc5b8088021339bedd119a85d40bc2e18df5c55ca629b1ef4d346c5

Name             Length
----             ------
nat.exe         5353984
sdnbridge.exe   5353984
sdnoverlay.exe  5353984

The nat network configuration

We put the network description into conf, the file 0-containerd-nat.conflist:

{
    "cniVersion": "0.3.0",
    "name": "nat",
    "plugins": [
        {
            "type": "nat",
            "master": "Ethernet",
            "ipam": {
                "subnet": "172.30.0.0/16",
                "routes": [
                    { "gateway": "172.30.0.1" }
                ]
            },
            "capabilities": {
                "portMappings": true,
                "dns": true
            }
        }
    ]
}
  • name is the network name. The nat plugin will find or create an HNS network with this name.
  • plugins is a chain of plugins called in turn; we have one. That is why the file is named .conflist. There is also the old .conf format, a single plugin without a list, and ctr understands it, but nerdctl fails on it with an index out of range error in verifyNetworkTypes: it needs a list.
  • type is the name of the plugin's executable in bin_dirs, that is, nat.exe.
  • master is the host's network adapter, as it is named in Microsoft's examples. You can find the name with Get-NetAdapter.
  • ipam says where to get addresses: the container subnet and the gateway, which will be the host. The subnet must not overlap either the host network or the networks containers need to reach.
  • capabilities is what the plugin can accept from the runtime: port publishing and the settings of DNS, the service that turns names like mcr.microsoft.com into addresses.
curl.exe -sSL -o "$cni\conf\0-containerd-nat.conflist" https://raw.githubusercontent.com/vitaliy-leschenko/windows-containers-by-hand/main/01-containerd/0-containerd-nat.conflist
Get-HnsNetwork

Get-HnsNetwork prints nothing: there are no HNS networks yet. We will not have to create one by hand, and the built-in module has no command for it anyway.

A container on the network

ctr run --rm --cni mcr.microsoft.com/windows/nanoserver:ltsc2025 net1 cmd /c "ipconfig & ping -n 2 1.1.1.1"
Windows IP Configuration


Ethernet adapter vEthernet (default-net1_nat):

   Connection-specific DNS Suffix  . : example.com
   Link-local IPv6 Address . . . . . : fe80::8653:cde8:f2a6:5379%17
   IPv4 Address. . . . . . . . . . . : 172.30.150.138
   Subnet Mask . . . . . . . . . . . : 255.255.0.0
   Default Gateway . . . . . . . . . : 172.30.0.1

Pinging 1.1.1.1 with 32 bytes of data:
Reply from 1.1.1.1: bytes=32 time=9ms TTL=54
Reply from 1.1.1.1: bytes=32 time=9ms TTL=54

Ping statistics for 1.1.1.1:
    Packets: Sent = 2, Received = 2, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 9ms, Maximum = 9ms, Average = 9ms

The --cni flag tells ctr to start the CNI plugin, and it is ctr itself that starts it, not containerd. The container now has an adapter with an address from our subnet and the gateway 172.30.0.1, and ping, which sends ICMP echo requests that the remote host answers (ICMP is IP's service protocol), reaches an external address. The adapter is named default-net1_nat: the containerd namespace (default), the container name and the network name. And the host now has an HNS network:

Get-HnsNetwork | Select-Object Name, Type, @{n='AddressPrefix';e={$_.Subnets.AddressPrefix}}, @{n='Gateway';e={$_.Subnets.GatewayAddress}} | Format-List
Name          : nat
Type          : NAT
AddressPrefix : 172.30.0.0/16
Gateway       : 172.30.0.1

It was created by the nat plugin on the first ADD call, because there was no network named nat. After --rm ctr called DEL, and the plugin removed the container's endpoint (Get-HnsEndpoint is empty again), while the network remained for the next containers.

Nano Server has no nslookup, so we will check DNS with a request to the image registry through curl.exe, which the image does include:

ctr run --rm --cni mcr.microsoft.com/windows/nanoserver:ltsc2025 net2 cmd /c "ipconfig /all | findstr /i dns & curl.exe -sS -o NUL -w %{http_code} https://mcr.microsoft.com/v2/"
   Primary Dns Suffix  . . . . . . . :
   DNS Suffix Search List. . . . . . : example.com
   Connection-specific DNS Suffix  . : example.com
   DNS Servers . . . . . . . . . . . : 192.168.10.1
   Connection-specific DNS Suffix Search List :
200

The container received the same DNS server and suffix as the host, the name resolved, and the registry answered with code 200.


nerdctl

ctr is fine for checks, but typing --cni and inventing a container name every time is inconvenient. nerdctl is a containerd client with Docker's commands: run, ps, exec, -p, -v. It is a single file:

$v = '2.4.2'
$f = "nerdctl-$v-windows-amd64.tar.gz"
curl.exe -sSLO "https://github.com/containerd/nerdctl/releases/download/v$v/$f"
curl.exe -sSLO "https://github.com/containerd/nerdctl/releases/download/v$v/SHA256SUMS"
(Select-String -Path SHA256SUMS -Pattern $f -SimpleMatch).Line
(Get-FileHash $f).Hash.ToLower()
tar.exe -xzf $f -C "$env:ProgramFiles\containerd\bin"
nerdctl info
nerdctl network ls
03891a599848e819dee0f79f1adb6bd3022df737980df7ea5ffe0649fec9cd80  nerdctl-2.4.2-windows-amd64.tar.gz
03891a599848e819dee0f79f1adb6bd3022df737980df7ea5ffe0649fec9cd80

Client:
 Namespace:     default
 Debug Mode:    false

Server:
 Server Version: v2.4.2
 Storage Driver: windows
 Logging Driver: json-file
 Plugins:
  Log:     fluentd journald json-file none syslog
  Storage: windows-lcow cimfs windows
 Kernel Version:   10.0 26100 (26100.33648.amd64fre.lt_release_svc_prod1.261009-2239)
 Operating System: Microsoft Windows Server Version 24H2 (OS Build 26100.33650)
 OSType:           windows
 Architecture:     x86_64
 CPUs:             4
 Total Memory:     7.999GiB
 Name:             wincont-lab

NETWORK ID    NAME    FILE
              nat     C:\Program Files\containerd\cni\conf\0-containerd-nat.conflist
              host
              none

nerdctl found containerd through the \\.\pipe\containerd-containerd pipe and the nat network in the CNI directory. It needs no configuration of its own. On every run it will warn that the nat network was not created by it:

time="2026-11-08T02:24:09+03:00" level=warning msg="default network named \"nat\" does not have an internal nerdctl ID or nerdctl-managed config file, it was most likely NOT created by nerdctl"

That is true and harmless. From here on this warning is left out of the output.

Publishing a port

Let's run Microsoft's ASP.NET sample on Nano Server, the same one as in the Kubernetes series. It listens on port 8080:

nerdctl run -d --name web -p 8080:8080 mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025
nerdctl ps
CONTAINER ID    IMAGE                                                             COMMAND                 CREATED                   STATUS    PORTS                     NAMES
7c686c1fbb87    mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025    "AspNetCoreRazorApp"    Less than a second ago    Up        0.0.0.0:8080->8080/tcp    web

From another machine on the network:

curl.exe -s -o NUL -w "%{http_code}`n" http://192.168.10.30:8080/
200

The page opens both from outside and on the host itself at http://localhost:8080. Let's see how this is done:

Get-HnsEndpoint | Select-Object Name, IPAddress, VirtualNetworkName | Format-List
(Get-HnsEndpoint).Policies | ForEach-Object { [pscustomobject]@{ Type = $_.Type; Protocol = $_.Protocol; InternalPort = $_.InternalPort; ExternalPort = $_.ExternalPort } } | Format-Table
Name               : 7c686c1fbb87c5b10437fcdb3f4f071a469905dfe2b71f962f42b3d798c16396_nat
IPAddress          : 172.30.124.41
VirtualNetworkName : nat

Type Protocol InternalPort ExternalPort
---- -------- ------------ ------------
NAT  TCP              8080         8080

The nat plugin created an HNS endpoint for the container, which is its network adapter connected to the nat network, and attached a NAT policy to it: connections to port 8080 of the host go to port 8080 of the container. The port is open on all host addresses, and there is no firewall rule for it (Get-NetFirewallPortFilter does not find port 8080), just as there is no Get-NetNat object: the translation is done by HNS, not by the Windows NAT service. How HNS policies become virtual switch rules is covered in part 37.


Host folders and files

Mounting a host folder into a container (bind mount) looks the same in nerdctl as in Docker, -v <on the host>:<in the container>:

New-Item -ItemType Directory C:\share -Force | Out-Null
'hello from host' | Set-Content C:\share\hello.txt
nerdctl run --rm -v C:\share:C:\data mcr.microsoft.com/windows/nanoserver:ltsc2025 cmd /c "type C:\data\hello.txt & echo written in container> C:\data\from-container.txt"
Get-Content C:\share\from-container.txt
hello from host
written in container

Writing works both ways: the container read a host file, and the file the container wrote appeared on the host. With the :ro suffix the folder is mounted read-only:

nerdctl run --rm -v C:\share:C:\data:ro mcr.microsoft.com/windows/nanoserver:ltsc2025 cmd /c "echo x> C:\data\ro.txt"
Access is denied.

Now something Docker on Windows could not do: mount a single file. Docker required the source to be a folder, so a configuration file had to be placed in a separate directory. containerd with runhcs mounts a file as well:

New-Item -ItemType Directory C:\lab -Force | Out-Null
'version=1' | Set-Content C:\lab\app.conf
nerdctl run --rm -v C:\lab\app.conf:C:\config\app.conf mcr.microsoft.com/windows/nanoserver:ltsc2025 cmd /c "dir C:\config & type C:\config\app.conf"
 Volume in drive C has no label.
 Volume Serial Number is AE3E-D6B0

 Directory of C:\config

11/08/2026  02:40 AM    <DIR>          .
11/08/2026  02:39 AM                11 app.conf
               1 File(s)             11 bytes
               1 Dir(s)  21,302,444,032 bytes free
version=1

With ctr the same thing is written with --mount and explicit parameters:

ctr run --rm --mount type=bind,src=C:\lab\app.conf,dst=C:\config\app.conf,options=rbind:ro mcr.microsoft.com/windows/nanoserver:ltsc2025 m2 cmd /c "type C:\config\app.conf & echo x>> C:\config\app.conf"
version=1
Access is denied.

Changes on the host are visible in a running container immediately, both in the folder and in the file:

$id = nerdctl run -d -v C:\share:C:\data -v C:\lab\app.conf:C:\config\app.conf mcr.microsoft.com/windows/nanoserver:ltsc2025 ping -t localhost
'version=2' | Set-Content C:\lab\app.conf
'new file' | Set-Content C:\share\new.txt
nerdctl exec $id cmd /c "type C:\config\app.conf & dir /b C:\data"
Remove-Item C:\lab\app.conf
'version=3' | Set-Content C:\lab\app.conf
nerdctl exec $id cmd /c "type C:\config\app.conf"
nerdctl rm -f $id
version=2
from-container.txt
hello.txt
new.txt

version=3

In the last check the file on the host was deleted and created again, and the container still sees the new content. This is a difference from Linux: there a mounted file is tied to a specific inode, and if an editor saves a file by replacing it, the container keeps seeing the old version. On Windows the mapping works by path. What does it, the bindflt file system filter, we will see in part 3.


Memory and CPU limits

A container with process isolation has no virtual machine of its own; its processes run on the host kernel. They are limited by the job object that contains the container's silo, a Windows mechanism that accounts for and limits the resources of a group of processes (more in part 36). Let's check whether the --memory and --cpus flags work. For this we need PowerShell inside the container, and Nano Server does not have it, so we will take the Server Core image, which is considerably heavier:

nerdctl pull mcr.microsoft.com/windows/servercore:ltsc2025
nerdctl images
IMAGE                                                             ID              DISK USAGE    CONTENT SIZE    EXTRA
mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025    3bbeaca15f52    1.76GB        258MB           U
mcr.microsoft.com/windows/nanoserver:ltsc2025                     05d1a7fb562f    1.28GB        194MB
mcr.microsoft.com/windows/servercore:ltsc2025                     4e5730bddf04    15GB          2.33GB

2.33 GB compressed and 15 GB on disk. The letter U in the last column means the image is used by a container, in our case web.

Memory

Inside the container PowerShell allocates 64 MB arrays in a loop until it reaches 2 GB or gets an error:

$img = 'mcr.microsoft.com/windows/servercore:ltsc2025'
$test = '$l = [Collections.Generic.List[byte[]]]::new(); $i = 0; try { while ($i -lt 32) { $l.Add([byte[]]::new(64MB)); $i++ }; "allocated $($i*64) MB, no error" } catch { "failed after $($i*64) MB: $($_.Exception.InnerException.GetType().Name)" }'
nerdctl run --rm $img powershell -NoProfile -Command $test
nerdctl run --rm --memory 512m $img powershell -NoProfile -Command $test
allocated 2048 MB, no error
failed after 320 MB: OutOfMemoryException

Without a limit the container took 2 GB without trouble. With --memory 512m allocation stopped at 320 MB of arrays: the next 64 MB block did not fit, because part of the memory is taken by PowerShell and .NET themselves. Note how it happened: the process got a memory allocation error and handled it itself, and the container kept running and exited normally. On Linux, when the limit is exceeded, the kernel kills the process (OOM killer), whereas Windows simply refuses new memory; part 39 covered the consequences of this in Kubernetes.

CPU

The check is harder here: we need to load the container and measure from outside how much CPU time it got. Inside the container we start four PowerShell processes with an empty infinite loop, each wanting a whole core, and on the host we add up the CPU time of the container's processes over 10 seconds. We find the container's processes by session number, which hcsdiag list shows (more on that in the last section). The full script is cpu-test.ps1 in the repository:

.\cpu-test.ps1
.\cpu-test.ps1 -Cpus 1
limit: none; session 3; 5 powershell processes; CPU used: 3,98 of 4 cores
limit: --cpus 1; session 3; 5 powershell processes; CPU used: 1,04 of 4 cores

Without a limit the four loops took all four cores of the machine, with --cpus 1 one core for all of them. The fifth PowerShell process is the one that started them and is waiting.

What goes into the spec

nerdctl does not limit anything itself: it writes the limits into the container spec, OCI-format JSON that containerd passes to the shim, and the shim passes them to HCS. You can read the spec through ctr:

$id = nerdctl run -d --cpus 1 --memory 512m mcr.microsoft.com/windows/nanoserver:ltsc2025 ping -t localhost
(ctr containers info $id | ConvertFrom-Json).Spec.windows | ConvertTo-Json -Depth 5
nerdctl rm -f $id
{
    "layerFolders": null,
    "resources": {
        "memory": {
            "limit": 536870912
        },
        "cpu": {
            "count": 1
        }
    },
    "ignoreFlushesDuringBoot": true,
    "network": {
        "allowUnqualifiedDNSQuery": true,
        "networkNamespace": "5602c638-42b8-40e5-abe1-8b14ae8af66b"
    }
}

Memory is limit in bytes, 512 MiB. nerdctl sets CPU as a number of processors, count: 1. The OCI spec for Windows has other ways as well: maximum, the share of all processors' time in ten-thousandths, and shares, a relative weight under contention. kubelet, as we saw in part 39, translates a pod's limits.cpu into maximum. You can also see the network namespace here (networkNamespace), the very one nerdctl passed to the CNI plugin in the ADD command.


Process isolation: what the host sees

All the containers in this part ran with process isolation; it is the default both for runhcs-wcow-process in the containerd configuration and for nerdctl:

nerdctl run --help | Select-String isolation
      --isolation string    Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default (default "default")

There are three isolation levels:

  • process is process isolation. The container's processes run on the host kernel, but inside a server silo, with their own file system, registry, network and kernel object namespace. This is the mode we use.
  • hyperv is Hyper-V isolation. The container runs in a separate small virtual machine with its own kernel, so it does not have to match the host's build. It needs the Hyper-V feature, which our test machine does not have, so such a container will not start. More on it in part 6.
  • host is a HostProcess container. There is no isolation at all: the process runs directly on the host, as SYSTEM, with the host's files and network. In Kubernetes this is how system node components that need access to the host are run, such as a network plugin's agent.

The difference is visible right away:

nerdctl run --rm --isolation host mcr.microsoft.com/windows/nanoserver:ltsc2025 cmd /c "hostname & whoami"
nerdctl run --rm --isolation hyperv mcr.microsoft.com/windows/nanoserver:ltsc2025 cmd /c "hostname"
wincont-lab
nt authority\system
time="2026-11-08T11:41:47+03:00" level=error msg="failed to accept stdout connection on \\\\.\\pipe\\ctr-cdfa883989cdbbcd085a9ddab5472235198beb489e81cedff0026ca5f3bd3342-stdout" error="use of closed network connection"
time="2026-11-08T11:41:47+03:00" level=error msg="failed to accept stderr connection on \\\\.\\pipe\\ctr-cdfa883989cdbbcd085a9ddab5472235198beb489e81cedff0026ca5f3bd3342-stderr" error="use of closed network connection"
time="2026-11-08T11:41:47+03:00" level=fatal msg="failed to create shim task: error in preparing config doc: failed to get host processor information: failed to retrieve processor and processor topology information: hcs::GetServiceProperties: The virtual machine could not be started because a required feature is not installed."

The host container sees the host's name, not its own (minwinpc from the first experiment), and runs as SYSTEM rather than ContainerUser. For the hyperv container HCS cannot assemble a virtual machine without the Hyper-V feature, and the lines about the stdout and stderr pipes are a consequence: the task was not created, and nerdctl closed the pipes nobody had connected to. From here on we stay with process isolation. You can confirm that containers really run in it from the containers themselves. hcsdiag, a utility that came with the Containers feature, shows everything created through HCS:

hcsdiag list
7c686c1fbb87c5b10437fcdb3f4f071a469905dfe2b71f962f42b3d798c16396
    Windows Server Container,   Running,   , containerd-shim-runhcs-v1.exe, 2

Windows Server Container is what HCS calls a container with process isolation; a container with Hyper-V isolation would have a different type, and a utility VM would appear next to it. The owner is the containerd shim, and the last number is the session number. With process isolation the container's processes are ordinary host processes, only in their own session:

Get-Process | Where-Object SessionId -gt 1 | Sort-Object SessionId, Name | Format-Table Name, Id, SessionId
Name                 Id SessionId
----                 -- ---------
AspNetCoreRazorApp 3784         2
CExecSvc           5436         2
csrss              5284         2
lsass              3756         2
services           4672         2
svchost            5512         2
svchost            5312         2
...
wininit            5528         2

Inside the container there is a small Windows of its own: csrss, wininit, services, lsass, a set of svchost and CExecSvc, through which exec works, and next to them the application itself. The host sees all of this in its ordinary process list. How these processes, the server silo and the image layers add up to a container is something we will take apart in part 3.


Cleaning up

We no longer need the containers, images and folders from this part: each part of the series creates what it needs from scratch and removes it at the end.

nerdctl rm -f web
nerdctl rmi mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025 mcr.microsoft.com/windows/nanoserver:ltsc2025 mcr.microsoft.com/windows/servercore:ltsc2025
Remove-Item C:\share, C:\lab -Recurse -Force
nerdctl ps -a
nerdctl images
CONTAINER ID    IMAGE    COMMAND    CREATED    STATUS    PORTS    NAMES
IMAGE    ID    DISK USAGE    CONTENT SIZE    EXTRA

The containerd service, nerdctl and the CNI plugins stay on the server.


All in one script

Everything we did by hand, except the Containers feature (it needs a reboot), is collected in install-containerd.ps1: it downloads containerd, nerdctl and the CNI plugins, verifies the checksums, lays out the files, writes config.toml and the nat network configuration and registers the service. The versions and the subnet are parameters:

Install-WindowsFeature Containers
Restart-Computer
# after the reboot
.\install-containerd.ps1 -ContainerdVersion 2.4.2 -NerdctlVersion 2.4.2 -CniVersion 0.3.3 -Subnet 172.30.0.0/16 -Gateway 172.30.0.1

The script has been tested on a clean machine with the same Windows build as in this article.


Sources


Next — we start two containers and teach them to find each other by name.

Only registered users can leave a comment.

Sign in or register to leave a comment.