diff --git a/docs/book/SUMMARY.md b/docs/book/SUMMARY.md index 3445ed3d..d830bdf9 100644 --- a/docs/book/SUMMARY.md +++ b/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/docs/book/pages/extending_kubectl/discovering_plugins.md b/docs/book/pages/extending_kubectl/discovering_plugins.md new file mode 100644 index 00000000..dde5f492 --- /dev/null +++ b/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/docs/book/pages/extending_kubectl/plugin_mechanism.md b/docs/book/pages/extending_kubectl/plugin_mechanism.md new file mode 100644 index 00000000..869be92a --- /dev/null +++ b/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/docs/book/pages/kubectl_book/getting_started.md b/docs/book/pages/kubectl_book/getting_started.md index 0e2e71e2..2ad3505c 100644 --- a/docs/book/pages/kubectl_book/getting_started.md +++ b/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/pkg/cmd/plugin/plugin.go b/pkg/cmd/plugin/plugin.go index 0beba47d..1b6d86c2 100644 --- a/pkg/cmd/plugin/plugin.go +++ b/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.