Add debugging support for Skaffold: skaffold debug

cmd/skaffold/app/cmd/cmd.go

@@ -84,6 +84,7 @@ func NewSkaffoldCommand(out, err io.Writer) *cobra.Command {
 	rootCmd.AddCommand(NewCmdVersion(out))
 	rootCmd.AddCommand(NewCmdRun(out))
 	rootCmd.AddCommand(NewCmdDev(out))
+	rootCmd.AddCommand(NewCmdDebug(out))
 	rootCmd.AddCommand(NewCmdBuild(out))
 	rootCmd.AddCommand(NewCmdDeploy(out))
 	rootCmd.AddCommand(NewCmdDelete(out))
@@ -158,6 +159,14 @@ func AddRunDevFlags(cmd *cobra.Command) {
 	cmd.Flags().StringVarP(&opts.CacheFile, "cache-file", "", "", "Specify the location of the cache file (default $HOME/.skaffold/cache)")
 }
 
+func AddDevDebugFlags(cmd *cobra.Command) {
+	cmd.Flags().BoolVar(&opts.TailDev, "tail", true, "Stream logs from deployed objects")
+	cmd.Flags().BoolVar(&opts.Cleanup, "cleanup", true, "Delete deployments after dev mode is interrupted")
+	cmd.Flags().BoolVar(&opts.PortForward, "port-forward", true, "Port-forward exposed container ports within pods")
+	cmd.Flags().StringArrayVarP(&opts.CustomLabels, "label", "l", nil, "Add custom labels to deployed objects. Set multiple times for multiple labels")
+	cmd.Flags().BoolVar(&opts.ExperimentalGUI, "experimental-gui", false, "Experimental Graphical User Interface")
+}
+
 func SetUpLogs(out io.Writer, level string) error {
 	logrus.SetOutput(out)
 	lvl, err := logrus.ParseLevel(v)

cmd/skaffold/app/cmd/debug.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2019 The Skaffold Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package cmd
+
+import (
+	"io"
+
+	debugging "github.com/GoogleContainerTools/skaffold/pkg/skaffold/debug"
+	"github.com/GoogleContainerTools/skaffold/pkg/skaffold/deploy"
+	"github.com/spf13/cobra"
+)
+
+// NewCmdDebug describes the CLI command to run a pipeline in debug mode.
+func NewCmdDebug(out io.Writer) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "debug",
+		Short: "Runs a pipeline file in debug mode",
+		Long:  "Similar to `dev`, but configures the pipeline for debugging.",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return debug(out)
+		},
+	}
+	AddRunDevFlags(cmd)
+	AddDevDebugFlags(cmd)
+	return cmd
+}
+
+func debug(out io.Writer) error {
+	// HACK: disable watcher to prevent redeploying changed containers during debugging
+	// TODO: enable file-sync but avoid redeploys of artifacts being debugged
+	if len(opts.TargetImages) == 0 {
+		opts.TargetImages = []string{"none"}
+	}
+
+	deploy.AddManifestTransform(debugging.ApplyDebuggingTransforms)
+
+	return dev(out, opts.ExperimentalGUI)
+}

cmd/skaffold/app/cmd/dev.go

@@ -44,15 +44,10 @@ func NewCmdDev(out io.Writer) *cobra.Command {
 		},
 	}
 	AddRunDevFlags(cmd)
-	cmd.Flags().BoolVar(&opts.TailDev, "tail", true, "Stream logs from deployed objects")
+	AddDevDebugFlags(cmd)
 	cmd.Flags().StringVar(&opts.Trigger, "trigger", "polling", "How are changes detected? (polling, manual or notify)")
-	cmd.Flags().BoolVar(&opts.Cleanup, "cleanup", true, "Delete deployments after dev mode is interrupted")
 	cmd.Flags().StringArrayVarP(&opts.TargetImages, "watch-image", "w", nil, "Choose which artifacts to watch. Artifacts with image names that contain the expression will be watched only. Default is to watch sources for all artifacts")
 	cmd.Flags().IntVarP(&opts.WatchPollInterval, "watch-poll-interval", "i", 1000, "Interval (in ms) between two checks for file changes")
-	cmd.Flags().BoolVar(&opts.PortForward, "port-forward", true, "Port-forward exposed container ports within pods")
-	cmd.Flags().StringArrayVarP(&opts.CustomLabels, "label", "l", nil, "Add custom labels to deployed objects. Set multiple times for multiple labels")
-	cmd.Flags().BoolVar(&opts.ExperimentalGUI, "experimental-gui", false, "Experimental Graphical User Interface")
-
 	return cmd
 }
 

docs/content/en/docs/how-tos/_index.md

@@ -14,3 +14,4 @@ weight: 30
 | [Port forwarding](/docs/how-tos/portforward) | Port forwarding from pods |
 | [Profiles](/docs/how-tos/profiles) | Define configurations for different contexts |
 | [Templated fields](/docs/how-tos/templating) | Adjust configuration with environment variables |
