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 https://github.com/kubernetes/community/pull/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.