Make debugging distroless OCI containers a lot less painful
- Go 100%
| cmd | ||
| pkg | ||
| .gitignore | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| main.go | ||
| README.md | ||
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
injectcommand