debug

Documentation

Index

• Constants
• Variables
• func HandleDockerRuntime(logger *log.Entry, xc *app.ExecutionContext, gparams *command.GenericParams, ...)
• func HandleKubernetesRuntime(logger *log.Entry, xc *app.ExecutionContext, gparams *command.GenericParams, ...)
• func OnCommand(xc *app.ExecutionContext, gparams *command.GenericParams, ...)
• func RegisterCommand()
• func ShellCommandPrefix(imageName string) []string
• type CommandParams
• type DebugContainerInfo
• type NVPair
  • func ParseNameValueList(list []string) []NVPair

Constants

const (
	Name  = "debug"
	Usage = "Debug the target container from a debug (side-car) container"
	Alias = "dbg"
)

const (
	DockerRuntime     = "docker"
	KubernetesRuntime = "k8s"
	KubeconfigDefault = "${HOME}/.kube/config"
	NamespaceDefault  = "default"
)

const (
	CgrSlimToolkitDebugImage = "cgr.dev/chainguard/slim-toolkit-debug:latest"
	WolfiBaseImage           = "cgr.dev/chainguard/wolfi-base:latest"
	BusyboxImage             = "busybox:latest"
	NicolakaNetshootImage    = "nicolaka/netshoot"
	KoolkitsNodeImage        = "lightruncom/koolkits:node"
	KoolkitsPythonImage      = "lightruncom/koolkits:python"
	KoolkitsGolangImage      = "lightruncom/koolkits:golang"
	KoolkitsJVMImage         = "lightruncom/koolkits:jvm"
	DigitaloceanDoksImage    = "digitalocean/doks-debug:latest"
	ZinclabsUbuntuImage      = "public.ecr.aws/zinclabs/debug-ubuntu-base:latest"
	InfuserImage             = "ghcr.io/teaxyz/infuser:latest"
)

const (
	FlagRuntime      = "runtime"
	FlagRuntimeUsage = "Runtime environment type"

	FlagTarget      = "target"
	FlagTargetUsage = "Target container (name or ID)"

	FlagNamespace      = "namespace"
	FlagNamespaceUsage = "Namespace to target (k8s runtime)"

	FlagPod      = "pod"
	FlagPodUsage = "Pod to target (k8s runtime)"

	FlagDebugImage      = "debug-image"
	FlagDebugImageUsage = "Debug image to use for the debug side-car container"

	FlagEntrypoint      = "entrypoint"
	FlagEntrypointUsage = "Custom ENTRYPOINT to use for the debug side-car container."

	FlagCmd      = "cmd"
	FlagCmdUsage = "Custom CMD to use for the debug side-car container (alternatively pass custom CMD params after '--')."

	FlagWorkdir      = "workdir"
	FlagWorkdirUsage = "Custom WORKDIR to use for the debug side-car container."

	//value expected to be "name=value"
	FlagEnv      = "env"
	FlagEnvUsage = "Environment variable to add to the debug side-car container."

	//TBD
	FlagMount      = "mount"
	FlagMountUsage = "Volume mount to create in the debug side-car container."

	//TBD
	FlagLoadAllTargetEnvVars      = "load-all-target-env-vars"
	FlagLoadAllTargetEnvVarsUsage = "Load all (known) environment variables from the target container"

	FlagTerminal      = "terminal"
	FlagTerminalUsage = "Attach interactive terminal to the debug container"

	FlagRunAsTargetShell      = "run-as-target-shell"
	FlagRunAsTargetShellUsage = "Attach interactive terminal to the debug container and run shell as if it's running in the target container environment."

	FlagListSessions      = "list-sessions"
	FlagListSessionsUsage = "" /* 128-byte string literal not displayed */

	FlagShowSessionLogs      = "show-session-logs"
	FlagShowSessionLogsUsage = "" /* 173-byte string literal not displayed */

	FlagSession      = "session"
	FlagSessionUsage = "Debug session container name (used for debug sessoin actions)."

	FlagConnectSession      = "connect-session"
	FlagConnectSessionUsage = "Connect to existing debug session."

	//TBD
	FlagConnectLastSession      = "connect-last-session"
	FlagConnectLastSessionUsage = "Connect to last debug session"

	FlagListNamespaces      = "list-namespaces"
	FlagListNamespacesUsage = "List names for available namespaces (use this flag by itself)."

	FlagListPods      = "list-pods"
	FlagListPodsUsage = "List names for running pods in the selected namespace (use this flag by itself)."

	FlagListDebuggableContainers      = "list-debuggable-containers"
	FlagListDebuggableContainersUsage = "List container names for active containers that can be debugged (use this flag by itself)."

	FlagListDebugImage      = "list-debug-images"
	FlagListDebugImageUsage = "List possible debug images to use for the debug side-car container (use this flag by itself)."

	FlagKubeconfig      = "kubeconfig"
	FlagKubeconfigUsage = "Kubeconfig file location (k8s runtime)"
)

