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

desktop/builds view (#17592) 

* build: add a 'builders' section

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* desktop: builds view and builder settings

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

* build: manage redirects for build/ui

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

---------

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2023-06-29 18:44:12 +02:00 committed by GitHub
parent 4523221101
commit 7abffab6b3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 350 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
_data/toc.yaml
View File

@ -1120,6 +1120,8 @@ manuals:
title: Explore Images
- path: /desktop/use-desktop/volumes/
title: Explore Volumes
- path: /desktop/use-desktop/builds/
title: Explore Builds (Beta)
- path: /desktop/use-desktop/pause/
title: Pause Docker Desktop
- sectiontitle: Hardened Docker Desktop
@ -1683,6 +1685,12 @@ manuals:
title: OpenTelemetry support
- path: /build/building/base-images/
title: Create your own base image
- sectiontitle: Builders
section:
- path: /build/builders/
title: Builders overview
- path: /build/builders/manage/
title: Manage builders
- sectiontitle: Drivers
section:
- path: /build/drivers/

62
_includes/desktop-builders-setting.md Normal file
View File

@ -0,0 +1,62 @@
If you have turned on the
[Docker Desktop Builds view](/desktop/use-desktop/builds/), you can use the
**Builders** tab to inspect and manage builders in the Docker Desktop settings.
### Inspect
To inspect builders, find the builder that you want to inspect and select the
expand icon. You can only inspect active builders.
The detailed builder view shows:
- Builder status
- Information about the BuildKit runtime
- Capabilities and driver type
- Supported platforms
- Disk usage
### Select a different builder
The **Selected builder** section displays the selected builder.
To select a different builder:
1. Find the builder that you want to use under **Available builders**
2. Open the drop-down menu next to the builder's name.
3. Select **Use** to switch to this builder.
Your build commands now use the selected builder by default.
### Create a builder
To create a builder, use the Docker CLI. See
[Create a new builder](/build/builders/manage/#create-a-new-builder)
### Remove a builder
You can remove a builder if:
- The builder isn't your [selected builder](/build/builders/#selected-builder)
- The builder isn't [associated with a Docker context](/build/builders/#default-builder).
To remove builders associated with a Docker context, remove the context using
the `docker context rm` command.
To remove a builder:
1. Find the builder that you want to remove under **Available builders**
2. Open the drop-down menu.
3. Select **Remove** to remove this builder.
If the builder uses the `docker-container` or `kubernetes` driver,
the build cache is also removed, along with the builder.
### Stop and start a builder
Builders that use the
[`docker-container` driver](/build/drivers/docker-container/)
run the BuildKit daemon in a container.
You can start and stop the BuildKit container using the drop-down menu.
Running a build automatically starts the container if it's stopped.
You can only start and stop builders using the `docker-container` driver.

8
_redirects.yml
View File

@ -569,6 +569,10 @@
"/develop/remote-development/":
- /go/telepresence/
# Builders
"/build/drivers/":
# Build links
"/desktop/use-desktop/builds/":
- /go/builds/
"/build/builders/":
- /go/builders/
"/build/builders/#selected-builder":
- /go/builders/selected/

12
build/architecture.md
View File

@ -48,17 +48,7 @@ A builder may run on the same system as the Buildx client, or it may run
remotely, on a different system. You can run it as a single node, or as a cluster
of nodes. Builder nodes may be containers, virtual machines, or physical machines.
How and where you run your builders depends on your use case. Buildx implements
a concept of [build drivers](./drivers/index.md) to refer to different types of
builder configurations. Buildx supports the following drivers:
- `docker`: uses the BuildKit library bundled into the Docker daemon.
- `docker-container`: creates a dedicated BuildKit container using Docker.
- `kubernetes`: creates BuildKit pods in a Kubernetes cluster.
- `remote`: connects directly to a manually managed BuildKit daemon.
You can create, append, and connect to builders and nodes using the
[`docker buildx create` command](../engine/reference/commandline/buildx_create.md).
For more information, see [Builders](./builders/index.md).
## BuildKit

79
build/builders/index.md Normal file
View File

@ -0,0 +1,79 @@
---
title: "Builders"
keywords: build, buildx, builders, buildkit, drivers, backend
description:
---
A builder is a BuildKit daemon that you can use to run your builds. BuildKit
is the build engine that solves the build steps in a Dockerfile to produce a
container image or other artifacts.
You can create and manage builders, inspect them, and even connect to builders
running remotely. You interact with builders using the Docker CLI.
> **Builds in Docker Desktop**
>
> The [Docker Desktop Builds view](../../desktop/use-desktop/builds.md)
> is a [Beta](../../release-lifecycle.md#beta) feature that lets you
> view and manage builders using Docker Desktop.
{: .experimental }
## Default builder
Docker Engine automatically creates a builder that becomes the default backend
for your builds. This builder uses the BuildKit library bundled with the
daemon. This builder requires no configuration.
The default builder is directly bound to the Docker daemon and its
[context](../../engine/context/working-with-contexts.md). If you change the
Docker context, your `default` builder refers to the new Docker context.
## Build drivers
Buildx implements a concept of [build drivers](../drivers/index.md) to refer to
different builder configurations. The default builder created by the daemon
uses the [`docker` driver](../drivers/docker.md).
Buildx supports the following build drivers:
- `docker`: uses the BuildKit library bundled into the Docker daemon.
- `docker-container`: creates a dedicated BuildKit container using Docker.
- `kubernetes`: creates BuildKit pods in a Kubernetes cluster.
- `remote`: connects directly to a manually managed BuildKit daemon.
## Selected builder
Selected builder refers to the builder that's used by default when you run
build commands.
When you run a build, or interact with builders in some way using the CLI,
you can use the optional `--builder` flag, or the `BUILDX_BUILDER`
[environment variable](../building/env-vars.md#buildx_builder),
to specify a builder by name. If you don't specify a builder,
the selected builder is used.
Use the `docker buildx ls` command to see the available builder instances.
The asterisk (`*`) next to a builder name indicates the selected builder.
```console
$ docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default * docker
default default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
my_builder docker-container
my_builder0 default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
```
### Select a different builder
To switch between builders, use the `docker buildx use <name>` command.
After running this command, the builder you specify is automatically
selected when you invoke builds.
## Additional information
- For information about how to interact with and manage builders,
see [Manage builders](./manage.md)
- To learn about different types of builders,
see [Build drivers](../drivers/index.md)

108
build/builders/manage.md Normal file
View File

@ -0,0 +1,108 @@
---
title: "Manage builders"
keywords: build, buildx, builders, buildkit, drivers, backend
description:
---
You can create, inspect, and manage builders using `docker buildx` commands,
or [using Docker Desktop](#manage-builders-with-docker-desktop).
## Create a new builder
The default builder uses the [`docker` driver](../drivers/docker.md).
You can't manually create new `docker` builders, but you can create builders
that use other drivers, such as the
[`docker-container` driver](../drivers/docker-container.md),
which runs the BuildKit daemon in a container.
Use the
[`docker buildx create`](../../engine/reference/commandline/buildx_create.md)
command to create a builder.
```console
$ docker buildx create --name=<builder-name>
```
Buildx uses the `docker-container` driver by default if you omit the `--driver`
flag. For more information about available drivers, see
[Build drivers](../drivers/index.md).
## List available builders
Use `docker buildx ls` to see builder instances available on your system, and
the drivers they're using.
```console
$ docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default * docker
default default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
my_builder docker-container
my_builder0 default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
```
The asterisk (`*`) next to the builder name indicates the
[selected builder](index.md#selected-builder).
## Inspect a builder
To inspect a builder with the CLI, use `docker buildx inspect <name>`.
You can only inspect a builder if the builder is active.
You can add the `--bootstrap` flag to the command to start the builder.
```console
$ docker buildx inspect --bootstrap my_builder
[+] Building 1.7s (1/1) FINISHED
=> [internal] booting buildkit 1.7s
=> => pulling image moby/buildkit:buildx-stable-1 1.3s
=> => creating container buildx_buildkit_my_builder0 0.4s
Name: my_builder
Driver: docker-container
Last Activity: 2023-06-21 18:28:37 +0000 UTC
Nodes:
Name: my_builder0
Endpoint: unix:///var/run/docker.sock
Status: running
Buildkit: v0.11.6
Platforms: linux/arm64, linux/amd64, linux/amd64/v2, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6
```
If you want to see how much disk space a builder is using, use the
`docker buildx du` command. By default, this command shows the total disk usage
for all available builders. To see usage for a specific builder, use the
`--builder` flag.
```console
$ docker buildx du --builder my_builder
ID RECLAIMABLE SIZE LAST ACCESSED
olkri5gq6zsh8q2819i69aq6l true 797.2MB 37 seconds ago
6km4kasxgsywxkm6cxybdumbb* true 438.5MB 36 seconds ago
qh3wwwda7gx2s5u4hsk0kp4w7 true 213.8MB 37 seconds ago
54qq1egqem8max3lxq6180cj8 true 200.2MB 37 seconds ago
ndlp969ku0950bmrw9muolw0c* true 116.7MB 37 seconds ago
u52rcsnfd1brwc0chwsesb3io* true 116.7MB 37 seconds ago
rzoeay0s4nmss8ub59z6lwj7d true 46.25MB 4 minutes ago
itk1iibhmv7awmidiwbef633q true 33.33MB 37 seconds ago
4p78yqnbmgt6xhcxqitdieeln true 19.46MB 4 minutes ago
dgkjvv4ay0szmr9bl7ynla7fy* true 19.24MB 36 seconds ago
tuep198kmcw299qc9e4d1a8q2 true 8.663MB 4 minutes ago
n1wzhauk9rpmt6ib1es7dktvj true 20.7kB 4 minutes ago
0a2xfhinvndki99y69157udlm true 16.56kB 37 seconds ago
gf0z1ypz54npfererqfeyhinn true 16.38kB 37 seconds ago
nz505f12cnsu739dw2pw0q78c true 8.192kB 37 seconds ago
hwpcyq5hdfvioltmkxu7fzwhb* true 8.192kB 37 seconds ago
acekq89snc7j6im1rjdizvsg1* true 8.192kB 37 seconds ago
Reclaimable: 2.01GB
Total: 2.01GB
```
## Manage builders with Docker Desktop
If you have turned on the
[Docker Desktop Builds view](../../desktop/use-desktop/builds.md),
you can inspect builders in Docker Desktop settings. See:
- [Change settings, Windows](../../desktop/settings/windows.md#builders)
- [Change settings, Mac](../../desktop/settings/mac.md#builders)
- [Change settings, Linux](../../desktop/settings/linux.md#builders)

57
build/drivers/index.md
View File

@ -31,63 +31,6 @@ The following table outlines some differences between drivers.
| **Multi-arch images** | | ✅ | ✅ | ✅ |
| **BuildKit configuration** | | ✅ | ✅ | Managed externally |
## List available builders
Use `docker buildx ls` to see builder instances available on your system, and
the drivers they're using.
```console
$ docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default docker
default default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
```
Depending on your setup, you may find multiple builders in your list that use
the Docker driver. For example, on a system that runs both a manually installed
version of dockerd, as well as Docker Desktop, you might see the following
output from `docker buildx ls`:
```console
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default docker
default default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
desktop-linux * docker
desktop-linux desktop-linux running v0.11.6 linux/arm64, linux/amd64, linux/amd64/v2, linux/riscv64, linux/ppc64le, linux/s390x, linux/mips64le, linux/mips64
```
This is because the Docker driver builders are automatically pulled from the
available [Docker Contexts](../../engine/context/working-with-contexts.md). When
you add new contexts using `docker context create`, these will appear in your
list of buildx builders.
The asterisk (`*`) next to the builder name indicates that this is the selected
builder which gets used by default, unless you specify a builder using the
`--builder` option.
## Create a new builder
Use the
[`docker buildx create`](../../engine/reference/commandline/buildx_create.md)
command to create a builder, and specify the driver using the `--driver` option.
```console
$ docker buildx create --name=<builder-name> --driver=<driver> --driver-opt=<driver-options>
```
This creates a new builder instance with a single build node. After creating a
new builder you can also
[append new nodes to it](../../engine/reference/commandline/buildx_create/#append).
To use a remote node for your builders, you can set the `DOCKER_HOST`
environment variable or provide a remote context name when creating the builder.
## Switch between builders
To switch between different builders, use the `docker buildx use <name>`
command. After running this command, the build commands will automatically use
this builder.
## What's next
Read about each of the Buildx drivers to learn about how they work and how to

4
desktop/settings/linux.md
View File

@ -157,6 +157,10 @@ To see the full list of possible configuration options, see the
Select **Apply & Restart** to save your settings and restart Docker Desktop.
## Builders
{% include desktop-builders-setting.md %}
## Kubernetes
Docker Desktop includes a standalone Kubernetes server, so that you can test

4
desktop/settings/mac.md
View File

@ -202,6 +202,10 @@ To see the full list of possible configuration options, see the
Select **Apply & Restart** to save your settings and restart Docker Desktop.
## Builders
{% include desktop-builders-setting.md %}
## Kubernetes
Docker Desktop includes a standalone Kubernetes server, so that you can test

4
desktop/settings/windows.md
View File

@ -236,6 +236,10 @@ To see the full list of possible configuration options, see the
Select **Apply & Restart** to save your settings and restart Docker Desktop.
## Builders
{% include desktop-builders-setting.md %}
## Kubernetes
> **Note**

74
desktop/use-desktop/builds.md Normal file
View File

@ -0,0 +1,74 @@
---
title: Explore Builds (Beta)
description: Understand how to use the Builds view in Docker Desktop
keywords: Docker Dashboard, manage, gui, dashboard, builders, builds
---
The **Builds** view is a simple interface that lets you inspect your build
history and manage builders using Docker Desktop. By default, it
displays a list of all your ongoing and completed builds.
> **Beta feature**
>
> The **Builds** view is currently in [Beta](../../release-lifecycle.md/#beta).
> This feature may change or be removed from future releases.
{: .experimental }
The **Builds** view displays metadata about the build, such as:
- Build name
- Target platforms
- Builder name
- Build duration
- Progress bar
- Cache usage
- Completion date
The **Active builds** section displays builds that are currently running on
builders that you're using.
The **Completed builds** section lists build records for past builds for your
active builders. The list doesn't include builds for inactive builders.
## Turn on the Builds view
1. Navigate to **Settings**.
2. Select **Features in development**.
3. In the **Beta features** tab, select the **Display Builds view** checkbox.
4. Select **Apply & restart** for the changes to take effect.
After the restart, the **Builds** view and the **Builders** settings menu
appear.
## Inspect a build
To inspect a build, select the build that you want to view in the list.
The **Info** tab displays details about the build job. The details include
information such as target stage for multi-stage builds, target platforms, and
version control information, if available.
The **Source** tab shows the [frontend](../../build/dockerfile/frontend.md)
used to create the build.
The **Error** tab appears if the build finished with an error. It displays the
[frontend](../../build/dockerfile/frontend.md) used to create the build, and
the build error displays inline in the frontend source.
The **Logs** tab displays the build logs. If the build is currently running,
the logs are updated in real-time.
The **Stats** tab displays statistics data about completed builds. Analyze the
build stats to get a better understanding of how your build gets executed, and
find ways to optimize it.
## Manage builders
To inspect your builders, and change your default builder, select
**Builder settings** to open the settings menu. For more information, see:
- [Change settings, Windows](../settings/windows.md#builders)
- [Change settings, Mac](../settings/mac.md#builders)
- [Change settings, Linux](../settings/linux.md#builders)