How iximiuz/cdebug works
This project is a command‐line tool written in Go called “cdebug” whose primary purpose is to serve as a “swiss army knife” for container debugging. It provides commands like exec and port-forward to allow users to troubleshoot and interact with containers (or even Kubernetes pods) using various container runtimes (Docker, containerd, Kubernetes, and even nerdctl). The tool’s functionality is implemented through a combination of command subdirectories, dedicated packages for interfacing with container runtimes, and integration/E2E tests.
Main components
• CLI Entry Point & Command Dispatcher
• The project uses a main Go file (main.go) and the “cmd” directory which contains subcommands like “exec” and “portforward”. These represent the core entry points where user commands are parsed and dispatched.
• Core Business Logic Layer
• This layer is composed of helper packages and utility libraries located in “pkg”. Subdirectories like “pkg/cliutil”, “pkg/containerd”, “pkg/docker”, “pkg/kubernetes”, “pkg/jsonutil”, “pkg/tty”, “pkg/signalutil”, and “pkg/uuid” encapsulate functionality for managing container interactions, JSON handling, signal processing, and terminal management.
• Container Runtime Abstractions
• Specific adapter packages (e.g., pkg/docker, pkg/containerd, pkg/kubernetes) abstract the details of interacting with different container platforms. These components are key in translating the “exec” and “port-forward” commands into appropriate API calls and runtime actions.
• CI/CD Integration & Testing Infrastructure
• The “.github” and “ci” directories indicate automated workflows for testing and release (using GoReleaser, workflows, and dependabot) as well as integration tests (notably the “e2e” folder which contains end-to-end tests for exec and port-forward functionality).
Relationships and interactions between components
• The CLI layer (cmd/) takes user input and then calls into the core business logic.
• The core logic, by coordinating with the runtime adapters in pkg/docker, pkg/containerd, and pkg/kubernetes, interacts with container engines or Kubernetes clusters.
• When handling an “exec” command, the CLI delegates to the corresponding routine that picks the appropriate adapter and prepares the “debugger sidecar” container, setting up symlinks and chroot’s based on the target container’s root filesystem.
• For port forwarding, the system spawns a forwarding container (using a socat-based mechanism as per the README) that handles traffic routing.
Architectural patterns or design principles
• Modularity: Each container runtime adapter is isolated in its own package.
• Separation of Concerns: The command parsing, business logic, and direct container API interactions are clearly separated.
• Extensibility: The architecture supports future expansions (e.g., adding more container platforms or features like remote port forwarding).
Relevant technologies and frameworks
• Go programming language – for compiling into a statically linked binary.
• CI tools – GitHub Actions defined in .github/workflows and release tools like GoReleaser (.goreleaser.yaml).
• Container runtimes such as Docker, containerd, and Kubernetes.
• Supporting libraries for JSON manipulation and terminal handling.
Detail and succinctness
• Be as detailed as possible by mapping out every module along with its interactions.