Make debugging distroless OCI containers a lot less painful
Find a file
2026-09-28 17:19:07 +07:00
cmd Add all project files 2026-09-28 17:19:07 +07:00
pkg Add all project files 2026-09-28 17:19:07 +07:00
.gitignore Add all project files 2026-09-28 17:19:07 +07:00
go.mod Add all project files 2026-09-28 17:19:07 +07:00
go.sum Add all project files 2026-09-28 17:19:07 +07:00
LICENSE Add all project files 2026-09-28 17:19:07 +07:00
main.go Add all project files 2026-09-28 17:19:07 +07:00
README.md Add all project files 2026-09-28 17:19:07 +07:00

debugless

A CLI tool to make debugging distroless OCI containers a lot less painful

Install

Note: You need to have the Golang toolstack installed.

First compile the binary:

GOOS=linux GOARCH=amd64 go build -o debugless .

Then execute normally:

./debugless --help

Or compile it just to a temp binary and run it:

go run . --help

Usage

Debug containers by attaching layer(s) of debug tools to their OCI image or
by attaching debug tools to their running state via an ephemeral container.

Usage:
  debugless [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  inject      Pull a source image and inject a filesystem layer
  sideload    Side load a debugging container to a running container

Flags:
  -h, --help   help for debugless

inject subcommand

inject receives a source image either from registry, docker daemon or local tar archive (oci or docker). Set one of the following source refs:

  docker-daemon:<ref>     read from the local Docker daemon
  archive:<path>          auto-detect OCI layout or Docker tarball on disk
  docker://<ref>          pull from a remote registry (explicit)
  <anything else>         treated as a remote registry image (implicit docker://)

Then injects a custom filesystem layer onto it, and pushes the result to --output. Output can be local archive or registry. Set one of the following output refs:

  archive:/path/to/out.tar   write to a local tar archive. Format (OCI / Docker) is inferred from the image's layer media type.
  docker://<ref>             push to a remote registry (explicit)
  <ref>                      push to a remote registry (implicit)

Usage:
  debugless inject <source-image> [flags]

Flags:
  -h, --help             help for inject
  -o, --output string    destination image reference (e.g. ttl.sh/myimage:latest)
  -p, --profile string   which profile to use to append as debugging layer (e.g. 'busybox') (default "busybox")
      --version string   which version of the used profile should be used (e.g. '1.36.1' for 'busybox' profile)

sideload subcommand

Side load a debugging container to a running container. Set one of the following target refs:

  docker://<container-name-or-id>     target container name or id for local Docker daemon
  k8s://<pod-name>                    target Kubernetes pod. If no container is specified, use default. If no namespace is specified, use default.

Usage:
  debugless sideload [target] [flags]

Flags:
  -A, --all-namespaces                 If present, list the requested object(s) across all namespaces.
  -c, --container string               Container name. If omitted, the first container in the pod will be chosen.
  -u, --container-user string          Run the debugger container as User (format: <name|uid>[:<group|gid>]). If omitted, use root user by default if 'use-target-user' or 'use-debug-user' are not set. (default "0:0")
  -h, --help                           help for sideload
      --image string                   The image used for the debug container. Make sure the docker daemon or the kubelet is able to resolve the provided image. (default "docker.io/library/busybox:musl")
      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.
  -n, --namespace string               If present, the namespace scope for this CLI request
      --no-set-caps                    If present, doesn't set capabilities 'CAP_SYS_CHROOT' and 'CAP_SYS_PTRACE' on debug container if resolved user is root.
  -d, --use-debug-user                 If present, use the standard user of the debug container. If this is a nonroot user, reading target rootfs might not be possible, due to a bug. See KEP-2763.
  -t, --use-target-user                If present, use the user of the target container as user in debug container. If this is a nonroot user, disables setting capabilities and doing chroot, due to a bug. See KEP-2763. But reading target rootfs is still possible.

TODO's

  • configurable Log levels via CLI
  • custom debug images for inject command