Windows containers by hand. Part 5: Running a container without a runtime through HCS
All parts of the series “Windows containers by hand”In part 4 we downloaded an image without containerd, unpacked its layers with the wclayer utility and looked at what containerd hands to the shim: the layers and the OCI specification. From there the shim turns this into an HCS JSON document and calls HCS. Today we will do the shim's work ourselves: we will write a small program that calls HCS and HNS directly and run the same ASP.NET sample in a container, with a network, port publishing, a mounted folder and limits. There will be no containerd, no shim and no OCI specification in this part.
The code and scripts are in the 05-hcs folder of the repository.
HCS API
HCS (Host Compute Service, the vmcompute service) creates both containers and virtual machines. Programs reach it through the computecore.dll library, the same one we found in the system in part 1 before the Containers feature was even installed. The API is built on three ideas:
- Handles. A compute system (the term HCS uses for both a container and a virtual machine) and a process in it are represented by the handles
HCS_SYSTEMandHCS_PROCESS. A system can be opened by name from another program. - Operations. Calls that act on a system or a process are asynchronous: each one is given an
HCS_OPERATION, and the result is collected by waiting on it withHcsWaitForOperationResult. The result or the error description comes back as a JSON document. - JSON documents. What to create and how is described by a document in the HCS schema: for a system, its storage, network and limits; for a process, the command line, user, environment and I/O pipes.
We will need eleven functions, not counting the ones that close handles:
| Function | What it does |
|---|---|
HcsCreateOperation |
creates an operation for an asynchronous call |
HcsWaitForOperationResult |
waits for an operation and returns the result document |
HcsWaitForOperationResultAndProcessInfo |
the same for creating a process, together with the handles of its pipes |
HcsCreateComputeSystem |
creates a system from a document |
HcsStartComputeSystem |
starts it |
HcsOpenComputeSystem |
opens an existing system by name |
HcsGetComputeSystemProperties |
system properties |
HcsCreateProcess |
starts a process in a system |
HcsGetProcessProperties |
process state and exit code |
HcsTerminateComputeSystem |
stops a system |
HcsEnumerateComputeSystems |
list of systems |
Networking is a separate service, HNS, with its own library computenetwork.dll and the same approach: handles and JSON. What an HNS network, endpoint and network compartment are is covered in part 37 of the Kubernetes series.
hcsctl
The hcsctl program is 435 lines of C# built with Native AOT, like name-ipam in part 2. It does not build the JSON documents: we write them, and it only passes them to HCS. The functions are declared with LibraryImport, a code generator for calling unmanaged functions:
[LibraryImport("computecore.dll")]
private static partial IntPtr HcsCreateOperation(IntPtr context, IntPtr callback);
[LibraryImport("computecore.dll")]
private static partial int HcsWaitForOperationResult(IntPtr operation, uint timeoutMs, out IntPtr resultDocument);
[LibraryImport("computecore.dll", StringMarshalling = StringMarshalling.Utf16)]
private static partial int HcsCreateComputeSystem(string id, string configuration, IntPtr operation, IntPtr securityDescriptor, out IntPtr computeSystem);
[LibraryImport("computecore.dll", StringMarshalling = StringMarshalling.Utf16)]
private static partial int HcsStartComputeSystem(IntPtr computeSystem, IntPtr operation, string? options);
Every call goes the same way: call the function with an operation, wait for the operation, take the document. This is moved into one function:
static string Wait(IntPtr op, int hr, string what)
{
if (hr < 0) throw new InvalidOperationException($"{what}: 0x{hr:X8}");
hr = HcsWaitForOperationResult(op, Infinite, out var doc);
var result = TakeString(doc);
if (hr < 0) throw new InvalidOperationException($"{what}: 0x{hr:X8} {result}");
return result;
}
TakeString turns a string allocated by HCS into a .NET string and frees the memory with LocalFree. Creating a system is two calls on one operation:
public static void Create(string id, string document)
{
var op = HcsCreateOperation(IntPtr.Zero, IntPtr.Zero);
try
{
Wait(op, HcsCreateComputeSystem(id, document, op, IntPtr.Zero, out var system), "HcsCreateComputeSystem");
try
{
Wait(op, HcsStartComputeSystem(system, op, null), "HcsStartComputeSystem");
}
finally
{
HcsCloseComputeSystem(system);
}
}
finally
{
HcsCloseOperation(op);
}
}
The hcsctl commands follow the familiar Docker ones:
| Command | What it does |
|---|---|
create <id> <system.json> |
creates and starts a system from a document |
exec [-d] <id> <process.json> |
starts a process; without -d it prints the process output and returns its exit code |
ls, props <id> |
lists systems and shows the properties of one |
rm <id> |
stops a system |
net <namespace> <network> <ip>/<prefix> <gateway> <dns> [host:container ...] |
creates an HNS endpoint and a network namespace |
net-rm <namespace> |
deletes them |
layer-id <folder> |
the layer GUID for the document |
We build it on the workstation. As a reminder, besides the .NET 10 SDK, Native AOT needs the linker from Visual Studio or Build Tools with the C++ component, and the build looks for it with the vswhere.exe utility, which may not be on PATH. So the first line adds the Visual Studio installer folder there:
$env:Path += ";${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer"
dotnet publish -c Release -o out
Get-ChildItem out | Format-Table Name, Length
Name Length
---- ------
hcsctl.exe 1743360
hcsctl.pdb 9105408
Only hcsctl.exe goes to the server: we put it in C:\hcs, next to wclayer.exe. We will also download there the scripts we need below:
foreach ($f in 'run-container.ps1', 'remove-container.ps1', 'cpu-test.ps1') {
curl.exe -sSLo "C:\hcs\$f" "https://raw.githubusercontent.com/vitaliy-leschenko/windows-containers-by-hand/main/05-hcs/$f"
}
The first container
The experiments need two images: Nano Server and Microsoft's ASP.NET sample. We will download them with the pull-image.ps1 script, which is in C:\hcs, and next to them start a web container with the same sample under containerd, to compare our containers with it:
pull-image.ps1 mcr.microsoft.com/windows/nanoserver:ltsc2025 C:\images\nanoserver
pull-image.ps1 mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025 C:\images\samples
nerdctl run -d --name web -p 8080:8080 mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025
Let's start with the simplest case: Nano Server without a network. We prepare the container disk as in part 4: a writable layer on top of the image layer, mounted as a volume. This time we do not give wclayer mount a target folder, because we need the volume path:
New-Item -ItemType Directory C:\lab\hcs -Force | Out-Null; Set-Location C:\lab\hcs
$base = 'C:\images\nanoserver\layers\9a4c0752c6bda5fc00f886a9acf0c0afed0750082f7999c331df978fb9f97d2a'
wclayer create -l $base C:\layers\hello
$volume = wclayer mount -l $base C:\layers\hello
$lid = hcsctl layer-id $base
$volume
$lid
\\?\Volume{1896b46a-29d4-403c-92d3-a2080cb86690}
13962ae5-0ef1-5a3b-881c-5e9fa8000f5e
In an HCS document every layer has a path and a GUID. The GUID is derived from the layer folder name by the NameToGuid function from vmcompute.dll, the same way hcsshim computes it; that is what hcsctl layer-id does. The system document is hello.json:
{
"SchemaVersion": { "Major": 2, "Minor": 1 },
"Owner": "hcsctl",
"ShouldTerminateOnLastHandleClosed": false,
"Container": {
"GuestOs": { "HostName": "hello" },
"Storage": {
"Layers": [
{
"Id": "13962ae5-0ef1-5a3b-881c-5e9fa8000f5e",
"Path": "C:\\images\\nanoserver\\layers\\9a4c0752c6bda5fc00f886a9acf0c0afed0750082f7999c331df978fb9f97d2a"
}
],
"Path": "\\\\?\\Volume{1896b46a-29d4-403c-92d3-a2080cb86690}"
}
}
}
SchemaVersionis the version of the HCS document schema.Owneris the owner, shown byhcsdiag list.ShouldTerminateOnLastHandleClosed: falsemeans the system survives the closing of the handle, that is, the exit ofhcsctl. Otherwise the container would live only while the program that created it is running.Containersays this is a container and not a virtual machine. It runs on the host kernel with process isolation:hcsctl propsbelow will show"IsolationType": "Process".GuestOs.HostNameis the computer name inside the container. This field should always be set; we will see why below.Storage.Layerslists the image layers from top to bottom, andStorage.Pathis the volume of the writable layer: HCS will make it the container'sC:drive.
hcsctl create hello hello.json
hcsdiag list
hello
e3f3aa09b67d4555b7619e202e25dca92bc8cd636045dfb1a2849a729052da73
Windows Server Container, Running, , containerd-shim-runhcs-v1.exe, 2
hello
Windows Server Container, Running, , hcsctl, 4
Next to the web container managed by the containerd shim, our hello has appeared: also a Windows Server Container, owner hcsctl, session 4.
Processes
The system is running, but it has no process of its own yet: processes are started separately. A process is described by its own document, ver.json:
{
"CommandLine": "cmd /c ver & hostname & echo %USERNAME% & dir /b C:\\",
"WorkingDirectory": "C:\\",
"CreateStdOutPipe": true,
"CreateStdErrPipe": true
}
hcsctl exec hello ver.json
Microsoft Windows [Version 10.0.26100.33674]
hello
ContainerAdministrator
License.txt
Users
Windows
The name comes from GuestOs.HostName, and the root of the drive holds the files of the Nano Server layer. The user is ContainerAdministrator, even though the configuration of the Nano Server image says ContainerUser. HCS knows nothing about images: it is containerd that reads the image configuration, and by default HCS starts a process as the container administrator. We set the user, the environment and the exit code ourselves, in user.json:
{
"CommandLine": "cmd /c echo %USERNAME%: %GREETING% & exit 3",
"User": "ContainerUser",
"Environment": { "GREETING": "hello from hcsctl" },
"CreateStdOutPipe": true,
"CreateStdErrPipe": true
}
hcsctl exec hello user.json
"exit code: $LASTEXITCODE"
ContainerUser: hello from hcsctl
exit code: 3
CreateStdOutPipe and CreateStdErrPipe ask HCS to create pipes for the process output. Their handles, along with the process ID, come from HcsWaitForOperationResultAndProcessInfo, the wait on the HcsCreateProcess operation, and hcsctl copies from them to its own output until the process closes them. Then it queries HcsGetProcessProperties until it gets "Exited": true with the exit code:
var hr = HcsCreateProcess(system, parameters, op, IntPtr.Zero, out var process);
if (hr < 0) throw new InvalidOperationException($"HcsCreateProcess: 0x{hr:X8}");
hr = HcsWaitForOperationResultAndProcessInfo(op, Infinite, out var info, out var doc);
// ...
var copies = new[]
{
Wants("CreateStdOutPipe") ? Copy(info.StdOutput, Console.OpenStandardOutput()) : Task.CompletedTask,
Wants("CreateStdErrPipe") ? Copy(info.StdError, Console.OpenStandardError()) : Task.CompletedTask,
};
Task.WaitAll(copies);
return ExitCode(process);
Pipes not requested in the document are not created, and their handles are invalid: the first version of hcsctl tried to read from such a handle and crashed with "Invalid handle". And this is what runhcs could not do in part 4: the container's output reaches the terminal.
The container name
The name we passed to hcsctl create is the system identifier for HCS. It does not get inside the container: the computer name is set only by GuestOs.HostName, and when we start a container ourselves this field is mandatory. Let's run the same container with different values of the field and the process cmd /c hostname & echo %COMPUTERNAME%:
GuestOs.HostName |
hostname |
%COMPUTERNAME% |
|---|---|---|
| not set | minwinpc |
MINWINPC |
Web-Two |
Web-Two |
WEB-TWO |
abcdefghij12345 |
abcdefghij12345 |
ABCDEFGHIJ12345 |
a-long-container-name2 |
a-long-container-name2 |
A-LONG-CONTAINE |
Without the field all containers have the same name, minwinpc, and applications that write the computer name to their logs or register under it cannot tell one container from another. One field sets both names: hostname as written, and COMPUTERNAME in upper case and no longer than 15 characters, which is the NetBIOS name limit. If an application needs the long name in full, the variable is set in the process document:
{
"CommandLine": "cmd /c hostname & echo %COMPUTERNAME%",
"Environment": { "COMPUTERNAME": "a-long-container-name2" },
"CreateStdOutPipe": true,
"CreateStdErrPipe": true
}
a-long-container-name2
a-long-container-name2
The run-container.ps1 script at the end of this part does the same: it writes the container name to GuestOs.HostName, and for names longer than 15 characters also to COMPUTERNAME.
What HCS knows about the system
hcsctl props hello
{
"Id": "hello",
"SystemType": "Container",
"RuntimeOsType": "Windows",
"Owner": "hcsctl",
"ObRoot": "\\\\.\\Silos\\980",
"State": "Running",
"ServiceSessionId": 4,
"IsolationType": "Process"
}
ObRoot is the root of the container's kernel object namespace, the same \Silos\<number> directory we examined in part 3. ServiceSessionId is the session in which the container's processes run. We stop the system and unmount the writable layer:
hcsctl rm hello
wclayer unmount C:\layers\hello
Network
hello has no network adapter: the document had no Networking section. A container's network in HNS is an endpoint in an HNS network, placed into a network namespace; it is the namespace that is specified in the container document. We will take an existing network, nat, which the CNI plugin created when the web container started, and create the endpoint and the namespace ourselves through computenetwork.dll.
The endpoint is described by JSON that hcsctl net assembles from its arguments:
{
"SchemaVersion": { "Major": 2, "Minor": 0 },
"Owner": "hcsctl",
"HostComputeNetwork": "<GUID of the nat network>",
"IpConfigurations": [ { "IpAddress": "172.30.0.50", "PrefixLength": 16 } ],
"Routes": [ { "NextHop": "172.30.0.1", "DestinationPrefix": "0.0.0.0/0" } ],
"Dns": { "ServerList": [ "172.30.0.1" ] },
"Policies": [
{ "Type": "PortMapping", "Settings": { "Protocol": 6, "ExternalPort": 8081, "InternalPort": 8080 } }
]
}
We set the address ourselves: the one the IPAM plugin would have assigned in part 2. The default route goes through the network gateway, and the DNS server is CoreDNS on the same gateway. PortMapping is the same NAT policy that the nat plugin attached to the endpoint in part 1 for -p 8080:8080; protocol 6 is TCP. Next come the namespace and the endpoint in it:
hr = HcnCreateNamespace(nsId, $$"""{"SchemaVersion": {{Schema}}, "Type": "Host"}""", out var ns, out error);
Check(hr, error, "HcnCreateNamespace");
hr = HcnModifyNamespace(ns, $$$"""{"ResourceType": "Endpoint", "RequestType": "Add", "Settings": {"EndpointId": "{{{endpointId}}}"}}""", out error);
Check(hr, error, "HcnModifyNamespace");
The namespace type matters. At first I wrote HostDefault, and the container would not be created, failing with 0x80070490 (Element not found). HostDefault is the host's default namespace; there is only one, and HNS does not create a new one but returns the existing one, ignoring the GUID passed in. The endpoint went into it, and a namespace with our GUID never appeared. What is needed is the Host type, a separate namespace:
$ns = [guid]::NewGuid()
$ns
hcsctl net $ns nat 172.30.0.50/16 172.30.0.1 172.30.0.1 8081:8080
hnsdiag list namespaces | Select-String -Context 0,1 $ns
ba4ccad4-b088-4197-8445-f73e2c10c8ba
endpoint b4949713-4c59-4304-90cb-9b1f10808b33
address 172.30.0.50
mac 00-15-5D-43-E1-4C
ports 8081:8080
> Namespace : ba4ccad4-b088-4197-8445-f73e2c10c8ba
Endpoint IDs : B4949713-4C59-4304-90CB-9B1F10808B33
The ASP.NET sample
Now let's build a container for the ASP.NET sample from the C:\images\samples image: thirteen layers, a network, a mounted folder and limits. The writable layer goes on top of all the layers from layers.json:
$layers = Get-Content C:\images\samples\layers.json | ConvertFrom-Json
$l = foreach ($p in $layers) { '-l'; $p }
wclayer create @l C:\layers\web2
$volume = wclayer mount @l C:\layers\web2
$volume
\\?\Volume{929f72e1-7355-4b29-9bbf-9b35d34095b0}
There is no reason to type thirteen layers into JSON by hand, so we will build the document in PowerShell:
New-Item -ItemType Directory C:\share -Force | Out-Null
'hello from host' | Set-Content C:\share\hello.txt
[ordered]@{
SchemaVersion = [ordered]@{ Major = 2; Minor = 1 }
Owner = 'hcsctl'
ShouldTerminateOnLastHandleClosed = $false
Container = [ordered]@{
GuestOs = @{ HostName = 'web2' }
Storage = [ordered]@{
Layers = @(foreach ($p in $layers) { [ordered]@{ Id = (hcsctl layer-id $p); Path = $p } })
Path = $volume
}
MappedDirectories = @([ordered]@{ HostPath = 'C:\share'; ContainerPath = 'C:\data'; ReadOnly = $true })
Memory = @{ SizeInMB = 512 }
Processor = @{ Count = 1 }
Networking = [ordered]@{ AllowUnqualifiedDnsQuery = $true; Namespace = "$ns" }
}
} | ConvertTo-Json -Depth 6 | Set-Content web2.json -Encoding ascii
hcsctl create web2 web2.json
The new sections are what the nerdctl flags did in part 1:
MappedDirectoriesare mounted host folders,-v C:\share:C:\data:ro. They are mapped into the container by thebindfltfilter driver from part 3.Memory.SizeInMBandProcessor.Countare--memory 512mand--cpus 1.Networking.Namespaceis the namespace with our endpoint, andAllowUnqualifiedDnsQueryallows queries for short names without a suffix; containerd set the same field in the OCI specification.
Let's check what is inside with a process from inside.json:
{
"CommandLine": "cmd /c hostname & ipconfig | findstr IPv4 & type C:\\data\\hello.txt & echo x> C:\\data\\x.txt",
"CreateStdOutPipe": true,
"CreateStdErrPipe": true
}
hcsctl exec web2 inside.json
web2
IPv4 Address. . . . . . . . . . . : 172.30.0.50
hello from host
Access is denied.
The name, the address, the mounted folder, the write denial: everything is in place. All that is left is to start the application itself. What to start is known from the image configuration, image.json, which pull-image.ps1 saved. Let's move it into a process document:
$config = (Get-Content C:\images\samples\image.json | ConvertFrom-Json).config
$environment = [ordered]@{}
foreach ($e in $config.Env) { $k, $v = $e -split '=', 2; $environment[$k] = $v }
[ordered]@{
CommandLine = $config.Entrypoint -join ' '
WorkingDirectory = $config.WorkingDir
User = $config.User
Environment = $environment
} | ConvertTo-Json | Set-Content app.json -Encoding ascii
Get-Content app.json
hcsctl exec -d web2 app.json
{
"CommandLine": "AspNetCoreRazorApp",
"WorkingDirectory": "C:\\app",
"User": "ContainerUser",
"Environment": {
"ASPNETCORE_HTTP_PORTS": "8080",
"DOTNET_RUNNING_IN_CONTAINER": "true",
"DOTNET_VERSION": "11.0.0-rc.3.26522.148",
"ASPNET_VERSION": "11.0.0-rc.3.26522.148"
}
}
process 4952
This is the part of containerd's work that we saw in the OCI specification in part 4: Entrypoint goes to the command line, Env to the environment, WorkingDir and User as they are. With -d, hcsctl does not wait for the process and exits, while the process keeps running. Let's check from the host, from the web container managed by containerd, and from another machine on the network:
curl.exe -sS -o NUL -w "%{http_code}`n" http://localhost:8081/
nerdctl exec web curl.exe -sS -o NUL -w "%{http_code}`n" http://172.30.0.50:8080/
200
200
curl.exe -sS -o NUL -w "%{http_code}`n" http://192.168.10.30:8081/
200
Port 8081 on the host leads to our container, and the containerd containers and ours live in the same nat network and can reach each other by address.
How it looks from the host
hcsdiag list
Get-Process AspNetCoreRazorApp | Format-Table Name, Id, SessionId
e3f3aa09b67d4555b7619e202e25dca92bc8cd636045dfb1a2849a729052da73
Windows Server Container, Running, , containerd-shim-runhcs-v1.exe, 2
web2
Windows Server Container, Running, , hcsctl, 4
Name Id SessionId
---- -- ---------
AspNetCoreRazorApp 4952 4
AspNetCoreRazorApp 6572 2
Two identical applications in two containers: one in session 2 (the containerd container), the other, ours, in session 4. We will find the memory limit in the job object, as in part 3:
Import-Module NtObjectManager
$session = (hcsctl props web2 | ConvertFrom-Json).ServiceSessionId
$p = Get-Process AspNetCoreRazorApp | Where-Object SessionId -eq $session
$job = Get-NtProcessJob -Process (Get-NtProcess -ProcessId $p.Id)
$job | Format-List Name, LimitFlags, JobMemory
$job.Close()
Name : Container_web2
LimitFlags : JobMemory
JobMemory : 536870912
The job object is named Container_ plus the system name, and the limit is 512 MiB, exactly SizeInMB. $job.Close() is not here for decoration. An open handle keeps the job object alive even after the container stops, and while it is open a container with the same name cannot be created: HcsCreateComputeSystem returns 0x800700B7, "already exists". I ran into this when recreating web2 in the same PowerShell session.
We will check the CPU limit the same way as in part 1: load the container and add up the CPU time of its processes. The cpu-test.ps1 script creates a Nano Server container through hcsctl, with or without Processor.Count, starts four infinite cmd loops in it and sums their CPU time over 10 seconds:
cpu-test.ps1
cpu-test.ps1 -Cpus 1
no limit; session 5; CPU used: 3,98 of 4 cores
Processor.Count 1; session 5; CPU used: 0,99 of 4 cores
Teardown
We remove everything we created in reverse order: the system, the namespace with the endpoint, the writable layer:
hcsctl rm web2
hcsctl net-rm $ns
wclayer unmount C:\layers\web2
hcsdiag list
@(Get-HnsEndpoint | Where-Object IPAddress -eq 172.30.0.50).Count
e3f3aa09b67d4555b7619e202e25dca92bc8cd636045dfb1a2849a729052da73
Windows Server Container, Running, , containerd-shim-runhcs-v1.exe, 2
0
After the system stops, wclayer unmount sometimes prints "hcsshim::UnprepareLayer failed in Win32: The device is not ready", the same message we saw in part 4. The volume is unmounted anyway; on the test machine this did not happen every time, and I found no pattern.
All in one script
The steps of this part are collected in run-container.ps1 and remove-container.ps1, a small runtime on top of wclayer and hcsctl. The first prepares the storage, the network, the system document and a process from the image configuration; the second removes all of it. What was created is recorded in C:\containers\<name>:
run-container.ps1 web2 C:\images\samples -Ip 172.30.0.50 -Publish 8081:8080 -Mount C:\share:C:\data:ro -Memory 512 -Cpus 1
curl.exe -sS -o NUL -w "%{http_code}`n" http://localhost:8081/
Get-ChildItem C:\containers\web2 | Format-Table Name, Length
remove-container.ps1 web2
Test-Path C:\containers\web2
volume \\?\Volume{4b8064d0-52fc-43a5-bb2b-aa514fddb9e2}
endpoint 172.30.0.50 in nat, namespace fd2694b0-f7d0-48aa-9cb3-c0af54c717b6
compute system web2
process 3216
200
Name Length
---- ------
scratch
process.json 424
state.json 136
system.json 6563
False
About a hundred lines of PowerShell and a C# program do what we installed containerd, nerdctl and the CNI plugin for in part 1.
Cleaning up
We no longer need the web container, the images, the writable layers and the working folders from this part. wclayer remove deletes the layer folders, and an ordinary Remove-Item handles the rest:
Set-Location C:\
nerdctl rm -f web
nerdctl rmi mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025
foreach ($d in 'C:\layers\hello', 'C:\layers\web2') { wclayer remove $d }
Get-ChildItem C:\images\*\layers -Directory | ForEach-Object { wclayer remove $_.FullName }
Remove-Item C:\images, C:\layers, C:\share, C:\lab, C:\containers -Recurse -Force
wclayer, hcsctl and the scripts in C:\hcs stay on the server.
What is missing for a real runtime
The container works, but containerd and its shim do more:
- They watch processes. The shim subscribes to HCS events and learns that a process has exited right away rather than by polling. containerd stores the exit code, and nerdctl restarts the container according to its policy and keeps a log of the output, which is what
nerdctl logsshows. - Input and a terminal.
CreateStdInPipeandEmulateConsolein the process document give an interactiveexec -it;hcsctldoes not use them. - They clean up after themselves. If
hcsctlcrashes or the host reboots, the HCS system, the endpoint and the mounted volume remain. containerd remembers what it created and cleans it up on the next start. - Hyper-V isolation. The container runs inside a utility VM with its own kernel. That is the next part.
Summary
- The HCS API is handles, asynchronous operations and JSON documents. Eleven functions from
computecore.dllare enough to create a container, start a process with output in it and stop it. - A process-isolated container document holds layers with GUIDs from
NameToGuid, the writable layer volume, mounted folders, memory and CPU limits and a network namespace. - The network is an HNS endpoint with an address, a route, DNS and a port publishing policy, placed in a namespace of type
Host(notHostDefault). - The user, the environment and the command are up to whoever starts the process: HCS knows nothing about images and by default starts a process as
ContainerAdministrator. - An open job object handle prevents creating a container with the same name.
Sources
- Host Compute System API — Microsoft Learn: the
computecore.dllfunctions and the asynchronous model. - HCS JSON schema reference — Microsoft Learn: system and process documents,
Container,Storage,MappedDirectories,ProcessParameters. - Host Compute Network API — Microsoft Learn:
computenetwork.dll, networks, endpoints and namespaces; HNS document schema. - microsoft/hcsshim — how the containerd shim builds the same documents.
- LibraryImport — Microsoft Learn: generating code for calling unmanaged functions.
Next — Hyper-V isolation: the same container, but inside a utility VM. What changes in the HCS document, where the kernel for that VM comes from and what is visible from the host when the container is not running on its kernel.
Only registered users can leave a comment.
Sign in or register to leave a comment.