• Kubernetes Submit Queue's avatar
    Merge pull request #66876 from juanvallejo/jvallejo/prototype-plugins · 1737a433
    Kubernetes Submit Queue authored
    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
    1737a433
Name
Last commit
Last update
..
admin Loading commit data...
api-reference Loading commit data...
man/man1 Loading commit data...
user-guide/kubectl Loading commit data...
yaml/kubectl Loading commit data...
.generated_docs Loading commit data...
BUILD Loading commit data...
OWNERS Loading commit data...