Can not specify hyperv isolation mode in buildctl

[QBos07]

Description

#6224 was merged and #5682 closed but i still can not figure out how to use hyperv isolation mode. I am not using docker but buildctl.

[ngebremariam-msft]

PR #6224 added the internal executor support required for Hyper-V isolation, but it did not expose a command-line flag or configuration option to enable it. Based on that implementation, the steps below create a practical test by setting HyperVIsolation: true in the BuildKit source and compiling a custom buildkitd.exe .

This workaround is not documented in the PR. It is a reproducible example that activates and verifies the internal support introduced by the PR.

Note

Clone the repository and run all commands from elevated PowerShell terminals:
git clone https://github.com/moby/buildkit.git

1. Verify Windows features

Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All
Get-WindowsOptionalFeature -Online -FeatureName Containers

Both features must show Enabled .

2. Find the containerd pipe

Get-ChildItem '\\.\pipe\' |
  Where-Object Name -Match 'containerd' |
  Select-Object Name

Set the pipe found on your system. For example:

$ContainerdPipe = '\\.\pipe\desktop-containerd'

Verify the connection:

ctr.exe --address $ContainerdPipe namespaces list

3. Enable Hyper-V isolation

Open worker\containerd\containerd.go :

code worker\containerd\containerd.go

Add HyperVIsolation: true, to executorOpts :

executorOpts := containerdexecutor.ExecutorOptions{
    Client:           client,
    Root:             root,
    NetworkProviders: np,
    ProxyProvider:    proxyProvider,
    HyperVIsolation:  true,
}

This hardcodes Hyper-V isolation in the custom BuildKit binary.

4. Compile BuildKit

New-Item -ItemType Directory -Force .\bin

go build -o .\bin\buildkitd.exe .\cmd\buildkitd
go build -o .\bin\buildctl.exe .\cmd\buildctl

5. Create a test Dockerfile

Create Dockerfile  in the repository root:

FROM mcr.microsoft.com/windows/nanoserver:ltsc2022
RUN ping -n 60 127.0.0.1 >NUL

The delay keeps the build container running long enough to inspect it.

Important

Use three elevated PowerShell terminals:
• Terminal 1: Run  buildkitd .
• Terminal 2: Run  buildctl .
• Terminal 3: Inspect the running container.
Keep Terminals 1 and 2 open during the inspection.

6. Terminal 1: Start BuildKit

$ContainerdPipe = '\\.\pipe\desktop-containerd'

.\bin\buildkitd.exe `
  --addr npipe:////./pipe/buildkitd-hyperv-test `
  --root "$env:ProgramData\buildkitd-hyperv-test" `
  --otel-socket-path \\.\pipe\buildkit-otel-grpc-hyperv-test `
  --containerd-worker-addr $ContainerdPipe `
  --debug

If your containerd pipe has a different name, update $ContainerdPipe.

7. Terminal 2: Start the build

From the repository root:

.\bin\buildctl.exe `
  --addr npipe:////./pipe/buildkitd-hyperv-test `
  build `
  --frontend=dockerfile.v0 `
  --local context=. `
  --local dockerfile=. `
  --progress=plain `
  --no-cache

When the output shows the RUN ping...  step in progress, continue to Terminal 3. Do not run the RUN  instruction manually.

8. Terminal 3: Verify Hyper-V isolation

Set the containerd pipe again because variables do not transfer between terminals:

$ContainerdPipe = '\\.\pipe\desktop-containerd'

Find the active task:

ctr.exe --address $ContainerdPipe --namespace buildkit tasks list

Copy its ID and inspect the container:

ctr.exe --address $ContainerdPipe --namespace buildkit containers info YOUR_TASK_ID

Confirm that the output contains:

"windows": {
  "layerFolders": null,
  "hyperv": {}
}

 layerFolders: null  is expected. The  "hyperv": {}  entry confirms that the build container is using Hyper-V isolation.

After the build finishes, press Ctrl+C in Terminal 1 to stop the custom BuildKit daemon.

[Aziks0]

If this gets closed, #5682 needs to be reopened. The issue hasn't been fixed as far as I know, there is still no way to use buildkit with Hyper-V.

[ngebremariam-msft]

Thanks for bringing this up, you're right, and I've reopened the issue. That should cover your concern without needing to reopen #5682, since #6224 did land the executor support (verified: a RUN step produces "hyperv": {} in the container spec). What's still missing is any way to select it: no  buildkitd  flag, no config key, no  buildctl --opt. That's what this issue will track. My comment above is a workaround, not a fix