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.exeis the daemon itself;ctr.exeis its debugging client, which can do everything the containerd API can, without any conveniences;containerd-shim-runhcs-v1.exeis the shim for Windows: containerd starts one instance per container, and it is the shim that calls HCS. On Linux this place is taken bycontainerd-shim-runc-v2with runc;containerd-stress.exeis 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'
rootandstateare where containerd keeps images, layers and metadata (root) and whatever lives only while the service is running (state). We will look at what is inrootin part 3.snapshotter = 'windows'is the way image layers are turned into the container's file system. Thewindowssnapshotter 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 describesrunhcs-wcow-hypervisor, the same runtime with Hyper-V isolation. These two lines belong to the CRI section, that is, the settings kubelet uses;ctrand nerdctl choose isolation themselves, and their default is alsoprocess.bin_dirsandconf_dirare where the CNI plugins and their configuration live. These folders do not exist yet.platformslists 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.addressis 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
}
}
]
}
nameis the network name. Thenatplugin will find or create an HNS network with this name.pluginsis a chain of plugins called in turn; we have one. That is why the file is named.conflist. There is also the old.confformat, a single plugin without a list, andctrunderstands it, but nerdctl fails on it with anindex out of rangeerror inverifyNetworkTypes: it needs a list.typeis the name of the plugin's executable inbin_dirs, that is,nat.exe.masteris the host's network adapter, as it is named in Microsoft's examples. You can find the name withGet-NetAdapter.ipamsays 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.capabilitiesis what the plugin can accept from the runtime: port publishing and the settings of DNS, the service that turns names likemcr.microsoft.cominto 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:
processis 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.hypervis 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.hostis 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
- Get started: Prep Windows for containers — Microsoft Learn: the Containers feature and containerd on Windows Server.
- containerd: Getting started — installing containerd, including on Windows.
- microsoft/windows-container-networking — the
nat,sdnbridgeandsdnoverlayCNI plugins. - CNI specification — the CNI specification: commands, configuration, the
.conflistformat. - nerdctl — a containerd client with Docker's commands.
- OCI runtime spec: Windows-specific container configuration — the
windows.resourcessection of the container spec. - Isolation modes — Microsoft Learn: process and Hyper-V isolation.
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.