Merge pull request #66876 from juanvallejo/jvallejo/prototype-plugins

Automatic merge from submit-queue (batch tested with PRs 67062, 67169, 67539, 67504, 66876). If you want to cherry-pick this change to another branch, please follow the instructions <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md">here</a>.

Update the kubectl plugin mechanism

**Release note**:
```release-note
The plugin mechanism functionality to closely follow the git plugin design
```

Replace the existing plugin mechanism with the design proposed in kubernetes/community#2437.

~~_The full implementation of the plugin mechanism itself is entirely contained within the first commit._~~

## Walkthrough

Under the new design, there is no plugin installation or loading required to use plugins.
A plugin is simply any executable file on a user's PATH whose name begins with `kubectl-`.
- Plugins receive the inherited environment from the `kubectl` binary. All environment variables
accessible by `kubectl` become accessible by the plugin.
- Plugins decide which command path they wish to implement based on their name. For example, a plugin wanting to provide a new command `foo`, would simply be named `kubectl-foo`.

### Creating a plugin

Below is an example plugin, that we will use for this walkthrough. Plugins may be written in any language, and handle arguments and flags in any way, optionally (as a convention) providing a way to retrieve their version via a `version` subcommand.

```bash
#!/bin/bash

# optional argument handling
if [[ "$1" == "version" ]]
then
    echo "1.0.0"
    exit 0
fi

# optional argument handling
if [[ "$1" == "config" ]]
then
    echo $KUBECONFIG
    exit 0
fi

echo "I am a plugin named kubectl-foo"
```

### Using a plugin

To use a plugin, simply make it executable:

```bash
sudo chmod +x ./kubectl-foo
```

and place it anywhere in your PATH:

```bash
sudo mv ./kubectl-foo /usr/local/bin
```

You may now invoke your plugin as a `kubectl` command:

```bash
$ kubectl foo
I am a plugin named kubectl-foo
```

All args and flags are passed as-is to the executable:

```bash
$ kubectl foo version
1.0.0
```

All environment variables are also passed as-is to the executable:

```bash
$ export KUBECONFIG=~/.kube/config
$ kubectl foo config
/home/<user>/.kube/config

$ KUBECONFIG=/etc/kube/config kubectl foo config
/etc/kube/config
```

Additionally, the first argument that is passed to a plugin will always be the full path to the location where it was invoked (`$0` would equal `/usr/local/bin/kubectl-foo` in our example above).

### Plugin discoverability

Seeing as how the `kubectl plugin` command is left as a no-op with this PR (perhaps it could serve as an entrypoint towards additional plugin functionality in the future), a small subcommand has been included that _lists all available plugin executables on a user's PATH_, along with any warnings it finds.

Example usage of this new subcommand is included below:

```bash
$ kubectl plugin list
The following kubectl-compatible plugins are available:

test/fixtures/pkg/kubectl/plugins/kubectl-foo
plugins/kubectl-foo
  - warning: plugins/kubectl-foo is overshadowed by a similarly named plugin: test/fixtures/pkg/kubectl/plugins/kubectl-foo
plugins/kubectl-invalid
  - warning: plugins/kubectl-invalid identified as a kubectl plugin, but it is not executable
plugins/kubectl-bar

error: 2 plugin warnings were found
```

cc @kubernetes/kubectl-maintainers @kubernetes/sig-cli-pr-reviews @soltysh @seans3 @mengqiy

docs/.generated_docs

@@ -243,6 +243,7 @@ docs/man/man1/kubectl-label.1
 docs/man/man1/kubectl-logs.1
 docs/man/man1/kubectl-options.1
 docs/man/man1/kubectl-patch.1
+docs/man/man1/kubectl-plugin-list.1
 docs/man/man1/kubectl-plugin.1
 docs/man/man1/kubectl-port-forward.1
 docs/man/man1/kubectl-proxy.1
@@ -346,6 +347,7 @@ docs/user-guide/kubectl/kubectl_logs.md
 docs/user-guide/kubectl/kubectl_options.md
 docs/user-guide/kubectl/kubectl_patch.md
 docs/user-guide/kubectl/kubectl_plugin.md
+docs/user-guide/kubectl/kubectl_plugin_list.md
 docs/user-guide/kubectl/kubectl_port-forward.md
 docs/user-guide/kubectl/kubectl_proxy.md
 docs/user-guide/kubectl/kubectl_replace.md

docs/man/man1/kubectl-plugin-list.1

@@ -0,0 +1,3 @@
+This file is autogenerated, but we've stopped checking such files into the
+repository to reduce the need for rebases. Please run hack/generate-docs.sh to
+populate this file.

docs/user-guide/kubectl/kubectl_plugin_list.md

@@ -0,0 +1,3 @@
+This file is autogenerated, but we've stopped checking such files into the
+repository to reduce the need for rebases. Please run hack/generate-docs.sh to
+populate this file.

pkg/kubectl/BUILD

