Quick-Debug: Fast In-Cluster Debugging for Kubernetes Applications

quick-debug project details: https://github.com/chinaran/quick-debug

What Problem Does It Solve

As Kubernetes becomes increasingly popular, most projects are deployed in k8s, including development environments. Traditional debugging requires rebuilding Docker images, committing code, running CI/CD pipelines, and redeploying, which is time‑consuming.

Quick‑debug offers an "instant" debugging experience similar to front‑end local debugging, allowing developers to modify code locally, compile, and see results in the remote cluster quickly.

Use Cases

Local development environment cannot be set up or is not realistic.

Quick debugging via log printing.

Experimenting with unfamiliar libraries.

Rapidly understanding program behavior.

Develop‑debug‑self‑test workflow.

Principle

The container image used for development must contain the quick-debug executable; the actual service is started by quick‑debug.

After locally compiling the program (e.g., adding debug logs), upload it to the target pod through an exposed NodePort, restart the service, and achieve fast debugging.

Effect Before and After

Before

Code change → git commit → CI/CD builds image → replace remote k8s container image → view logs with kubectl or platform.

After

Modify code locally, compile, run program in remote k8s, and view logs on the local machine directly.

Steps

Example based on go-httpbin ; see example at https://github.com/chinaran/quick-debug/tree/main/example.

Note: The local machine must have network access to the development k8s cluster; the tool is intended for development environments only.

0. Install quick-debug and quick-debug-client

git clone https://github.com/chinaran/quick-debug.git $GOPATH/src/github.com/chinaran/quick-debug/
cd $GOPATH/src/github.com/chinaran/quick-debug/
make install

1. Ensure Docker image contains /usr/local/bin/quick-debug

Copy the compiled binary into the image during build.

Use base image ghcr.io/chinaran/quick-debug:0.2-alpine3.13 .

Refer to example Dockerfile at https://github.com/chinaran/quick-debug/blob/main/example/program-with-quick-debug.Dockerfile and copy quick-debug into the image.

2. Update Deployment command and args

command:
          - quick-debug
          - --exec-path=/bin/go-httpbin # your exec path in docker
          - exec-args
        args: # original args
          - -port
          - "80"
          - -response-delay
          - 10ms

Resulting command for the go‑httpbin pod:

quick-debug --exec-path=/bin/go-httpbin exec-args -port 80 -response-delay 10ms

Original command before modification:

/bin/go-httpbin -port 80 -response-delay 10ms

3. Deploy a NodePort Service (default port 60006)

The nodePort should be fixed (random is also acceptable).

kubectl apply -f - <

4. Compile binary locally and use quick-debug-client to upload and view logs

# Compile executable
CGO_ENABLED=0 GOOS=linux go build -o /tmp/go-httpbin ./cmd/go-httpbin
# Optional UPX compression
upx -1 /tmp/go-httpbin
# Upload to remote k8s pod
quick-debug-client upload --addr {your-node-ip}:{your-node-port} --file {your-program-path}
# Tail logs from remote pod
quick-debug-client taillog --addr {your-node-ip}:{your-node-port}

Golang users can use the shell function at https://github.com/chinaran/quick-debug/blob/main/shell-func-golang.sh for quick execution; other languages can adapt the script similarly.

Join the Cloud‑Native Community: Add the assistant on WeChat (alaudacloudnative, note: 云原生) to access 20+ technical groups.