mirror of https://github.com/k3s-io/k3s
1737a43324
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 |
||
|---|---|---|
| .. | ||
| admin | ||
| api-reference | ||
| man/man1 | ||
| user-guide/kubectl | ||
| yaml/kubectl | ||
| .generated_docs | ||
| BUILD | ||
| OWNERS | ||