Skip to content

Latest commit

 

History

History
113 lines (93 loc) · 4.54 KB

debugging.md

File metadata and controls

113 lines (93 loc) · 4.54 KB
Raw

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.

$ 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.

$ 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:

/ # ls
bin    etc    lib    mnt    proc   run    srv    tmp    var
dev    home   media  opt    root   sbin   sys    usr    work

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.

(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.

$ 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.

$ 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
/ #