Add documentation around plugins

Documentation is added in several areas:
1. `kubectl plugin` now prints a note that plugins are best discovered
   with krew.dev and how to install it.
2. The kubectl book now has a new section about plugins, featuring
   - a very brief introduction to the kubectl plugin mechanism
   - a section about krew

Kubernetes-commit: ed0e0350854e34bad65de4db44c0f661a5851870
This commit is contained in:
Cornelius Weig 2020-02-26 14:50:50 +01:00 committed by Kubernetes Publisher
parent 19ed29c90e
commit e54c7dba6a
5 changed files with 130 additions and 2 deletions

View File

@ -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)

View File

@ -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 %}

View File

@ -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 %}

View File

@ -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).

View File

@ -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.