debug

Overview ¶

The `debug` package transforms Kubernetes pod-bearing resources so as to configure containers for remote debugging as suited for a container's runtime technology. This package defines a _container transformer_ interface. Each transformer implementation should do the following:

1. The transformer should modify the container's entrypoint, command arguments, and environment to enable debugging for the appropriate language runtime. 2. The transformer should expose the port(s) required to connect remote debuggers. 3. The transformer should identify any additional support files required to enable debugging (e.g., the `ptvsd` debugger for Python). 4. The transform should return metadata to describe the remote connection information.

Certain language runtimes require additional support files to enable remote debugging. These support files are provided through a set of support images defined at `gcr.io/gcp-dev-tools/duct-tape/` and defined at https://github.com/GoogleContainerTools/container-debug-support. The appropriate image ID is returned by the language transformer. These support images are configured as initContainers on the pod and are expected to copy the debugging support files into a support volume mounted at `/dbg`. The expected convention is that each runtime's files are placed in `/dbg/<runtimeId>`. This same volume is then mounted into the actual containers at `/dbg`.

As Kubernetes container objects don't actually carry metadata, we place this metadata on the container's parent as an _annotation_; as a pod/podspec can have multiple containers, each of which may be debuggable, we record this metadata using as a JSON object keyed by the container name. Kubernetes requires that containers within a podspec are uniquely named. For example, a pod with two containers named `microservice` and `adapter` may be:

debug.cloud.google.com/config: '{
  "microservice":{"devtools":9229,"runtime":"nodejs"},
  "adapter":{"jdwp":5005,"runtime":"jvm"}
}'

Each configuration is itself a JSON object with a `runtime` field identifying the language runtime, and a set of runtime-specific fields describing connection information.