+| [Debugging (alpha)](/docs/how-tos/debug) | Enabling debugging of apps as deployed to a Kubernetes cluster |

docs/content/en/docs/how-tos/debug/_index.md

@@ -0,0 +1,48 @@
+---
+title: "Debugging with Skaffold"
+linkTitle: "Debugging"
+weight: 100
+---
+
+This page describes `skaffold debug`, a zero-configuration solution for
+setting up containers for debugging on a Kubernetes cluster. 
+
+{{< alert title="Note" >}}
+This functionality is in an alpha state and may change without warning.
+{{< /alert >}}
+
+## Debugging with Skaffold
+
+`skaffold debug` acts like `skaffold dev`, but it configures containers in pods
+ for debugging as required for each container's runtime technology.
+The associated debugging ports are exposed and labelled and port-forwarded to the
+local machine.  Helper metadata is also added to allow IDEs to detect the debugging
+configuration parameters.
+
+## How it works
+
+`skaffold debug` examines the built artifacts to determine the underlying runtime technology
+(currently supported: Java and NodeJS).  Any Kubernetes manifest that references these
+artifacts are transformed to enable the runtime technology's debugging functions:
+
+  - a JDWP agent is configured for Java applications,
+  - the Chrome DevTools inspector is configured for NodeJS applications.
+
+`skaffold debug` uses a set of heuristics to identify the runtime technology.
+The Kubernetes manifests are transformed on-the-fly such that the on-disk
+representations are untouched. 
+
+## Limitations
+
+`skaffold debug` has some limitations:
+
+  - Only the `kubectl` deployer is supported at the moment: the Helm and Kustomize
+    deployers are not yet available.
+  - Only JVM and NodeJS applications are supported:
+      - JVM applications are configured using the `JAVA_TOOL_OPTIONS` environment variable
+        which causes extra debugging output on launch.
+      - NodeJS applications must be launched using `node` or `nodemon`
+  - File watching is disabled for all artifacts, regardless of whether
+    the artifact could be configured for debugging.
+
+ Support for additional language runtimes will be forthcoming.

docs/content/en/docs/references/cli/_index.md

@@ -214,6 +214,57 @@ Env vars:
 * `SKAFFOLD_GLOBAL` (same as `--global`)
 * `SKAFFOLD_KUBE_CONTEXT` (same as `--kube-context`)
 
+### skaffold debug
+
+Runs a pipeline file in debug mode
+
+```
+Usage:
+  skaffold debug
+
+Flags:
+      --cache-artifacts           Set to true to enable caching of artifacts.
+      --cache-file string         Specify the location of the cache file (default $HOME/.skaffold/cache)
+      --cleanup                   Delete deployments after dev mode is interrupted (default true)
+  -d, --default-repo string       Default repository value (overrides global config)
+      --enable-rpc skaffold dev   Enable gRPC for exposing Skaffold events (true by default for skaffold dev)
+      --experimental-gui          Experimental Graphical User Interface
+  -f, --filename string           Filename or URL to the pipeline file (default "skaffold.yaml")
+  -l, --label stringArray         Add custom labels to deployed objects. Set multiple times for multiple labels
+  -n, --namespace string          Run deployments in the specified namespace
+      --port-forward              Port-forward exposed container ports within pods (default true)
+  -p, --profile stringArray       Activate profiles by name
+      --rpc-http-port int         tcp port to expose event REST API over HTTP (default 50052)
+      --rpc-port int              tcp port to expose event API (default 50051)
+      --skip-tests                Whether to skip the tests after building
+      --tail                      Stream logs from deployed objects (default true)
+      --toot                      Emit a terminal beep after the deploy is complete
+
+Global Flags:
+      --color int          Specify the default output color in ANSI escape codes (default 34)
+  -v, --verbosity string   Log level (debug, info, warn, error, fatal, panic) (default "warning")
+
+
+```
+Env vars:
+
+* `SKAFFOLD_CACHE_ARTIFACTS` (same as `--cache-artifacts`)
+* `SKAFFOLD_CACHE_FILE` (same as `--cache-file`)
+* `SKAFFOLD_CLEANUP` (same as `--cleanup`)
+* `SKAFFOLD_DEFAULT_REPO` (same as `--default-repo`)
+* `SKAFFOLD_ENABLE_RPC` (same as `--enable-rpc`)
+* `SKAFFOLD_EXPERIMENTAL_GUI` (same as `--experimental-gui`)
+* `SKAFFOLD_FILENAME` (same as `--filename`)
+* `SKAFFOLD_LABEL` (same as `--label`)
+* `SKAFFOLD_NAMESPACE` (same as `--namespace`)
+* `SKAFFOLD_PORT_FORWARD` (same as `--port-forward`)
+* `SKAFFOLD_PROFILE` (same as `--profile`)
+* `SKAFFOLD_RPC_HTTP_PORT` (same as `--rpc-http-port`)
+* `SKAFFOLD_RPC_PORT` (same as `--rpc-port`)
+* `SKAFFOLD_SKIP_TESTS` (same as `--skip-tests`)
+* `SKAFFOLD_TAIL` (same as `--tail`)
+* `SKAFFOLD_TOOT` (same as `--toot`)
+
 ### skaffold delete
 
 Delete the deployed resources

