Merge pull request #1782 from jedevc/docs-monitor

docs: add initial guide about debugging monitor mode

docs/guides/debugging.md

@@ -0,0 +1,113 @@
+# 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
+```
+
+## 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
+/ # 
+```