mirror of
https://gitea.com/Lydanne/buildx.git
synced 2025-11-04 18:13:42 +08:00
154 lines
6.3 KiB
Markdown
154 lines
6.3 KiB
Markdown
# Debug monitor
|
|
|
|
To assist with creating and debugging complex builds, Buildx provides a
|
|
debugger to help you step through the build process and easily inspect the
|
|
state of the build environment at any point.
|
|
|
|
> **Note**
|
|
>
|
|
> The debug monitor is a new experimental feature in recent versions of Buildx.
|
|
> There are rough edges, known bugs, and missing features. Please try it out
|
|
> and let us know what you think!
|
|
|
|
## Starting the debugger
|
|
|
|
To start the debugger, first, ensure that `BUILDX_EXPERIMENTAL=1` is set in
|
|
your environment.
|
|
|
|
```console
|
|
$ export BUILDX_EXPERIMENTAL=1
|
|
```
|
|
|
|
To start a debug session for a build, you can use the `--invoke` flag with the
|
|
build command to specify a command to launch in the resulting image.
|
|
|
|
```console
|
|
$ docker buildx build --invoke /bin/sh .
|
|
[+] Building 4.2s (19/19) FINISHED
|
|
=> [internal] connecting to local controller 0.0s
|
|
=> [internal] load build definition from Dockerfile 0.0s
|
|
=> => transferring dockerfile: 32B 0.0s
|
|
=> [internal] load .dockerignore 0.0s
|
|
=> => transferring context: 34B 0.0s
|
|
...
|
|
Launching interactive container. Press Ctrl-a-c to switch to monitor console
|
|
Interactive container was restarted with process "dzz7pjb4pk1mj29xqrx0ac3oj". Press Ctrl-a-c to switch to the new container
|
|
Switched IO
|
|
/ #
|
|
```
|
|
|
|
This launches a `/bin/sh` process in the final stage of the image, and allows
|
|
you to explore the contents of the image, without needing to export or load the
|
|
image outside of the builder.
|
|
|
|
For example, you can use `ls` to see the contents of the image:
|
|
|
|
```console
|
|
/ # ls
|
|
bin etc lib mnt proc run srv tmp var
|
|
dev home media opt root sbin sys usr work
|
|
```
|
|
|
|
#### `on-error`
|
|
|
|
If you want to start a debug session when a build fails, you can use
|
|
`--invoke=on-error` to start a debug session when the build fails.
|
|
|
|
```console
|
|
$ docker buildx build --invoke on-error .
|
|
[+] Building 4.2s (19/19) FINISHED
|
|
=> [internal] connecting to local controller 0.0s
|
|
=> [internal] load build definition from Dockerfile 0.0s
|
|
=> => transferring dockerfile: 32B 0.0s
|
|
=> [internal] load .dockerignore 0.0s
|
|
=> => transferring context: 34B 0.0s
|
|
...
|
|
=> ERROR [shell 10/10] RUN bad-command
|
|
------
|
|
> [shell 10/10] RUN bad-command:
|
|
#0 0.049 /bin/sh: bad-command: not found
|
|
------
|
|
Launching interactive container. Press Ctrl-a-c to switch to monitor console
|
|
Interactive container was restarted with process "edmzor60nrag7rh1mbi4o9lm8". Press Ctrl-a-c to switch to the new container
|
|
/ #
|
|
```
|
|
|
|
This allows you to explore the state of the image when the build failed.
|
|
|
|
#### `debug-shell`
|
|
|
|
If you want to drop into a debug session without first starting the build, you
|
|
can use `--invoke=debug-shell` to start a debug session.
|
|
|
|
```
|
|
$ docker buildx build --invoke debug-shell .
|
|
[+] Building 4.2s (19/19) FINISHED
|
|
=> [internal] connecting to local controller 0.0s
|
|
(buildx)
|
|
```
|
|
|
|
You can then use the commands available in [monitor mode](#monitor-mode) to
|
|
start and observe the build.
|
|
|
|
## Monitor mode
|
|
|
|
By default, when debugging, you'll be dropped into a shell in the final stage.
|
|
|
|
When you're in a debug shell, you can use the `Ctrl-a-c` key combination (press
|
|
`Ctrl`+`a` together, lift, then press `c`) to toggle between the debug shell
|
|
and the monitor mode. In monitor mode, you can run commands that control the
|
|
debug environment.
|
|
|
|
```console
|
|
(buildx) help
|
|
Available commands are:
|
|
attach attach to a buildx server or a process in the container
|
|
disconnect disconnect a client from a buildx server. Specific session ID can be specified an arg
|
|
exec execute a process in the interactive container
|
|
exit exits monitor
|
|
help shows this message
|
|
kill kill buildx server
|
|
list list buildx sessions
|
|
ps list processes invoked by "exec". Use "attach" to attach IO to that process
|
|
reload reloads the context and build it
|
|
rollback re-runs the interactive container with initial rootfs contents
|
|
```
|
|
|
|
## Build controllers
|
|
|
|
Debugging is performed using a buildx "controller", which provides a high-level
|
|
abstraction to perform builds. By default, the local controller is used for a
|
|
more stable experience which runs all builds in-process. However, you can also
|
|
use the remote controller to detach the build process from the CLI.
|
|
|
|
To detach the build process from the CLI, you can use the `--detach=true` flag with
|
|
the build command.
|
|
|
|
```console
|
|
$ docker buildx build --detach=true --invoke /bin/sh .
|
|
```
|
|
|
|
If you start a debugging session using the `--invoke` flag with a detached
|
|
build, then you can attach to it using the `buildx debug-shell` subcommand to
|
|
immediately enter the monitor mode.
|
|
|
|
```console
|
|
$ docker buildx debug-shell
|
|
[+] Building 0.0s (1/1) FINISHED
|
|
=> [internal] connecting to remote controller
|
|
(buildx) list
|
|
ID CURRENT_SESSION
|
|
xfe1162ovd9def8yapb4ys66t false
|
|
(buildx) attach xfe1162ovd9def8yapb4ys66t
|
|
Attached to process "". Press Ctrl-a-c to switch to the new container
|
|
(buildx) ps
|
|
PID CURRENT_SESSION COMMAND
|
|
3ug8iqaufiwwnukimhqqt06jz false [sh]
|
|
(buildx) attach 3ug8iqaufiwwnukimhqqt06jz
|
|
Attached to process "3ug8iqaufiwwnukimhqqt06jz". Press Ctrl-a-c to switch to the new container
|
|
(buildx) Switched IO
|
|
/ # ls
|
|
bin etc lib mnt proc run srv tmp var
|
|
dev home media opt root sbin sys usr work
|
|
/ #
|
|
``` |