@@ -188,7 +188,6 @@ filegroup(
         "//pkg/kubectl/explain:all-srcs",
         "//pkg/kubectl/genericclioptions:all-srcs",
         "//pkg/kubectl/metricsutil:all-srcs",
-        "//pkg/kubectl/plugins:all-srcs",
         "//pkg/kubectl/polymorphichelpers:all-srcs",
         "//pkg/kubectl/proxy:all-srcs",
         "//pkg/kubectl/scheme:all-srcs",

pkg/kubectl/cmd/BUILD

@@ -78,7 +78,6 @@ go_library(
         "//pkg/kubectl/genericclioptions/printers:go_default_library",
         "//pkg/kubectl/genericclioptions/resource:go_default_library",
         "//pkg/kubectl/metricsutil:go_default_library",
-        "//pkg/kubectl/plugins:go_default_library",
         "//pkg/kubectl/polymorphichelpers:go_default_library",
         "//pkg/kubectl/proxy:go_default_library",
         "//pkg/kubectl/scheme:go_default_library",
@@ -172,7 +171,6 @@ go_test(
         "label_test.go",
         "logs_test.go",
         "patch_test.go",
-        "plugin_test.go",
         "portforward_test.go",
         "replace_test.go",
         "rollingupdate_test.go",
@@ -203,7 +201,6 @@ go_test(
         "//pkg/kubectl/genericclioptions:go_default_library",
         "//pkg/kubectl/genericclioptions/printers:go_default_library",
         "//pkg/kubectl/genericclioptions/resource:go_default_library",
-        "//pkg/kubectl/plugins:go_default_library",
         "//pkg/kubectl/polymorphichelpers:go_default_library",
         "//pkg/kubectl/scheme:go_default_library",
         "//pkg/kubectl/util/i18n:go_default_library",

pkg/kubectl/cmd/cmd.go

@@ -21,6 +21,12 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"os/exec"
+	"runtime"
+	"strings"
+	"syscall"
+
+	"github.com/spf13/cobra"
 
 	"k8s.io/apimachinery/pkg/api/meta"
 	utilflag "k8s.io/apiserver/pkg/util/flag"
@@ -36,7 +42,6 @@ import (
 	"k8s.io/kubernetes/pkg/kubectl/cmd/wait"
 	"k8s.io/kubernetes/pkg/kubectl/util/i18n"
 
-	"github.com/spf13/cobra"
 	"k8s.io/kubernetes/pkg/kubectl/genericclioptions"
 )
 
@@ -257,7 +262,100 @@ var (
 )
 
 func NewDefaultKubectlCommand() *cobra.Command {
-	return NewKubectlCommand(os.Stdin, os.Stdout, os.Stderr)
+	return NewDefaultKubectlCommandWithArgs(&defaultPluginHandler{}, os.Args, os.Stdin, os.Stdout, os.Stderr)
+}
+
+func NewDefaultKubectlCommandWithArgs(pluginHandler PluginHandler, args []string, in io.Reader, out, errout io.Writer) *cobra.Command {
+	cmd := NewKubectlCommand(in, out, errout)
+
+	if pluginHandler == nil {
+		return cmd
+	}
+
+	if len(args) > 1 {
+		cmdPathPieces := args[1:]
+
+		// only look for suitable extension executables if
+		// the specified command does not already exist
+		if _, _, err := cmd.Find(cmdPathPieces); err != nil {
+			if err := handleEndpointExtensions(pluginHandler, cmdPathPieces); err != nil {
+				fmt.Fprintf(errout, "%v\n", err)
+				os.Exit(1)
+			}
+		}
+	}
+
+	return cmd
+}
+
+// PluginHandler is capable of parsing command line arguments
+// and performing executable filename lookups to search
+// for valid plugin files, and execute found plugins.
+type PluginHandler interface {
+	// Lookup receives a potential filename and returns
+	// a full or relative path to an executable, if one
+	// exists at the given filename, or an error.
+	Lookup(filename string) (string, error)
+	// Execute receives an executable's filepath, a slice
+	// of arguments, and a slice of environment variables
+	// to relay to the executable.
+	Execute(executablePath string, cmdArgs, environment []string) error
+}
+
+type defaultPluginHandler struct{}
+
+// Lookup implements PluginHandler
+func (h *defaultPluginHandler) Lookup(filename string) (string, error) {
+	// if on Windows, append the "exe" extension
+	// to the filename that we are looking up.
+	if runtime.GOOS == "windows" {
+		filename = filename + ".exe"
+	}
+
+	return exec.LookPath(filename)
+}
+
+// Execute implements PluginHandler
+func (h *defaultPluginHandler) Execute(executablePath string, cmdArgs, environment []string) error {
+	return syscall.Exec(executablePath, cmdArgs, environment)
+}
+
+func handleEndpointExtensions(pluginHandler PluginHandler, cmdArgs []string) error {
+	remainingArgs := []string{} // all "non-flag" arguments
+
+	for idx := range cmdArgs {
+		if strings.HasPrefix(cmdArgs[idx], "-") {
+			break
+		}
+		remainingArgs = append(remainingArgs, strings.Replace(cmdArgs[idx], "-", "_", -1))
+	}
+
+	foundBinaryPath := ""
+
+	// attempt to find binary, starting at longest possible name with given cmdArgs
+	for len(remainingArgs) > 0 {
+		path, err := pluginHandler.Lookup(fmt.Sprintf("kubectl-%s", strings.Join(remainingArgs, "-")))
+		if err != nil || len(path) == 0 {
+			remainingArgs = remainingArgs[:len(remainingArgs)-1]
+			continue
+		}
+
+		foundBinaryPath = path
+		break
+	}
+
+	if len(foundBinaryPath) == 0 {
+		return nil
+	}
+
+	// invoke cmd binary relaying the current environment and args given
+	// remainingArgs will always have at least one element.
+	// execve will make remainingArgs[0] the "binary name".
+	if err := pluginHandler.Execute(foundBinaryPath, append([]string{foundBinaryPath}, cmdArgs[len(remainingArgs):]...), os.Environ()); err != nil {
+		return err
+	}
+
+	return nil
 }
 
 // NewKubectlCommand creates the `kubectl` command and its nested children.

pkg/kubectl/cmd/cmd_test.go

@@ -19,6 +19,7 @@ package cmd
 import (
 	"bytes"
 	"encoding/json"
+	"fmt"
 	"io"
 	"io/ioutil"
 	"net/http"
@@ -37,6 +38,7 @@ import (
 	"k8s.io/kubernetes/pkg/api/testapi"
 	apitesting "k8s.io/kubernetes/pkg/api/testing"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
+	"k8s.io/kubernetes/pkg/kubectl/genericclioptions"
 	"k8s.io/kubernetes/pkg/kubectl/scheme"
 )
 
@@ -213,3 +215,106 @@ func Test_deprecatedAlias(t *testing.T) {
 		t.Errorf("original function doesn't appear to have been called by alias")
 	}
 }
+
+func TestKubectlCommandHandlesPlugins(t *testing.T) {
+	tests := []struct {
+		name             string
+		args             []string
+		expectPlugin     string
+		expectPluginArgs []string
+		expectError      string
+	}{
+		{
+			name:             "test that normal commands are able to be executed, when no plugin overshadows them",
+			args:             []string{"kubectl", "get", "foo"},
+			expectPlugin:     "",
+			expectPluginArgs: []string{},
+		},
+		{
+			name:             "test that a plugin executable is found based on command args",
+			args:             []string{"kubectl", "foo", "--bar"},
+			expectPlugin:     "testdata/plugin/kubectl-foo",
+			expectPluginArgs: []string{"foo", "--bar"},
+		},
+		{
+			name: "test that a plugin does not execute over an existing command by the same name",
+			args: []string{"kubectl", "version"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			pluginsHandler := &testPluginHandler{
+				pluginsDirectory: "testdata/plugin",
+			}
+			_, in, out, errOut := genericclioptions.NewTestIOStreams()
+
+			cmdutil.BehaviorOnFatal(func(str string, code int) {
+				errOut.Write([]byte(str))
+			})
+
+			root := NewDefaultKubectlCommandWithArgs(pluginsHandler, test.args, in, out, errOut)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			if pluginsHandler.err != nil && pluginsHandler.err.Error() != test.expectError {
+				t.Fatalf("unexpected error: expected %q to occur, but got %q", test.expectError, pluginsHandler.err)
+			}
+
+			if pluginsHandler.executedPlugin != test.expectPlugin {
+				t.Fatalf("unexpected plugin execution: expedcted %q, got %q", test.expectPlugin, pluginsHandler.executedPlugin)
+			}
+
+			if len(pluginsHandler.withArgs) != len(test.expectPluginArgs) {
+				t.Fatalf("unexpected plugin execution args: expedcted %q, got %q", test.expectPluginArgs, pluginsHandler.withArgs)
+			}
+		})
+	}
+}
+
+type testPluginHandler struct {
+	pluginsDirectory string
+
+	// execution results
+	executedPlugin string
+	withArgs       []string
+	withEnv        []string
+
+	err error
+}
+
+func (h *testPluginHandler) Lookup(filename string) (string, error) {
+	dir, err := os.Stat(h.pluginsDirectory)
+	if err != nil {
+		h.err = err
+		return "", err
+	}
+
+	if !dir.IsDir() {
+		h.err = fmt.Errorf("expected %q to be a directory", h.pluginsDirectory)
+		return "", h.err
+	}
+
+	plugins, err := ioutil.ReadDir(h.pluginsDirectory)
+	if err != nil {
+		h.err = err
+		return "", err
+	}
+
+	for _, p := range plugins {
+		if p.Name() == filename {
+			return fmt.Sprintf("%s/%s", h.pluginsDirectory, p.Name()), nil
+		}
+	}
+
+	h.err = fmt.Errorf("unable to find a plugin executable %q", filename)
+	return "", h.err
+}
+
+func (h *testPluginHandler) Execute(executablePath string, cmdArgs, env []string) error {
+	h.executedPlugin = executablePath
+	h.withArgs = cmdArgs
+	h.withEnv = env
+	return nil
+}