kubectl-debug
by aylei
kubectl-debug enables seamless debugging of running Kubernetes pods by injecting a new container sharing namespaces with the target pod without modifying the original container image.
This repository is no longer maintained, please checkout https://github.com/JamesTGrant/kubectl-debug.
Primary Use Case
This tool is primarily used by Kubernetes administrators and developers to troubleshoot and debug live pods in a cluster without needing to pre-install debugging tools inside the production containers. It facilitates incident response and security automation by allowing quick access to pod internals using a separate debug container.
- Runs a new container inside running pods for debugging purposes
- Shares pid, network, user, and ipc namespaces with the target container
- Supports agentless mode by creating debug agent pods on demand
- Optional installation of a debug agent DaemonSet for faster startup
- Compatible with kubectl 1.12.0 or higher
- Supports multiple OS binaries including Linux, macOS, and Windows
- No need to pre-install debugging tools inside production containers
Installation
- Install via Homebrew: brew install aylei/tap/kubectl-debug
- Download binary for Linux x86_64: curl -Lo kubectl-debug.tar.gz https://github.com/aylei/kubectl-debug/releases/download/v0.1.1/kubectl-debug_0.1.1_linux_amd64.tar.gz
- Download binary for macOS: curl -Lo kubectl-debug.tar.gz https://github.com/aylei/kubectl-debug/releases/download/v0.1.1/kubectl-debug_0.1.1_darwin_amd64.tar.gz
- Extract the binary: tar -zxvf kubectl-debug.tar.gz kubectl-debug
- Move binary to system path: sudo mv kubectl-debug /usr/local/bin/
- For Windows, download the latest release archive, decompress and add kubectl-debug to PATH
- Optionally install debug agent DaemonSet for faster debug sessions: kubectl apply -f https://raw.githubusercontent.com/aylei/kubectl-debug/master/scripts/agent_daemonset.yml
- For Kubernetes versions <1.16, modify apiVersion in agent_daemonset.yml before applying
- Alternatively, install via Helm: helm install kubectl-debug -n=debug-agent ./contrib/helm/kubectl-debug
Usage
>_ kubectl debug -hDisplays help information and usage instructions for kubectl-debug
>_ kubectl debug --agentless=false POD_NAMEStarts a debug session using the pre-installed debug agent DaemonSet for faster startup
- Integrate kubectl-debug into automated incident response playbooks to enable rapid live debugging of compromised containers without service disruption.
- Use in purple team exercises to simulate attacker lateral movement and container compromise scenarios, improving detection and response capabilities.
- Leverage agentless mode to minimize footprint and reduce risk of persistent artifacts in production environments during forensic investigations.
- Combine with container security monitoring tools to provide contextual live debugging data for alerts triggered by anomalous container behavior.
- Adopt as a DevSecOps tool to empower developers and security teams to collaboratively troubleshoot and remediate container security incidents in real-time.
Docs Take 2 Hours. AI Takes 10 Seconds.
Ask anything about kubectl-debug. Installation? Config? Troubleshooting? Get answers trained on real docs and GitHub issues—not generic ChatGPT fluff.
3 free chats per tool • Instant responses • No credit card
Related Tools
portainer
portainer/portainer
Making Docker and Kubernetes management easy.
slim
slimtoolkit/slim
Slim(toolkit): Don't change anything in your container image and minify it by up to 30x (and for compiled languages even more) making it secure too! (free and open source)
kubescape
kubescape/kubescape
Kubescape is an open-source Kubernetes security platform for your IDE, CI/CD pipelines, and clusters. It includes risk analysis, security, compliance, and misconfiguration scanning, saving Kubernetes users and administrators precious time, effort, and resources.
kube-bench
aquasecurity/kube-bench
Checks whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark
kubernetes-learning-path
techiescamp/kubernetes-learning-path
A roadmap to learn Kubernetes from scratch (Beginner to Advanced level)
kata-containers
kata-containers/kata-containers
Kata Containers is an open source project and community working to build a standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs. https://katacontainers.io/