Debug command flag names and usage descriptions

const (
	CSWaiting    = "WAITING"
	CSRunning    = "RUNNING"
	CSTerminated = "TERMINATED"
)

Variables

var (
	ErrPodTerminated       = errors.New("Pod terminated")
	ErrPodNotRunning       = errors.New("Pod not running")
	ErrContainerTerminated = errors.New("Container terminated")
)

var CLI = &cli.Command{
	Name:    Name,
	Aliases: []string{Alias},
	Usage:   Usage,
	Flags: []cli.Flag{
		cflag(FlagRuntime),
		cflag(FlagTarget),
		cflag(FlagNamespace),
		cflag(FlagPod),
		cflag(FlagDebugImage),
		cflag(FlagEntrypoint),
		cflag(FlagCmd),
		cflag(FlagWorkdir),
		cflag(FlagEnv),
		cflag(FlagTerminal),
		cflag(FlagRunAsTargetShell),
		cflag(FlagListSessions),
		cflag(FlagShowSessionLogs),
		cflag(FlagConnectSession),
		cflag(FlagSession),
		cflag(FlagListNamespaces),
		cflag(FlagListPods),
		cflag(FlagListDebuggableContainers),
		cflag(FlagListDebugImage),
		cflag(FlagKubeconfig),
	},
	Action: func(ctx *cli.Context) error {
		gcvalues := command.GlobalFlagValues(ctx)
		xc := app.NewExecutionContext(
			Name,
			gcvalues.QuietCLIMode,
			gcvalues.OutputFormat)

		if ctx.Bool(FlagListDebugImage) {
			xc.Out.State("action.list_debug_images")
			for k, v := range debugImages {
				xc.Out.Info("debug.image", ovars{"name": k, "description": v})
			}

			return nil
		}

		commandParams := &CommandParams{
			Runtime:                        ctx.String(FlagRuntime),
			TargetRef:                      ctx.String(FlagTarget),
			TargetNamespace:                ctx.String(FlagNamespace),
			TargetPod:                      ctx.String(FlagPod),
			DebugContainerImage:            ctx.String(FlagDebugImage),
			DoTerminal:                     ctx.Bool(FlagTerminal),
			DoRunAsTargetShell:             ctx.Bool(FlagRunAsTargetShell),
			Kubeconfig:                     ctx.String(FlagKubeconfig),
			Workdir:                        ctx.String(FlagWorkdir),
			EnvVars:                        ParseNameValueList(ctx.StringSlice(FlagEnv)),
			Session:                        ctx.String(FlagSession),
			ActionListNamespaces:           ctx.Bool(FlagListNamespaces),
			ActionListPods:                 ctx.Bool(FlagListPods),
			ActionListDebuggableContainers: ctx.Bool(FlagListDebuggableContainers),
			ActionListSessions:             ctx.Bool(FlagListSessions),
			ActionShowSessionLogs:          ctx.Bool(FlagShowSessionLogs),
			ActionConnectSession:           ctx.Bool(FlagConnectSession),
		}

		if commandParams.Runtime != KubernetesRuntime &&
			(commandParams.ActionListNamespaces ||
				commandParams.ActionListPods) {
			var actionName string
			if commandParams.ActionListNamespaces {
				actionName = FlagListNamespaces
			}

			if commandParams.ActionListPods {
				actionName = FlagListPods
			}

			xc.Out.Error("param", "unsupported runtime flag")
			xc.Out.State("exited",
				ovars{
					"runtime.provided": commandParams.Runtime,
					"runtime.required": KubernetesRuntime,
					"action":           actionName,
					"exit.code":        -1,
				})

			xc.Exit(-1)
		}

		var err error
		if rawEntrypoint := ctx.String(FlagEntrypoint); rawEntrypoint != "" {
			commandParams.Entrypoint, err = command.ParseExec(rawEntrypoint)
			if err != nil {
				return err
			}
		}

		if rawCmd := ctx.String(FlagCmd); rawCmd != "" {
			commandParams.Cmd, err = command.ParseExec(rawCmd)
			if err != nil {
				return err
			}
		}

		if len(commandParams.Entrypoint) > 0 || len(commandParams.Cmd) > 0 {
			commandParams.DoRunAsTargetShell = false
		}

		if commandParams.DoRunAsTargetShell {
			commandParams.DoTerminal = true
		}

		if !commandParams.ActionListNamespaces &&
			!commandParams.ActionListPods &&
			!commandParams.ActionListDebuggableContainers &&
			!commandParams.ActionListSessions &&
			!commandParams.ActionShowSessionLogs &&
			!commandParams.ActionConnectSession &&
			commandParams.TargetRef == "" {
			if ctx.Args().Len() < 1 {
				if commandParams.Runtime != KubernetesRuntime {
					xc.Out.Error("param.target", "missing target")
					cli.ShowCommandHelp(ctx, Name)
					return nil
				}

			} else {
				commandParams.TargetRef = ctx.Args().First()
				if ctx.Args().Len() > 1 && ctx.Args().Slice()[1] == "--" {

					cmdSlice := ctx.Args().Slice()[2:]
					var cmdClean []string
					for _, v := range cmdSlice {
						v = strings.TrimSpace(v)
						if v != "" {
							cmdClean = append(cmdClean, v)
						}
					}
					if len(cmdClean) > 0 {
						commandParams.Cmd = cmdClean
						commandParams.DoTerminal = false
						commandParams.DoRunAsTargetShell = false
					}
				}
			}
		}

		if commandParams.DebugContainerImage == "" {
			commandParams.DebugContainerImage = BusyboxImage
		}

		OnCommand(
			xc,
			gcvalues,
			commandParams)

		return nil
	},
}

var CommandFlagSuggestions = &command.FlagSuggestions{
	Names: []prompt.Suggest{
		{Text: command.FullFlagName(FlagRuntime), Description: FlagRuntimeUsage},
		{Text: command.FullFlagName(FlagTarget), Description: FlagTargetUsage},
		{Text: command.FullFlagName(FlagNamespace), Description: FlagNamespaceUsage},
		{Text: command.FullFlagName(FlagPod), Description: FlagPodUsage},
		{Text: command.FullFlagName(FlagDebugImage), Description: FlagDebugImageUsage},
		{Text: command.FullFlagName(FlagEntrypoint), Description: FlagEntrypointUsage},
		{Text: command.FullFlagName(FlagCmd), Description: FlagCmdUsage},
		{Text: command.FullFlagName(FlagWorkdir), Description: FlagWorkdirUsage},
		{Text: command.FullFlagName(FlagEnv), Description: FlagEnvUsage},
		{Text: command.FullFlagName(FlagTerminal), Description: FlagTerminalUsage},
		{Text: command.FullFlagName(FlagRunAsTargetShell), Description: FlagRunAsTargetShellUsage},
		{Text: command.FullFlagName(FlagListSessions), Description: FlagListSessionsUsage},
		{Text: command.FullFlagName(FlagShowSessionLogs), Description: FlagShowSessionLogsUsage},
		{Text: command.FullFlagName(FlagConnectSession), Description: FlagConnectSessionUsage},
		{Text: command.FullFlagName(FlagSession), Description: FlagSessionUsage},
		{Text: command.FullFlagName(FlagListNamespaces), Description: FlagListNamespacesUsage},
		{Text: command.FullFlagName(FlagListPods), Description: FlagListPodsUsage},
		{Text: command.FullFlagName(FlagListDebuggableContainers), Description: FlagListDebuggableContainersUsage},
		{Text: command.FullFlagName(FlagListDebugImage), Description: FlagListDebugImageUsage},
		{Text: command.FullFlagName(FlagKubeconfig), Description: FlagKubeconfigUsage},
	},
	Values: map[string]command.CompleteValue{
		command.FullFlagName(FlagRuntime):                  completeRuntime,
		command.FullFlagName(FlagTarget):                   completeTarget,
		command.FullFlagName(FlagDebugImage):               completeDebugImage,
		command.FullFlagName(FlagTerminal):                 command.CompleteTBool,
		command.FullFlagName(FlagRunAsTargetShell):         command.CompleteTBool,
		command.FullFlagName(FlagListSessions):             command.CompleteBool,
		command.FullFlagName(FlagShowSessionLogs):          command.CompleteBool,
		command.FullFlagName(FlagConnectSession):           command.CompleteBool,
		command.FullFlagName(FlagSession):                  completeSession,
		command.FullFlagName(FlagListNamespaces):           command.CompleteBool,
		command.FullFlagName(FlagListPods):                 command.CompleteBool,
		command.FullFlagName(FlagListDebuggableContainers): command.CompleteBool,
		command.FullFlagName(FlagListDebugImage):           command.CompleteBool,
		command.FullFlagName(FlagNamespace):                completeNamespace,
		command.FullFlagName(FlagPod):                      completePod,
	},
}

