Merge pull request #19792 from dvdksn/buildkit-windows-exp

build: experimental test instruction buildkit.exe

Author: dvdksn

content/build/buildkit/_index.md

@@ -105,9 +105,150 @@ If the `/etc/docker/daemon.json` file doesn't exist, create new file called
 `daemon.json` and then add the following to the file. And restart the Docker
 daemon.
 
+## BuildKit on Windows
+
 > **Warning**
 >
-> BuildKit only fully supports building Linux containers. Experimental Windows
-> container support is tracked in
-> [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616)
+> BuildKit only fully supports building Linux containers.
+> Windows container support is experimental, and is tracked in
+> [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616).
 { .warning }
+
+BuildKit has experimental support for Windows containers (WCOW) as of version 0.13.
+This section walks you through the steps for trying it out.
+We appreciate any feedback you submit by [opening an issue here](https://github.com/moby/buildkit/issues/new), especially `buildkitd.exe`.
+
+### Known limitations
+
+- BuildKit on Windows currently only supports the `containerd` worker.
+  Support for non-OCI workers is tracked in [moby/buildkit#4836](https://github.com/moby/buildkit/issues/4836).
+
+### Prerequisites
+
+- Architecture: `amd64`, `arm64` (binaries available but not officially tested yet).
+- Supported OS: Windows Server 2019, Windows Server 2022, Windows 11.
+- Base images: `ServerCore:ltsc2019`, `ServerCore:ltsc2022`, `NanoServer:ltsc2022`.
+  See the [compatibility map here](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-2019%2Cwindows-11#windows-server-host-os-compatibility).
+- Docker Desktop version 4.29 or later
+
+### Steps
+
+> **Note**
+>
+> The following commands require administrator (elevated) privileges in a PowerShell terminal.
+
+1. Enable the **Hyper-V** and **Containers** Windows features.
+
+   ```console
+   > Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V, Containers -All
+   ```
+
+   If you see `RestartNeeded` as `True`, restart your machine and re-open a PowerShell terminal as an administrator.
+   Otherwise, continue with the next step.
+
+2. Switch to Windows containers in Docker Desktop.
+
+   Select the Docker icon in the taskbar, and then **Switch to Windows containers...**.
+
+3. Install containerd version 1.7.7 or later following the setup instructions [here](https://github.com/containerd/containerd/blob/main/docs/getting-started.md#installing-containerd-on-windows).
+
+4. Download and extract the latest BuildKit release.
+
+   ```powershell
+   $version = "v0.13.1" # specify the release version, v0.13+
+   $arch = "amd64" # arm64 binary available too
+   curl.exe -LO https://github.com/moby/buildkit/releases/download/$version/buildkit-$version.windows-$arch.tar.gz
+   # there could be another `.\bin` directory from containerd instructions
+   # you can move those
+   mv bin bin2
+   tar.exe xvf .\buildkit-$version.windows-$arch.tar.gz
+   ## x bin/
+   ## x bin/buildctl.exe
+   ## x bin/buildkitd.exe
+   ```
+
+5. Install BuildKit binaries on `PATH`.
+
+   ```powershell
+   # after the binaries are extracted in the bin directory
+   # move them to an appropriate path in your $Env:PATH directories or:
+   Copy-Item -Path ".\bin" -Destination "$Env:ProgramFiles\buildkit" -Recurse -Force
+   # add `buildkitd.exe` and `buildctl.exe` binaries in the $Env:PATH
+   $Path = [Environment]::GetEnvironmentVariable("PATH", "Machine") + `
+       [IO.Path]::PathSeparator + "$Env:ProgramFiles\buildkit"
+   [Environment]::SetEnvironmentVariable( "Path", $Path, "Machine")
+   $Env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + `
+       [System.Environment]::GetEnvironmentVariable("Path","User")
+   ```
+6. Start `buildkitd.exe`.
+
+   ```console
+   > buildkitd.exe
+   time="2024-02-26T10:42:16+03:00" level=warning msg="using null network as the default"
+   time="2024-02-26T10:42:16+03:00" level=info msg="found worker \"zcy8j5dyjn3gztjv6gv9kn037\", labels=map[org.mobyproject.buildkit.worker.containerd.namespace:buildkit org.mobyproject.buildkit.worker.containerd.uuid:c30661c1-5115-45de-9277-a6386185a283 org.mobyproject.buildkit.worker.executor:containerd org.mobyproject.buildkit.worker.hostname:[deducted] org.mobyproject.buildkit.worker.network: org.mobyproject.buildkit.worker.selinux.enabled:false org.mobyproject.buildkit.worker.snapshotter:windows], platforms=[windows/amd64]"
+   time="2024-02-26T10:42:16+03:00" level=info msg="found 1 workers, default=\"zcy8j5dyjn3gztjv6gv9kn037\""
+   time="2024-02-26T10:42:16+03:00" level=warning msg="currently, only the default worker can be used."
+   time="2024-02-26T10:42:16+03:00" level=info msg="running server on //./pipe/buildkitd"
+   ```
+
+7. In another terminal with administrator privileges, create a remote builder that uses the local BuildKit daemon.
+
+   > **Note**
+   >
+   > This requires Docker Desktop version 4.29 or later.
+
+   ```console
+   > docker buildx create --name buildkit-exp --use --driver=remote npipe:////./pipe/buildkitd
+   buildkit-exp
+   ```
+
+8. Verify the builder connection by running `docker buildx inspect`.
+
+   ```console
+   > docker buildx inspect
+   Name:          buildkit-exp
+    Driver:        remote
+    Last Activity: 2024-04-15 17:51:58 +0000 UTC
+    Nodes:
+    Name:             buildkit-exp0
+    Endpoint:         npipe:////./pipe/buildkitd
+    Status:           running
+    BuildKit version: v0.13.1
+    Platforms:        windows/amd64
+   ...
+   ```
+
+9. Create a Dockerfile and build a `hello-world` image.
+
+   ```console
+   > mkdir sample_dockerfile
+   > cd sample_dockerfile
+   > Set-Content Dockerfile @"
+   FROM mcr.microsoft.com/windows/nanoserver:ltsc2022
+   USER ContainerAdministrator
+   COPY hello.txt C:/
+   RUN echo "Goodbye!" >> hello.txt
+   CMD ["cmd", "/C", "type C:\\hello.txt"]
+   "@
+   Set-Content hello.txt @"
+   Hello from BuildKit!
+   This message shows that your installation appears to be working correctly.
+   "@
+   ```
+
+   > **Note**
+   >
+   > For a consistent experience, use forward-slashes `/` for paths, e.g. `C:/` instead of `C:\`.
+   > Support for Windows-style paths is tracked in [moby/buildkit#4696](https://github.com/moby/buildkit/issues/4696).
+
+10. Build and push the image to a registry.
+
+    ```console
+    > docker buildx build --push -t <username>/hello-buildkit .
+    ```
+
+11. After pushing to the registry, run the image with `docker run`.
+
+    ```console
+    > docker run <username>/hello-world
+    ```