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 `types.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
• Variables
• func EncodeConfigurations(configurations map[string]types.ContainerDebugConfiguration) string
• func NewDlvTransformer() containerTransformer
• func NewJDWPTransformer() containerTransformer
• func NewNetcoreTransformer() containerTransformer
• func NewNodeTransformer() containerTransformer
• func NewPythonTransformer() containerTransformer
• func RegisterContainerTransformer(t containerTransformer)
• func TransformContainer(adapter types.ContainerAdapter, config ImageConfiguration, ...) (types.ContainerDebugConfiguration, string, error)
• func UnregisterContainerTransformer(t containerTransformer)
• type Config
• type ConfigurationRetriever
• type Debugger
• type DebuggerMux
  • func (d DebuggerMux) Name() string
  • func (d DebuggerMux) Start(ctx context.Context) error
  • func (d DebuggerMux) Stop()
• type ImageConfiguration
  • func RetrieveImageConfiguration(ctx context.Context, artifact *graph.Artifact, ...) (ImageConfiguration, error)
• type NoopDebugger
  • func (n *NoopDebugger) Name() string
  • func (n *NoopDebugger) Start(context.Context) error
  • func (n *NoopDebugger) Stop()
• type PortAllocator

Constants

const (
	// DebuggingSupportVolume is the name of the volume used to hold language runtime debugging support files.
	DebuggingSupportFilesVolume = "debugging-support-files"
)

Variables

var ConfigRetriever = func(ctx context.Context, image string, builds []graph.Artifact, registries map[string]bool) (ImageConfiguration, error) {
	if artifact := findArtifact(image, builds); artifact != nil {
		return RetrieveImageConfiguration(ctx, artifact, registries)
	}
	return ImageConfiguration{}, fmt.Errorf("no build artifact for %q", image)
}

var Protocols = []string{}

Functions

func EncodeConfigurations

func EncodeConfigurations(configurations map[string]types.ContainerDebugConfiguration) string

func NewDlvTransformer

func NewDlvTransformer() containerTransformer

func NewJDWPTransformer

func NewJDWPTransformer() containerTransformer

func NewNetcoreTransformer

func NewNetcoreTransformer() containerTransformer

func NewNodeTransformer

func NewNodeTransformer() containerTransformer

func NewPythonTransformer

func NewPythonTransformer() containerTransformer

func RegisterContainerTransformer

func RegisterContainerTransformer(t containerTransformer)

RegisterContainerTransformer allows calling packages to register their own transformer implementation with the global transform list.

func TransformContainer

func TransformContainer(adapter types.ContainerAdapter, config ImageConfiguration, portAlloc PortAllocator) (types.ContainerDebugConfiguration, string, error)

TransformContainer rewrites the container definition to enable debugging. Returns a debugging configuration description with associated language runtime support container image, or an error if the rewrite was unsuccessful.

func UnregisterContainerTransformer

func UnregisterContainerTransformer(t containerTransformer)

UnregisterContainerTransformer removes the provided transformer from the global transformer set.

Types

type Config

type Config interface {
	Mode() config.RunMode
}

type ConfigurationRetriever

type ConfigurationRetriever func(string) (ImageConfiguration, error)

configurationRetriever retrieves an container image configuration

type Debugger

type Debugger interface {
	// Start starts the debugger.
	Start(context.Context) error

	// Stop stops the debugger.
	Stop()

	// Name returns an identifier string for the debugger.
	Name() string
}

Debugger defines the behavior for any implementation of a component that attaches to and helps debug deployed resources from Skaffold.

type DebuggerMux

type DebuggerMux []Debugger

func (DebuggerMux) Name

func (d DebuggerMux) Name() string

func (DebuggerMux) Start

func (d DebuggerMux) Start(ctx context.Context) error

func (DebuggerMux) Stop

func (d DebuggerMux) Stop()

type ImageConfiguration

type ImageConfiguration struct {
	// Artifact is the corresponding Artifact's image name (`pkg/skaffold/build.Artifact.ImageName`)
	Artifact    string
	RuntimeType types.Runtime
	Author      string
	Labels      map[string]string
	Env         map[string]string
	Entrypoint  []string
	Arguments   []string
	WorkingDir  string
}

ImageConfiguration captures information from a docker/oci image configuration. It also includes a "artifact", usually containing the corresponding artifact's' image name from `skaffold.yaml`.

func RetrieveImageConfiguration

func RetrieveImageConfiguration(ctx context.Context, artifact *graph.Artifact, insecureRegistries map[string]bool) (ImageConfiguration, error)

RetrieveImageConfiguration retrieves the image container configuration for the given build artifact

type NoopDebugger

type NoopDebugger struct{}

func (*NoopDebugger) Name

func (n *NoopDebugger) Name() string

func (*NoopDebugger) Start

func (n *NoopDebugger) Start(context.Context) error

func (*NoopDebugger) Stop

func (n *NoopDebugger) Stop()

type PortAllocator

type PortAllocator func(int32) int32

PortAllocator is a function that takes a desired port and returns an available port Ports are normally uint16 but Kubernetes types.ContainerPort is an integer