pkg/skaffold/debug/debug.go

@@ -0,0 +1,132 @@
+/*
+Copyright 2019 The Skaffold Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package debug
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"strings"
+
+	"github.com/pkg/errors"
+	"github.com/sirupsen/logrus"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	serializer "k8s.io/apimachinery/pkg/runtime/serializer/json"
+	"k8s.io/client-go/kubernetes/scheme"
+
+	"github.com/GoogleContainerTools/skaffold/pkg/skaffold/build"
+	"github.com/GoogleContainerTools/skaffold/pkg/skaffold/deploy/kubectl"
+	"github.com/GoogleContainerTools/skaffold/pkg/skaffold/docker"
+)
+
+var (
+	decodeFromYaml = scheme.Codecs.UniversalDeserializer().Decode
+	encodeAsYaml   = func(o runtime.Object) ([]byte, error) {
+		s := serializer.NewYAMLSerializer(serializer.DefaultMetaFactory, scheme.Scheme, scheme.Scheme)
+		var b bytes.Buffer
+		w := bufio.NewWriter(&b)
+		if err := s.Encode(o, w); err != nil {
+			return nil, err
+		}
+		w.Flush()
+		return b.Bytes(), nil
+	}
+)
+
+// ApplyDebuggingTransforms applies language-platform-specific transforms to a list of manifests.
+func ApplyDebuggingTransforms(l kubectl.ManifestList, builds []build.Artifact) (kubectl.ManifestList, error) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	retriever := func(image string) (imageConfiguration, error) {
+		if artifact := findArtifact(image, builds); artifact != nil {
+			return retrieveImageConfiguration(ctx, artifact)
+		}
+		return imageConfiguration{}, errors.Errorf("no build artifact for [%q]", image)
+	}
+	return applyDebuggingTransforms(l, retriever)
+}
+
+func applyDebuggingTransforms(l kubectl.ManifestList, retriever configurationRetriever) (kubectl.ManifestList, error) {
+	var updated kubectl.ManifestList
+	for _, manifest := range l {
+		obj, _, err := decodeFromYaml(manifest, nil, nil)
+		if err != nil {
+			return nil, errors.Wrap(err, "reading kubernetes YAML")
+		}
+
+		if transformManifest(obj, retriever) {
+			manifest, err = encodeAsYaml(obj)
+			if err != nil {
+				return nil, errors.Wrap(err, "marshalling yaml")
+			}
+			if logrus.IsLevelEnabled(logrus.DebugLevel) {
+				logrus.Debugln("Applied debugging transform:\n", string(manifest))
+			}
+		}
+		updated = append(updated, manifest)
+	}
+
+	return updated, nil
+}
+
+// findArtifact finds the corresponding artifact for the given image
+func findArtifact(image string, builds []build.Artifact) *build.Artifact {
+	for _, artifact := range builds {
+		if image == artifact.ImageName || image == artifact.Tag {
+			logrus.Debugf("Found artifact for image [%s]", image)
+			return &artifact
+		}
+	}
+	return nil
+}
+
+// retrieveImageConfiguration retrieves the image container configuration for
+// the given build artifact
+func retrieveImageConfiguration(ctx context.Context, artifact *build.Artifact) (imageConfiguration, error) {
+	apiClient, err := docker.NewAPIClient()
+	if err != nil {
+		return imageConfiguration{}, errors.Wrap(err, "could not connect to local docker daemon")
+	}
+
+	// the apiClient will go to the remote registry if local docker daemon is not available
+	manifest, err := apiClient.ConfigFile(ctx, artifact.Tag)
+	if err != nil {
+		logrus.Debugf("Error retrieving image manifest for %v: %v", artifact.Tag, err)
+		return imageConfiguration{}, errors.Wrapf(err, "retrieving image config for %q", artifact.Tag)
+	}
+
+	config := manifest.Config
+	logrus.Debugf("Retrieved local image configuration for %v: %v", artifact.Tag, config)
+	return imageConfiguration{
+		env:        envAsMap(config.Env),
+		entrypoint: config.Entrypoint,
+		arguments:  config.Cmd,
+		labels:     config.Labels,
+	}, nil
+}
+
+// envAsMap turns an array of environment "NAME=value" strings into a map
+func envAsMap(env []string) map[string]string {
+	result := make(map[string]string)
+	for _, pair := range env {
+		s := strings.SplitN(pair, "=", 2)
+		result[s[0]] = s[1]
+	}
+	return result
+}