Skip to content

Docs: turnkey Kubernetes debugging recipe (example manifests + attach presets) #424

Description

@debugmcpdev

Motivation

The capability has shipped: the Docker image debugs seven languages, attach modes work without local toolchains, and ephemeral-container sidecar debugging on Kubernetes is verified (kubectl debug --profile=general injecting SYS_PTRACE, attaching to PID 1, resolving symbols through /proc/1/root, rdbg attach over kubectl port-forward). What's missing is the copy-paste path from "my pod is misbehaving" to "agent is stepping through it".

Deliverables

  1. docs/kubernetes.md — a walkthrough against a sample Deployment:
    • ephemeral sidecar attach: the kubectl debug flags that matter (--profile=general, -- entrypoint replacement), why SYS_PTRACE and a shared PID namespace are needed
    • remote attach via port mapping / kubectl port-forward (the rdbg pattern, generalized to other attach-capable adapters)
    • symbol resolution notes (/proc/<pid>/root), ptrace_scope, distroless-image caveats
  2. Example manifests (or a minimal Helm chart) under examples/kubernetes/: target app + sidecar spec + the MCP client configuration to reach the debugger.
  3. Preset attach configs per attach-capable language, so agents don't have to derive them each time.

Existing material to build on: docs/docker-support.md, docs/ruby/README.md (remote attach), and the container e2e suite.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions