Merge pull request kubernetes#88577 from corneliusweig/w/plugin-and-krew-documentation

Add documentation around plugins

Author: k8s-ci-robot

staging/src/k8s.io/kubectl/docs/book/SUMMARY.md

@@ -33,6 +33,11 @@
 * [Port Forward to Pods](pages/container_debugging/port_forward_to_pods.md)
 * [Proxying Traffic to Services](pages/container_debugging/proxying_traffic_to_services.md)
 
+## Extending Kubectl
+
+* [Plugin mechanism](pages/extending_kubectl/plugin_mechanism.md)
+* [Discovering plugins](pages/extending_kubectl/discovering_plugins.md)
+
 ## App Customization
 
 * [Introduction](pages/app_customization/introduction.md)
@@ -68,4 +73,4 @@
 * [Introduction](pages/imperative_porcelain/introduction.md)
 * [Creating Resources](pages/imperative_porcelain/creating_resources.md)
 * [Setting Fields](pages/imperative_porcelain/setting_fields.md)
-* [Editing Workloads](pages/imperative_porcelain/editing_workloads.md)
+* [Editing Workloads](pages/imperative_porcelain/editing_workloads.md)

staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/discovering_plugins.md

@@ -0,0 +1,67 @@
+{% panel style="success", title="Providing Feedback" %}
+**Provide feedback at the [survey](https://www.surveymonkey.com/r/CLQBQHR)**
+{% endpanel %}
+
+{% panel style="info", title="TL;DR" %}
+- [krew.dev](https://github.com/kubernetes-sigs/krew/#installation) is a kubernetes sub-project to discover and manage plugins
+{% endpanel %}
+
+# Krew
+
+By design, `kubectl` does not install plugins. This task is left to the kubernetes sub-project
+[krew.dev](https://github.com/kubernetes-sigs/krew/#installation) which needs to be installed separately.
+Krew helps to
+
+- discover plugins
+- get updates for installed plugins
+- remove plugins
+
+## Installing krew
+
+Krew should be used as a kubectl plugin. To set yourself up to using krew, you need to do two things:
+
+1. Install git
+1. Install krew as described on the project page [krew.dev](https://github.com/kubernetes-sigs/krew/#installation).
+1. Add the krew bin folder to your `PATH` environment variable. For example, in bash `export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"`.
+
+## Krew capabilities
+
+{% method %}
+Discover plugins
+{% sample lang="yaml" %}
+```bash
+kubectl krew search
+```
+{% endmethod %}
+
+{% method %}
+Install a plugin
+{% sample lang="yaml" %}
+```bash
+kubectl krew install access-matrix
+```
+{% endmethod %}
+
+{% method %}
+Upgrade all installed plugins
+{% sample lang="yaml" %}
+```bash
+kubectl krew upgrade
+```
+{% endmethod %}
+
+{% method %}
+Show details about a plugin
+{% sample lang="yaml" %}
+```bash
+kubectl krew info access-matrix
+```
+{% endmethod %}
+
+{% method %}
+Uninstall a plugin
+{% sample lang="yaml" %}
+```bash
+kubectl krew uninstall access-matrix
+```
+{% endmethod %}

staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/plugin_mechanism.md

@@ -0,0 +1,35 @@
+{% panel style="success", title="Providing Feedback" %}
+**Provide feedback at the [survey](https://www.surveymonkey.com/r/CLQBQHR)**
+{% endpanel %}
+
+{% panel style="info", title="TL;DR" %}
+- Drop executables named `kubectl-plugin_name` on your `PATH` and invoke with `kubectl plugin-name`
+- `kubectl plugin list` shows available plugins
+{% endpanel %}
+
+# Kubectl plugins
+
+Kubectl plugins are a lightweight mechanism to extend `kubectl` with custom functionality to suit your needs.
+
+## Plugin mechanism
+
+As of version 1.12, kubectl has a simple plugin mechanism to expose binaries on your `PATH` as kubectl subcommands.
+When invoking an unknown subcommand `kubectl my-plugin`, kubectl starts searching for an executable named `kubectl-my_plugin` on your `PATH`.
+Note how the dash is mapped to an underscore. This is to enable plugins that are invoked by multiple words, for example 
+`kubectl my plugin` would trigger a search for the commands `kubectl-my-plugin` or `kubectl-my`. The more specific match
+always wins over the other, so if both `kubectl-my` and `kubectl-my-plugin` exist, the latter will be called.
+When a matching executable is found, kubectl calls it, forwarding all extra arguments.
+
+The reference on [kubernetes.io](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) knows more.
+
+{% panel style="info", title="Windows compatibility" %}
+On windows, the minimum required version to use the plugin mechanism is 1.14.
+{% endpanel %}
+
+{% method %}
+Listing installed plugins
+{% sample lang="yaml" %}
+```bash
+kubectl plugin list
+```
+{% endmethod %}

staging/src/k8s.io/kubectl/docs/book/pages/kubectl_book/getting_started.md

@@ -205,3 +205,21 @@ root@nginx-deployment-5c689d88bb-s7xcv:/#
 ```
 
 {% endmethod %}
+
+## Extending kubectl
+
+There is a plugin mechanism to adapt `kubectl` to your particular needs.
+
+{% method %}
+
+Show which plugins are currently available
+
+{% sample lang="yaml" %}
+
+```bash
+kubectl plugin list
+```
+
+{% endmethod %}
+
+The easiest way to discover and install plugins is via the kubernetes sub-project [krew.dev](https://github.com/kubernetes-sigs/krew/#installation).

staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin.go

@@ -38,7 +38,10 @@ var (
 		Provides utilities for interacting with plugins.
 
 		Plugins provide extended functionality that is not part of the major command-line distribution.
-		Please refer to the documentation and examples for more information about how write your own plugins.`)
+		Please refer to the documentation and examples for more information about how write your own plugins.
+
+		The easiest way to discover and install plugins is via the kubernetes sub-project krew.
+		To install krew, visit [krew.dev](https://github.com/kubernetes-sigs/krew/#installation)`)
 
 	pluginListLong = templates.LongDesc(`
 		List all available plugin files on a user's PATH.