From ed0e0350854e34bad65de4db44c0f661a5851870 Mon Sep 17 00:00:00 2001 From: Cornelius Weig Date: Wed, 26 Feb 2020 14:50:50 +0100 Subject: [PATCH] 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 --- .../src/k8s.io/kubectl/docs/book/SUMMARY.md | 7 +- .../extending_kubectl/discovering_plugins.md | 67 +++++++++++++++++++ .../extending_kubectl/plugin_mechanism.md | 35 ++++++++++ .../pages/kubectl_book/getting_started.md | 18 +++++ .../k8s.io/kubectl/pkg/cmd/plugin/plugin.go | 5 +- 5 files changed, 130 insertions(+), 2 deletions(-) create mode 100644 staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/discovering_plugins.md create mode 100644 staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/plugin_mechanism.md diff --git a/staging/src/k8s.io/kubectl/docs/book/SUMMARY.md b/staging/src/k8s.io/kubectl/docs/book/SUMMARY.md index 3445ed3d301..d830bdf925a 100644 --- a/staging/src/k8s.io/kubectl/docs/book/SUMMARY.md +++ b/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) \ No newline at end of file +* [Editing Workloads](pages/imperative_porcelain/editing_workloads.md) diff --git a/staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/discovering_plugins.md b/staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/discovering_plugins.md new file mode 100644 index 00000000000..dde5f4926d3 --- /dev/null +++ b/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 %} diff --git a/staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/plugin_mechanism.md b/staging/src/k8s.io/kubectl/docs/book/pages/extending_kubectl/plugin_mechanism.md new file mode 100644 index 00000000000..869be92a47c --- /dev/null +++ b/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 %} diff --git a/staging/src/k8s.io/kubectl/docs/book/pages/kubectl_book/getting_started.md b/staging/src/k8s.io/kubectl/docs/book/pages/kubectl_book/getting_started.md index 0e2e71e247d..2ad3505ca5d 100644 --- a/staging/src/k8s.io/kubectl/docs/book/pages/kubectl_book/getting_started.md +++ b/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). diff --git a/staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin.go b/staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin.go index 0beba47d866..1b6d86c27d6 100644 --- a/staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin.go +++ b/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.