Update the README and other cleanups

Signed-off-by: Mario Loriedo <[email protected]>

Author: l0rd

.gitignore

@@ -1,2 +1,3 @@
 kubectl-debug_ide
 .idea/*
+.DS_Store

README.md

@@ -2,63 +2,93 @@
 
 A `kubectl` plugin to debug Pods with an IDE rather than the CLI.
 
-![kubectl debug-ide in action](img/demo.gif)
+:warning: This plugin is in its alpha stage and is missing some important feature compared to `kubectl debug`. Running
+the IDE in an ephemeral debugging container (rather than copying the target Pod) is not supported. Workloads other than
+`Pods` aren't supported either.
+
+## How does `kubectl debug-ide` work?
 
-## Prerequirements
+Running `kubectl debug-ide` is similar to running `kubectl debug` (same flags) but an IDE is started and a git
+repository is cloned within the debugging container.
 
-The [DevWorkspace Operator](https://github.com/devfile/devworkspace-operator/tree/main) needs to be installed in the
-Kubernetes cluster.
+![kubectl debug-ide in action](img/demo.gif)
 
-## Details
+The command returns the URL of the remote IDE (local IDE support is not implemented yet). Opening the IDE URL in a 
+browser allow debugging a process in the target container. Note that the IDE runs in the debugging container, but
+"local" debugging is possible as the debugging container and the target container share the same process namespace.
 
-The plugin uses the [client-go library](https://github.com/kubernetes/client-go/tree/master/tools/clientcmd) to create a DevWorkspace in the current namespace.
+![debugging using an IDE](img/outyet-debug.gif)
 
-It accepts the same flags as the command `kubectl debug` which it tries to mimic as much as possible, but including an
-IDE for source code debugging.
+## Examples
 
-## Running
+The following command creates a copy of the Pod `$TARGET_POD` with an extra container using image
+`$DEBUGGING_CONTAINER_IMG` where `$GIT_REPO` is cloned and an IDE is started. 
 
 ```sh
-$ go install cmd/kubectl-debug_ide.go
+TARGET_POD="outyet"
+DEBUGGING_CONTAINER_IMG="ghcr.io/l0rd/outyet-dev:latest"
+TARGET_POD_COPY="outyet-debug"
+GIT_REPO="https://github.com/l0rd/outyet.git"
+
+kubectl debug-ide $TARGET_POD \
+  --image $DEBUGGING_CONTAINER_IMG \
+  --copy-to $TARGET_POD_COPY \
+  --share-processes \
+  --git-repository $GIT_REPO
+```
 
-# assumes you have a working KUBECONFIG
-# you can now begin using this plugin as a regular kubectl command:
-# start debugging the pod `outyet`
-$ kubectl debug-ide outyet \
-  --image ghcr.io/l0rd/outyet-dev:latest \
-  --copy-to outyet-debug \
+:mega: The containers in the copy of target Pod share the PID namespace. This is helpful to attach the IDE debugger to
+the target process as they run in separate containers.
+
+Delete the `DevWorkspace` Custom resource to stop the debugging session and cleanup the Kubernetes resources created by 
+`kubectl debug-id`:
+
+```sh
+TARGET_POD="outyet"
+DEBUGGING_CONTAINER_IMG="ghcr.io/l0rd/outyet-dev:latest"
+TARGET_POD_COPY="outyet-debug"
+GIT_REPO="https://github.com/l0rd/outyet.git"
+
+kubectl debug-ide $TARGET_POD \
+  --image $DEBUGGING_CONTAINER_IMG \
+  --copy-to $TARGET_POD_COPY \
   --share-processes \
-  --git-repository https://github.com/l0rd/outyet.git
+  --git-repository $GIT_REPO
 ```
 
-## Shell completion
+:mega: `kubectl delete pod` won't work in this case as the DevWorkspace Operator will restart the Pod.
 
-This plugin supports shell completion when used through kubectl. To enable shell completion for the plugin
-you must copy the file `./kubectl_complete-cde` somewhere on `$PATH` and give it executable permissions.
+## Requirements
 
-The `./kubectl_complete-cde` script shows a hybrid approach to providing completions:
-1. it uses the builtin `__complete` command provided by [Cobra](https://github.com/spf13/cobra) for flags
-1. it calls `kubectl` to obtain the list of pods to complete arguments (note that a more elegant approach would be to
-have the `kubectl-cde` program itself provide completion of arguments by implementing Cobra's `ValidArgsFunction` to
-fetch the list of pods, but it would then be a less varied example)
+Running `kubectl debug-ide` requires the [DevWorkspace Operator](https://github.com/devfile/devworkspace-operator/tree/main).
+`kubectl debug-ide` creates Custom Resources of type `DevWorkspace`.
 
-One can then do things like:
-```
-$ kubectl debug-ide <TAB>
-outyet
-
-$ kubectl debug-ide --<TAB>
---copy-to
---image
---git-repository
---share-processes
-[...]
+Building (and currently installing too) requires [Go](https://go.dev/dl/).
+
+## Installation
+
+To install `kubectl debug-ide` clone this git repository and run `go install`:  
+
+```sh
+$ go install cmd/kubectl-debug_ide.go
 ```
 
-Note: kubectl v1.26 or higher is required for shell completion to work for plugins.
+## Shell completion
+
+Copy the file `./kubectl_complete-ide` somewhere on `$PATH` and give it executable permissions to enable shell
+completion for the plugin.
+
+:mega: kubectl v1.26 or higher is required for shell completion to work for plugins.
 
 ## Cleanup
 
 You can "uninstall" this plugin from kubectl by simply removing it from your PATH:
 
-    $ rm /usr/local/bin/kubectl-debug_ide
+    $ rm  $GOBIN/kubectl-debug_ide
+
+## Acknowledgments
+
+The awesome [sample-cli-plugin](https://github.com/kubernetes/sample-cli-plugin) was used to kick off this plugin.
+
+`kubectl debug-ide` is just a generator of DevWorkspace Custom Resources. The heavy lifting, the Cloud Development
+Environment provisioning, is done by the [DevWorkspace Operator](https://github.com/devfile/devworkspace-operator).

cmd/kubectl-debug_ide.go

@@ -26,7 +26,7 @@ import (
 )
 
 func main() {
-	flags := pflag.NewFlagSet("kubectl-debug_cde", pflag.ExitOnError)
+	flags := pflag.NewFlagSet("kubectl-debug_ide", pflag.ExitOnError)
 	pflag.CommandLine = flags
 
 	root := pkg.NewCmdDebugIDE(genericiooptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr})

img/outyet-debug.gif

@@ -6,7 +6,7 @@ args=("$@")
 lastArg=${args[((${#args[@]}-1))]}
 if [[ "$lastArg" == -* ]]; then
    if [[ "$lastArg" != *=* ]]; then
-      kubectl debug-cde __complete "$@"
+      kubectl debug-ide __complete "$@"
    fi
 else
    # TODO Make sure we are not completing the value of a flag.
@@ -21,4 +21,4 @@ else
    # Turn off file completion.  See the ShellCompDirective documentation within
    # https://github.com/spf13/cobra/blob/main/shell_completions.md#completion-of-nouns
    echo :4
-fi
+fi

kubectl_complete-cde renamed to kubectl_complete-ide

@@ -94,7 +94,7 @@ func NewCmdDebugIDE(streams genericiooptions.IOStreams) *cobra.Command {
 	o := NewDebugIDEOptions(streams)
 
 	cmd := &cobra.Command{
-		Use:          "debug-cde [pod] [flags]",
+		Use:          "debug-ide [pod] [flags]",
 		Short:        "Create a copy of a Pod and add a Cloud Development Environment to debug it.",
 		Example:      fmt.Sprintf(debugIDEExample, "kubectl"),
 		SilenceUsage: true,

pkg/debug-cde.go renamed to pkg/debug-ide.go

@@ -64,19 +64,15 @@ EOF
 
 kubectl wait --for=condition=Ready pod/outyet
 
-echo
-echo "Building..."
-echo
-go build cmd/kubectl-debug_cde.go
 echo
 echo "Installing..."
 echo
-cp ./kubectl-debug_cde ~/.bin/
+go install cmd/kubectl-debug_ide.go
 
 echo
 echo "Running..."
 echo
-kubectl debug-cde outyet \
+kubectl debug-ide outyet \
   --image ghcr.io/l0rd/outyet-dev:latest \
   --copy-to outyet-debug \
   --share-processes \