var CommandSuggestion = prompt.Suggest{
	Text:        Name,
	Description: Usage,
}

var Flags = map[string]cli.Flag{
	FlagRuntime: &cli.StringFlag{
		Name:    FlagRuntime,
		Value:   DockerRuntime,
		Usage:   FlagRuntimeUsage,
		EnvVars: []string{"DSLIM_DBG_RT"},
	},
	FlagTarget: &cli.StringFlag{
		Name:    FlagTarget,
		Value:   "",
		Usage:   FlagTargetUsage,
		EnvVars: []string{"DSLIM_DBG_TARGET"},
	},
	FlagNamespace: &cli.StringFlag{
		Name:    FlagNamespace,
		Value:   NamespaceDefault,
		Usage:   FlagNamespaceUsage,
		EnvVars: []string{"DSLIM_DBG_TARGET_NS"},
	},
	FlagPod: &cli.StringFlag{
		Name:    FlagPod,
		Value:   "",
		Usage:   FlagPodUsage,
		EnvVars: []string{"DSLIM_DBG_TARGET_POD"},
	},
	FlagDebugImage: &cli.StringFlag{
		Name:    FlagDebugImage,
		Value:   BusyboxImage,
		Usage:   FlagDebugImageUsage,
		EnvVars: []string{"DSLIM_DBG_IMAGE"},
	},
	FlagEntrypoint: &cli.StringFlag{
		Name:    FlagEntrypoint,
		Value:   "",
		Usage:   FlagEntrypointUsage,
		EnvVars: []string{"DSLIM_DBG_ENTRYPOINT"},
	},
	FlagCmd: &cli.StringFlag{
		Name:    FlagCmd,
		Value:   "",
		Usage:   FlagCmdUsage,
		EnvVars: []string{"DSLIM_DBG_CMD"},
	},
	FlagWorkdir: &cli.StringFlag{
		Name:    FlagWorkdir,
		Value:   "",
		Usage:   FlagWorkdirUsage,
		EnvVars: []string{"DSLIM_DBG_WDIR"},
	},
	FlagEnv: &cli.StringSliceFlag{
		Name:    FlagEnv,
		Value:   cli.NewStringSlice(),
		Usage:   FlagEnvUsage,
		EnvVars: []string{"DSLIM_DBG_ENV"},
	},
	FlagTerminal: &cli.BoolFlag{
		Name:    FlagTerminal,
		Value:   true,
		Usage:   FlagTerminalUsage,
		EnvVars: []string{"DSLIM_DBG_TERMINAL"},
	},
	FlagRunAsTargetShell: &cli.BoolFlag{
		Name:    FlagRunAsTargetShell,
		Value:   true,
		Usage:   FlagRunAsTargetShellUsage,
		EnvVars: []string{"DSLIM_DBG_RATS"},
	},
	FlagListSessions: &cli.BoolFlag{
		Name:    FlagListSessions,
		Value:   false,
		Usage:   FlagListSessionsUsage,
		EnvVars: []string{"DSLIM_DBG_LIST_SESSIONS"},
	},
	FlagShowSessionLogs: &cli.BoolFlag{
		Name:    FlagShowSessionLogs,
		Value:   false,
		Usage:   FlagShowSessionLogsUsage,
		EnvVars: []string{"DSLIM_DBG_SHOW_SESSION_LOGS"},
	},
	FlagConnectSession: &cli.BoolFlag{
		Name:    FlagConnectSession,
		Value:   false,
		Usage:   FlagConnectSessionUsage,
		EnvVars: []string{"DSLIM_DBG_CONNECT_SESSION"},
	},
	FlagSession: &cli.StringFlag{
		Name:    FlagSession,
		Value:   "",
		Usage:   FlagSessionUsage,
		EnvVars: []string{"DSLIM_DBG_SESSION"},
	},
	FlagListNamespaces: &cli.BoolFlag{
		Name:    FlagListNamespaces,
		Value:   false,
		Usage:   FlagListNamespacesUsage,
		EnvVars: []string{"DSLIM_DBG_LIST_NAMESPACES"},
	},
	FlagListPods: &cli.BoolFlag{
		Name:    FlagListPods,
		Value:   false,
		Usage:   FlagListPodsUsage,
		EnvVars: []string{"DSLIM_DBG_LIST_PODS"},
	},
	FlagListDebuggableContainers: &cli.BoolFlag{
		Name:    FlagListDebuggableContainers,
		Value:   false,
		Usage:   FlagListDebuggableContainersUsage,
		EnvVars: []string{"DSLIM_DBG_LIST_CONTAINERS"},
	},
	FlagListDebugImage: &cli.BoolFlag{
		Name:    FlagListDebugImage,
		Value:   false,
		Usage:   FlagListDebugImageUsage,
		EnvVars: []string{"DSLIM_DBG_LIST_IMAGES"},
	},
	FlagKubeconfig: &cli.StringFlag{
		Name:    FlagKubeconfig,
		Value:   KubeconfigDefault,
		Usage:   FlagKubeconfigUsage,
		EnvVars: []string{"DSLIM_DBG_KUBECONFIG"},
	},
}

