From af3feec4eaaee894b218e7d1ce082b71bf018dc7 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Fri, 19 May 2023 14:51:30 +0100 Subject: [PATCH 1/2] docs: fixup typo in buildkit console output Signed-off-by: Justin Chadwell --- docs/guides/debugging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md index 90a9fd27..87f57a9d 100644 --- a/docs/guides/debugging.md +++ b/docs/guides/debugging.md @@ -24,7 +24,7 @@ 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 +[+] 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 @@ -93,7 +93,7 @@ immediately enter the monitor mode. ```console $ docker buildx debug-shell -+] Building 0.0s (1/1) FINISHED +[+] Building 0.0s (1/1) FINISHED => [internal] connecting to remote controller (buildx) list ID CURRENT_SESSION From 4ce80856b39495fd745262ff4b2ec6d31800ded5 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Fri, 19 May 2023 14:51:51 +0100 Subject: [PATCH 2/2] docs: add info for on-error and debug-shell values for invoke Signed-off-by: Justin Chadwell --- docs/guides/debugging.md | 41 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md index 87f57a9d..df1b49b8 100644 --- a/docs/guides/debugging.md +++ b/docs/guides/debugging.md @@ -49,6 +49,47 @@ 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.