aylei/kubectl-debug
Kubectl Debug
Kubectl-debug is a diagnostic utility for Kubernetes that enables deep inspection of running containerized applications. It functions by dynamically injecting ephemeral sidecar containers into existing pods, allowing users to troubleshoot processes and filesystems without modifying original production images. The tool manages the lifecycle of these diagnostic agents, ensuring they are created on demand and cleaned up automatically after an investigation session concludes.
The project distinguishes itself by enabling shared namespace access, which allows diagnostic tools to join the process and network namespaces of a target container. It supports advanced troubleshooting workflows, including the ability to fork pods to reproduce crashes in isolation, inspect initialization containers, and mount target filesystems for log or configuration analysis. Secure network connectivity is maintained through local-to-remote port tunneling and network bridging, ensuring access to isolated services within restricted environments.
The tool incorporates security and governance features to maintain production integrity during maintenance. It enforces strict image restrictions, supports authentication with private registries, and provides command auditing to record all actions performed during a session. These capabilities ensure that troubleshooting remains compliant with organizational security policies while providing the necessary visibility into cluster-level issues.
Features
- Kubernetes Ephemeral Debuggers - Provides a diagnostic utility that dynamically injects ephemeral sidecar containers into existing Kubernetes pods for deep inspection and troubleshooting.
- Container Troubleshooting - Injects temporary diagnostic tools into running pods to inspect application state and logs without modifying production images.
- Kubernetes Diagnostic Interfaces - Provides a diagnostic interface for deep inspection of containerized applications by mounting target filesystems and auditing execution commands.
- Ephemeral Sidecar Injections - Injects temporary diagnostic containers into existing pods by dynamically modifying the pod specification to share namespaces.
- Pod Troubleshooting - Enables deep inspection of running containerized applications by injecting diagnostic tools directly into pods to troubleshoot processes and filesystems.
- Ephemeral Diagnostics - Automates the lifecycle of diagnostic containers to ensure they are cleaned up after investigation sessions.
- Diagnostic Image Restrictions - Enforces strict image restrictions to ensure that only authorized diagnostic tools are executed within production environments.
- Dev Container Attachments - Injects temporary containers into running processes to provide immediate access to troubleshooting tools.
- API-Driven Pod Mutations - Provides automated pod patching via control plane operations to inject diagnostic sidecars without manual redeployment.
- Production Debugging Environments - Safely reproduces and analyzes application crashes by creating isolated copies of pods to troubleshoot failures.
- Namespace-Based Resource Sharings - Enables diagnostic tools to access target container filesystems and process trees by joining existing namespaces.
- Local Port Forwarding - Establishes connections to target nodes through local port forwarding for remote diagnostic sessions.
- Local-to-Remote Port Tunnels - Establishes secure network bridges between local diagnostic clients and isolated cluster services.
- Filesystem Mounting - Mounts the root filesystem of a target container into a diagnostic environment for log and configuration analysis.
- Pod Forking Mechanisms - Creates isolated copies of crashing processes to safely reproduce and debug failures without affecting production traffic.
- Kubernetes Policy Enforcers - Enforces security policies by limiting allowed diagnostic images and auditing commands to maintain compliance during cluster maintenance.
- Diagnostic Image Governance - Enforces strict image restrictions and registry authentication to ensure only authorized diagnostic tools are executed.
- Diagnostic Command Auditing - Logs all commands executed within diagnostic sessions to ensure compliance and maintain production integrity.
- Init Container Debugging Tools - Targets specific initialization containers to diagnose startup failures before the main application process begins.
- CLI Command Auditing - Logs all commands executed within diagnostic containers to provide a secure audit trail of troubleshooting actions.
- Cluster Diagnostics - Investigates startup failures and configuration issues by attaching ephemeral containers to specific init containers or isolated processes.