Functions

func HandleDockerRuntime

func HandleDockerRuntime(
	logger *log.Entry,
	xc *app.ExecutionContext,
	gparams *command.GenericParams,
	commandParams *CommandParams,
	client *dockerapi.Client,
	sid string,
	debugContainerName string)

HandleDockerRuntime implements support for the docker runtime

func HandleKubernetesRuntime

func HandleKubernetesRuntime(
	logger *log.Entry,
	xc *app.ExecutionContext,
	gparams *command.GenericParams,
	commandParams *CommandParams,
	sid string,
	debugContainerName string)

HandleKubernetesRuntime implements support for the k8s runtime

func OnCommand

func OnCommand(
	xc *app.ExecutionContext,
	gparams *command.GenericParams,
	commandParams *CommandParams)

OnCommand implements the 'debug' command

func RegisterCommand

func RegisterCommand()

func ShellCommandPrefix

func ShellCommandPrefix(imageName string) []string

Types

type CommandParams

type CommandParams struct {
	/// the runtime environment type
	Runtime string
	/// the running container which we want to attach to
	TargetRef string
	/// the target namespace (k8s runtime)
	TargetNamespace string
	/// the target pod (k8s runtime)
	TargetPod string
	/// the name/id of the container image used for debugging
	DebugContainerImage string
	/// ENTRYPOINT used launching the debugging container
	Entrypoint []string
	/// CMD used launching the debugging container
	Cmd []string
	/// WORKDIR used launching the debugging container
	Workdir string
	/// Environment variables used launching the debugging container
	EnvVars []NVPair
	/// launch the debug container with an interactive terminal attached (like '--it' in docker)
	DoTerminal bool
	/// make it look like shell is running in the target container
	DoRunAsTargetShell bool
	/// Kubeconfig file path (k8s runtime)
	Kubeconfig string
	/// Debug session container name
	Session string
	/// Simple (non-debug) action - list namespaces
	ActionListNamespaces bool
	/// Simple (non-debug) action - list pods
	ActionListPods bool
	/// Simple (non-debug) action - list debuggable container
	ActionListDebuggableContainers bool
	/// Simple (non-debug) action - list debug sessions
	ActionListSessions bool
	/// Simple (non-debug) action - show debug sessions logs
	ActionShowSessionLogs bool
	/// Simple (non-debug) action - connect to an existing debug session
	ActionConnectSession bool
}

type DebugContainerInfo

type DebugContainerInfo struct {
	TargetContainerName string
	Name                string
	SpecImage           string
	Command             []string
	Args                []string
	WorkingDir          string
	TTY                 bool
	ContainerID         string
	RunningImage        string
	RunningImageID      string
	StartTime           string
	FinishTime          string
	State               string
	ExitCode            int32
	ExitReason          string
	ExitMessage         string
	WaitReason          string
	WaitMessage         string
}

type NVPair

type NVPair struct {
	Name  string
	Value string
}

func ParseNameValueList

func ParseNameValueList(list []string) []NVPair