debug

Documentation

Overview

Package debug 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/k8s-skaffold/skaffold-debug-support/` 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":{"artifact":"node-example","runtime":"nodejs","ports":{"devtools":9229}},
  "adapter":{"artifact":"java-example","runtime":"jvm","ports":{"jdwp":5005}}
}'

Each configuration is itself a JSON object of type `ContainerDebugConfiguration`, with an `artifact` recording the corresponding artifact's `image` in the skaffold.yaml, a `runtime` field identifying the language runtime, the working directory of the remote image (if known), and a set of debugging ports.

Index

• Constants
• func ApplyDebuggingTransforms(l manifest.ManifestList, builds []build.Artifact, ...) (manifest.ManifestList, error)
• type ContainerDebugConfiguration

Constants

const (

	// DebugConfigAnnotation is the name of the podspec annotation that records debugging configuration information.
	// The annotation should be a JSON-encoded map of container-name to a `ContainerDebugConfiguration` object.
	DebugConfigAnnotation = "debug.cloud.google.com/config"

	// DebugProbesAnnotation is the name of the podspec annotation that disables rewriting of probe timeouts.
	// The annotation value should be `skip`.
	DebugProbeTimeoutsAnnotation = "debug.cloud.google.com/probe/timeouts"
)

Functions

func ApplyDebuggingTransforms

func ApplyDebuggingTransforms(l manifest.ManifestList, builds []build.Artifact, registries manifest.Registries) (manifest.ManifestList, error)

ApplyDebuggingTransforms applies language-platform-specific transforms to a list of manifests.

Types

type ContainerDebugConfiguration

type ContainerDebugConfiguration struct {
	// Artifact is the corresponding artifact's image name used in the skaffold.yaml
	Artifact string `json:"artifact,omitempty"`
	// Runtime represents the underlying language runtime (`go`, `jvm`, `nodejs`, `python`, `netcore`)
	Runtime string `json:"runtime,omitempty"`
	// WorkingDir is the working directory in the image configuration; may be empty
	WorkingDir string `json:"workingDir,omitempty"`
	// Ports is the list of debugging ports, keyed by protocol type
	Ports map[string]uint32 `json:"ports,omitempty"`
}

ContainerDebugConfiguration captures debugging information for a specific container. This structure is serialized out and included in the pod metadata.