docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

build: experimental test instruction buildkit.exe
This commit is contained in:
David Karlsson 2024-04-16 08:59:01 +02:00 committed by GitHub
parent 2abe7d9073 2b137114fe
commit 37f10b360c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 144 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
content/build/buildkit/_index.md
View File

@ -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
```