Buildg: A tool to interactively debug Dockerfile

Related tags

DevOps Tools buildg
Overview

buildg: A tool to interactively debug Dockerfile

buildg is a tool to interactively debug Dockerfile based on BuildKit.

  • Source-level inspection
  • Breakpoints and step execution
  • Interactive shell on a step with your own debugigng tools
  • Based on BuildKit (needs unmerged patches)
  • Supports rootless

early stage software This is implemented based on BuildKit with some unmerged patches. We're planning to upstream them.

How to use

buildg debug /path/to/build/context

To use your own image for debugging steps:

buildg debug --image=debugging-tools /path/to/build/context

Exmaple

Debug the following Dockerfile:

FROM busybox AS build1
RUN echo hello > /hello

FROM busybox AS build2
RUN echo hi > /hi

FROM scratch
COPY --from=build1 /hello /
COPY --from=build2 /hi /

Store this Dockerfile to somewhere (e.g. /tmp/ctx/Dockerfile) then run buildg debug. buildg.sh can be used for rootless execution (discussed later).

/hello 3| 4| FROM busybox AS build2 => 5| RUN echo hi > /hi 6| 7| FROM scratch 8| COPY --from=build1 /hello / >>> break 2 >>> breakpoints [0]: line: Dockerfile:2 [on-fail]: breaks on fail >>> continue #4 extracting sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0.0s done #4 DONE 0.3s #5 [build1 2/2] RUN echo hello > /hello #5 ... #6 [build2 2/2] RUN echo hi > /hi Breakpoint: line: Dockerfile:2: reached Filename: "Dockerfile" 1| FROM busybox AS build1 *=> 2| RUN echo hello > /hello 3| 4| FROM busybox AS build2 5| RUN echo hi > /hi >>> exec --image sh # cat /etc/os-release PRETTY_NAME="Ubuntu 22.04 LTS" NAME="Ubuntu" VERSION_ID="22.04" VERSION="22.04 LTS (Jammy Jellyfish)" VERSION_CODENAME=jammy ID=ubuntu ID_LIKE=debian HOME_URL="https://www.ubuntu.com/" SUPPORT_URL="https://help.ubuntu.com/" BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" UBUNTU_CODENAME=jammy # ls /debugroot/ bin dev etc hello home proc root tmp usr var # cat /debugroot/hello hello # >>> quit">
$ buildg.sh debug --image=ubuntu:22.04 /tmp/ctx
WARN[2022-05-10T10:21:14Z] using host network as the default            
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 195B done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 2B done
#2 DONE 0.1s

#3 [internal] load metadata for docker.io/library/busybox:latest
#3 DONE 3.1s

#4 [build2 1/2] FROM docker.io/library/[email protected]:d2b53584f580310186df7a2055ce3ff83cc0df6caacf1e3489bff8cf5d0af5d8
#4 resolve docker.io/library/[email protected]:d2b53584f580310186df7a2055ce3ff83cc0df6caacf1e3489bff8cf5d0af5d8 0.0s done
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 772.81kB / 772.81kB 0.2s done
Filename: "Dockerfile"
      2| RUN echo hello > /hello
      3| 
      4| FROM busybox AS build2
 =>   5| RUN echo hi > /hi
      6| 
      7| FROM scratch
      8| COPY --from=build1 /hello /
>>> break 2
>>> breakpoints
[0]: line: Dockerfile:2
[on-fail]: breaks on fail
>>> continue
#4 extracting sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0.0s done
#4 DONE 0.3s

#5 [build1 2/2] RUN echo hello > /hello
#5 ...

#6 [build2 2/2] RUN echo hi > /hi
Breakpoint: line: Dockerfile:2: reached
Filename: "Dockerfile"
      1| FROM busybox AS build1
*=>   2| RUN echo hello > /hello
      3| 
      4| FROM busybox AS build2
      5| RUN echo hi > /hi
>>> exec --image sh
# cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy
# ls /debugroot/
bin  dev  etc  hello  home  proc  root	tmp  usr  var
# cat /debugroot/hello
hello
# 
>>> quit

Install

Release binaries

Available from https://github.com/ktock/buildg/releases

Building using make

Go 1.18+ is needed.

$ git clone https://github.com/ktock/buildg
$ cd buildg
$ make
$ sudo make install

Rootless mode

Install and use buildg.sh. RootlessKit and slirp4netns are needed.

$ buildg.sh debug /tmp/mybuild

The doc in BuildKit project for troubleshooting: https://github.com/moby/buildkit/blob/master/docs/rootless.md#troubleshooting

Motivation

Debugging a large and complex Dockerfile isn't easy and can take a long time. The goal of buildg is to solve it by providing a way to insepct the detailed execution state of a Dockerfile in an interactive and easy-to-use UI/UX.

BuildKit project has been working on better debugging support (e.g. moby/buildkit#2813, moby/buildkit#1472, moby/buildkit#749). Leveraging the generic features added through the work, this project implements a PoC for providing easy UI/UX to debug Dockerfile.

Similar projects

  • buildctl by BuildKit : has debug commands to inspect buildkitd, LLB, etc. but no interactive debugging for builds.
  • cntr : allows attaching and debugging containers but no interactive debugging for builds.
  • ctr by containerd : allows directly controlling and inspecting containerd resources (e.g. contents, snapshots, etc.) but no interactive debugging for builds.

Command reference

$ buildg --help
NAME:
   buildg - A debug tool for Dockerfile based on BuildKit

USAGE:
   buildg [global options] command [command options] [arguments...]

COMMANDS:
   debug    Debug a build
   version  Version info
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --debug     enable debug logs
   --help, -h  show help

buildg debug

$ buildg debug --help
NAME:
   buildg debug - Debug a build

USAGE:
   buildg debug [command options] [arguments...]

OPTIONS:
   --file value, -f value       Name of the Dockerfile
   --target value               Target build stage to build.
   --build-arg value            Build-time variables
   --oci-worker-net value       Worker network type: "auto", "cni", "host" (default: "auto")
   --image value                Image to use for debugging stage
   --oci-cni-config-path value  Path to CNI config file (default: "/etc/buildkit/cni.json")
   --oci-cni-binary-path value  Path to CNI plugin binary dir (default: "/opt/cni/bin")
   --rootless                   Enable rootless configuration

Debug commands

COMMANDS:

break, b BREAKPOINT_SPEC  set a breakpoint
  BREAKPOINT_SPEC
    NUMBER   line number in Dockerfile
    on-fail  step that returns an error
breakpoints, bp           list breakpoints
clear BREAKPOINT_KEY      clear a breakpoint
clearall                  clear all breakpoints
next, n                   proceed to the next line
continue, c               proceed to the next breakpoint
exec, e [OPTIONS] ARG...  execute command in the step
  OPTIONS
    --image          use debugger image
    --mountroot=DIR  mountpoint to mount the rootfs of the step. ignored if --image isn't specified.
    --init           execute commands in an initial state of that step (experimental)
list, ls, l [OPTIONS]     list lines
  OPTIONS
    --all  list all lines in the source file
exit, quit, q             exit the debugging
Issues
  • Add `on-fail` breakpoint

    Add `on-fail` breakpoint

    on-fail breakpoint breaks when a step fails and allows debugging the state. This is enabled by default and disabled by clear on-fail. b on-fail can be used to re-enable this breakpoint.

    opened by ktock 0
  • Fix `clear` to take breakpoint key instead of line number

    Fix `clear` to take breakpoint key instead of line number

    Currently clear takes a line number but this should be fixed to take breakpiont key becaue futural breakpoint can be keyed by non line number (e.g. event name like build failure).

    opened by ktock 0
  • README: Remove install using `go install`

    README: Remove install using `go install`

    It's not possible. We'll work on fix this

    go: github.com/ktock/[email protected] (in github.com/ktock/[email protected]):
    	The go.mod file for the module providing named packages contains one or
    	more replace directives. It must not contain directives that would cause
    	it to be interpreted differently than if it were the main module.
    
    
    opened by ktock 0
Releases(v0.0.2)
Owner
Kohei Tokunaga
Kohei Tokunaga
concurrent, cache-efficient, and Dockerfile-agnostic builder toolkit

BuildKit BuildKit is a toolkit for converting source code to build artifacts in an efficient, expressive and repeatable manner. Key features: Automati

Moby 5.2k May 18, 2022
Get the tags of the images used in a Dockerfile

dockerfile-image-tags List or query images and tags used in a Dockerfile. Usage List all images and tags Pass path to Dockerfile: dockerfile-image-tag

Shiv Jha-Mathur 0 Nov 8, 2021
Deploy https certificates non-interactively to CDN services

certdeploy Deploy https certificates non-interactively to CDN services. Environment Variables CERT_PATH - Certificate file path, should contain certif

三三 1 Nov 12, 2021
Conjur Kubernetes All-in-One Dockerfile

conjur-authn-k8s-aio Conjur Kubernetes All-in-One Dockerfile Supported Authenticators Usage Build Secretless Broker Build Conjur Authn-K8s Client Buil

Joe Garcia 0 Dec 27, 2021
Gh-s - Search github repositories interactively

search github repositories interactively Installation • Usage • Feedback Search

Gennaro Tedesco 183 May 10, 2022
Gh-i - Search your github issues interactively

search your github issues interactively Installation • Usage • Feedback Search G

Gennaro Tedesco 18 May 1, 2022
quick debug program running in the k8s pod

quick-debug English | 中文 What Problem To Solve As the k8s becomes more and more popular, most projects are deployed in k8s, and so is the development

Alan Wang 13 Apr 1, 2022
This script search print debug from PHP code.

go-php-print-debug This script search print debug from PHP code. Checking "print", "print_r", "var_dump", "var_export", "echo" as print debug. Exclude

kota oue 0 Jan 15, 2022
Nycmesh-tool - nycmesh-tool CLI

nycmesh-tool nycmesh-tool CLI Features At the moment, the tool is pretty sparse. It provides the top level nycmesh-tool command, with subcommands for:

Gabe Conradi 1 Feb 10, 2022
Terraform-equinix-migration-tool - Tool to migrate code from Equinix Metal terraform provider to Equinix terraform provider

Equinix Terraform Provider Migration Tool This tool targets a terraform working

Equinix 1 Feb 15, 2022
Blast is a simple tool for API load testing and batch jobs

Blast Blast makes API requests at a fixed rate. The number of concurrent workers is configurable. The rate may be changed interactively during executi

Dave Brophy 204 Mar 8, 2022
Fast cross-platform HTTP benchmarking tool written in Go

bombardier bombardier is a HTTP(S) benchmarking tool. It is written in Go programming language and uses excellent fasthttp instead of Go's default htt

Максим Федосеев 3.5k May 17, 2022
:rocket: Modern cross-platform HTTP load-testing tool written in Go

English | 中文 Cassowary is a modern HTTP/S, intuitive & cross-platform load testing tool built in Go for developers, testers and sysadmins. Cassowary d

Roger Welin 582 May 9, 2022
DepCharge is a tool designed to help orchestrate the execution of commands across many directories at once.

DepCharge DepCharge is a tool that helps orchestrate the execution of commands across the many dependencies and directories in larger projects. It als

Andrew LeTourneau 22 May 9, 2022
Super simple deployment tool

Dropship Dropship is a simple tool for installing and updating artifacts from a CDN. Features Automatically performs md5sum checks of artifact that is

Christopher McKenzie 59 Mar 5, 2022
A dead simple, no frills Go cross compile tool

Gox - Simple Go Cross Compilation Gox is a simple, no-frills tool for Go cross compilation that behaves a lot like standard go build. Gox will paralle

Mitchell Hashimoto 4.2k May 8, 2022
a build tool for Go, with a focus on cross-compiling, packaging and deployment

goxc NOTE: goxc has long been in maintenance mode. Ever since Go1.5 supported simple cross-compilation, this tool lost much of its value. There are st

Am Laher 1.7k Apr 5, 2022
Ostent is a server tool to collect, display and report system metrics.

Ostent Ostent collects metrics to display and report to InfluxDB, Graphite, Librato. The interactive display UI (demo): System metrics collected and r

Ostrost 172 Mar 13, 2022
Packer is a tool for creating identical machine images for multiple platforms from a single source configuration.

Packer Website: https://www.packer.io IRC: #packer-tool on Freenode Mailing list: Google Groups Packer is a tool for building identical machine images

HashiCorp 13.7k May 9, 2022