Reword “Extend kubectl with plugins” (kubernetes#17005)

* Tweak kubectl plugins page

- drop text about kubectl plugin beta status etc
- fix output formatted as shell
- address the reader as “you”
- other tweaks

* Update links & details for Krew

* Update kubectl-plugins.md

content/en/docs/tasks/extend-kubectl/kubectl-plugins.md

@@ -9,8 +9,6 @@ content_template: templates/task
 
 {{% capture overview %}}
 
-{{< feature-state state="stable" >}}
-
 This guide demonstrates how to install and write extensions for [kubectl](/docs/reference/kubectl/kubectl/). By thinking of core `kubectl` commands as essential building blocks for interacting with a Kubernetes cluster, a cluster administrator can think
 of plugins as a means of utilizing these building blocks to create more complex behavior. Plugins extend `kubectl` with new sub-commands, allowing for new and custom features not included in the main distribution of `kubectl`.
 
@@ -20,55 +18,54 @@ of plugins as a means of utilizing these building blocks to create more complex
 
 You need to have a working `kubectl` binary installed.
 
-{{< note >}}
-Plugins were officially introduced as an alpha feature in the v1.8.0 release. They have been re-worked in the v1.12.0 release to support a wider range of use-cases. So, while some parts of the plugins feature were already available in previous versions, a `kubectl` version of 1.12.0 or later is recommended if you are following these docs.
-{{< /note >}}
-
 {{% /capture %}}
 
 {{% capture steps %}}
 
 ## Installing kubectl plugins
 
-A plugin is nothing more than a standalone executable file, whose name begins with `kubectl-`. To install a plugin, simply move its executable file to anywhere on your PATH.
+A plugin is nothing more than a standalone executable file, whose name begins with `kubectl-`. To install a plugin, simply move its executable file to anywhere on your `PATH`.
 
 You can also discover and install kubectl plugins available in the open source
-using [Krew](https://sigs.k8s.io/krew). Krew is a plugin manager maintained by
+using [Krew](https://krew.dev/). Krew is a plugin manager maintained by
 the Kubernetes SIG CLI community.
 
 {{< caution >}}
-Kubectl plugins installed via the Krew [centralized
-index](https://github.com/kubernetes-sigs/krew-index) are not audited for
-security. You should install and run third-party plugins at your own risk, since
-they are arbitrary programs running on your machine.
-{{< /note >}}
+Kubectl plugins available via the Krew [plugin index](https://index.krew.dev/)
+are not audited for security. You should install and run third-party plugins at your
+own risk, since they are arbitrary programs running on your machine.
+{{< /caution >}}
 
 ### Discovering plugins
 
-`kubectl` provides a command `kubectl plugin list` that searches your PATH for valid plugin executables.
-Executing this command causes a traversal of all files in your PATH. Any files that are executable, and begin with `kubectl-` will show up *in the order in which they are present in your PATH* in this command's output.
+`kubectl` provides a command `kubectl plugin list` that searches your `PATH` for valid plugin executables.
+Executing this command causes a traversal of all files in your `PATH`. Any files that are executable, and begin with `kubectl-` will show up *in the order in which they are present in your `PATH`* in this command's output.
 A warning will be included for any files beginning with `kubectl-` that are *not* executable.
 A warning will also be included for any valid plugin files that overlap each other's name.
 
-You can use [Krew](https://sigs.k8s.io/krew) to discover and install `kubectl`
+You can use [Krew](https://krew.dev/) to discover and install `kubectl`
 plugins from a community-curated
-[plugin index](https://github.com/kubernetes-sigs/krew-index).
+[plugin index](https://index.krew.dev/).
 
 #### Limitations
 
-It is currently not possible to create plugins that overwrite existing `kubectl` commands. For example, creating a plugin `kubectl-version` will cause that plugin to never be executed, as the existing `kubectl version` command will always take precedence over it. Due to this limitation, it is also *not* possible to use plugins to add new subcommands to existing `kubectl` commands. For example, adding a subcommand `kubectl create foo` by naming your plugin `kubectl-create-foo` will cause that plugin to be ignored. Warnings will appear under the output of `kubectl plugin list` for any valid plugins that attempt to do this.
+It is currently not possible to create plugins that overwrite existing `kubectl` commands. For example, creating a plugin `kubectl-version` will cause that plugin to never be executed, as the existing `kubectl version` command will always take precedence over it. Due to this limitation, it is also *not* possible to use plugins to add new subcommands to existing `kubectl` commands. For example, adding a subcommand `kubectl create foo` by naming your plugin `kubectl-create-foo` will cause that plugin to be ignored.
+
+`kubectl plugin list` shows warnings for any valid plugins that attempt to do this.
 
 ## Writing kubectl plugins
 
 You can write a plugin in any programming language or script that allows you to write command-line commands.
 
-There is no plugin installation or pre-loading required. Plugin executables receive the inherited environment from the `kubectl` binary.
-A plugin determines which command path it wishes to implement based on its name. For example, a plugin wanting to provide a new command
-`kubectl foo`, would simply be named `kubectl-foo`, and live somewhere in the user's PATH.
+There is no plugin installation or pre-loading required. Plugin executables receive
+the inherited environment from the `kubectl` binary.
+A plugin determines which command path it wishes to implement based on its name. For
+example, a plugin wanting to provide a new command `kubectl foo`, would simply be named
+`kubectl-foo`, and live somewhere in your `PATH`.
 
 ### Example plugin
 
-```
+```bash
 #!/bin/bash
 
 # optional argument handling
@@ -96,7 +93,7 @@ To use the above plugin, simply make it executable:
 sudo chmod +x ./kubectl-foo
 ```
 
-and place it anywhere in your PATH:
+and place it anywhere in your `PATH`:
 
 ```
 sudo mv ./kubectl-foo /usr/local/bin
@@ -137,7 +134,7 @@ 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).
+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 the example above).
 
 ### Naming a plugin
 
@@ -147,15 +144,19 @@ For example, a plugin that wishes to be invoked whenever the command `kubectl fo
 #### Flags and argument handling
 
 {{< note >}}
-Unlike previous versions of `kubectl`, the plugin mechanism will _not_ create any custom, plugin-specific values or environment variables to a plugin process.
-This means that environment variables such as `KUBECTL_PLUGINS_CURRENT_NAMESPACE` are no longer provided to a plugin. Plugins must parse all of the arguments passed to them by a user,
-and handle flag validation as part of their own implementation. For plugins written in Go, a set of utilities has been provided under [k8s.io/cli-runtime](https://github.com/kubernetes/cli-runtime) to assist with this.
+The plugin mechanism does _not_ create any custom, plugin-specific values or environment variables for a plugin process.
+
+An older kubectl plugin mechanism provided environment variables such as `KUBECTL_PLUGINS_CURRENT_NAMESPACE`; that no longer happens.
 {{< /note >}}
 
-Taking our `kubectl-foo-bar-baz` plugin from the above scenario, we further explore additional cases where users invoke our plugin while providing additional flags and arguments.
-For example, in a situation where a user invokes the command `kubectl foo bar baz arg1 --flag=value arg2`, the plugin mechanism will first try to find the plugin with the longest possible name, which in this case
-would be `kubectl-foo-bar-baz-arg1`. Upon not finding that plugin, it then treats the last dash-separated value as an argument (`arg1` in this case), and attempts to find the next longest possible name, `kubectl-foo-bar-baz`.
-Upon finding a plugin with this name, it then invokes that plugin, passing all args and flags after its name to the plugin executable.
+kubectl plugins must parse and validate all of the arguments passed to them.
+See [using the command line runtime package](#using-the-command-line-runtime-package) for details of a Go library aimed at plugin authors.
+
+Here are some additional cases where users invoke your plugin while providing additional flags and arguments. This builds upon the the `kubectl-foo-bar-baz` plugin from the scenario above.
+
+If you run `kubectl foo bar baz arg1 --flag=value arg2`, kubectl's plugin mechanism will first try to find the plugin with the longest possible name, which in this case
+would be `kubectl-foo-bar-baz-arg1`. Upon not finding that plugin, kubectl then treats the last dash-separated value as an argument (`arg1` in this case), and attempts to find the next longest possible name, `kubectl-foo-bar-baz`.
+Upon having found a plugin with this name, kubectl then invokes that plugin, passing all args and flags after the plugin's name as arguments to the plugin process.
 
 Example:
 
@@ -164,28 +165,31 @@ Example:
 echo -e '#!/bin/bash\n\necho "My first command-line argument was $1"' > kubectl-foo-bar-baz
 sudo chmod +x ./kubectl-foo-bar-baz
 
-# "install" our plugin by placing it on our PATH
+# "install" your plugin by moving it to a directory in your $PATH
 sudo mv ./kubectl-foo-bar-baz /usr/local/bin
 
-# ensure our plugin is recognized by kubectl
+# chck that kubectl recognizes your plugin
 kubectl plugin list
 ```
+
 ```
 The following kubectl-compatible plugins are available:
 
 /usr/local/bin/kubectl-foo-bar-baz
 ```
+
 ```
-# test that calling our plugin via a "kubectl" command works
-# even when additional arguments and flags are passed to our
+# test that calling your plugin via a "kubectl" command works
+# even when additional arguments and flags are passed to your
 # plugin executable by the user.
 kubectl foo bar baz arg1 --meaningless-flag=true
 ```
+
 ```
 My first command-line argument was arg1
 ```
 
-As you can see, our plugin was found based on the `kubectl` command specified by a user, and all extra arguments and flags were passed as-is to the plugin executable once it was found.
+As you can see, your plugin was found based on the `kubectl` command specified by a user, and all extra arguments and flags were passed as-is to the plugin executable once it was found.
 
 #### Names with dashes and underscores
 
@@ -199,45 +203,49 @@ Example:
 echo -e '#!/bin/bash\n\necho "I am a plugin with a dash in my name"' > ./kubectl-foo_bar
 sudo chmod +x ./kubectl-foo_bar
 
-# move the plugin into your PATH
+# move the plugin into your $PATH
 sudo mv ./kubectl-foo_bar /usr/local/bin
 
-# our plugin can now be invoked from `kubectl` like so:
+# You can now invoke your plugin via kubectl:
 kubectl foo-bar
 ```
+
 ```
 I am a plugin with a dash in my name
 ```
 
-Note that the introduction of underscores to a plugin filename does not prevent us from having commands such as `kubectl foo_bar`.
+Note that the introduction of underscores to a plugin filename does not prevent you from having commands such as `kubectl foo_bar`.
 The command from the above example, can be invoked using either a dash (`-`) or an underscore (`_`):
 
 ```bash
-# our plugin can be invoked with a dash
+# You can invoke your custom command with a dash
 kubectl foo-bar
 ```
+
 ```
 I am a plugin with a dash in my name
 ```
 
 ```bash
-# it can also be invoked using an underscore
+# You can also invoke your custom command with an underscore
 kubectl foo_bar
 ```
+
 ```
 I am a plugin with a dash in my name
 ```
 
 #### Name conflicts and overshadowing
 
-It is possible to have multiple plugins with the same filename in different locations throughout your PATH.
-For example, given a PATH with the following value: `PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins`, a copy of plugin `kubectl-foo` could exist in `/usr/local/bin/plugins` and `/usr/local/bin/moreplugins`,
+It is possible to have multiple plugins with the same filename in different locations throughout your `PATH`.
+For example, given a `PATH` with the following value: `PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins`, a copy of plugin `kubectl-foo` could exist in `/usr/local/bin/plugins` and `/usr/local/bin/moreplugins`,
 such that the output of the `kubectl plugin list` command is:
 
 ```bash
 PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins kubectl plugin list
 ```
-```bash
+
+```
 The following kubectl-compatible plugins are available:
 
 /usr/local/bin/plugins/kubectl-foo
@@ -247,39 +255,43 @@ The following kubectl-compatible plugins are available:
 error: one plugin warning was found
 ```
 
-In the above scenario, the warning under `/usr/local/bin/moreplugins/kubectl-foo` tells us that this plugin will never be executed. Instead, the executable that appears first in our PATH, `/usr/local/bin/plugins/kubectl-foo`, will always be found and executed first by the `kubectl` plugin mechanism.
+In the above scenario, the warning under `/usr/local/bin/moreplugins/kubectl-foo` tells you that this plugin will never be executed. Instead, the executable that appears first in your `PATH`, `/usr/local/bin/plugins/kubectl-foo`, will always be found and executed first by the `kubectl` plugin mechanism.
 
-A way to resolve this issue is to ensure that the location of the plugin that you wish to use with `kubectl` always comes first in your PATH. For example, if we wanted to always use `/usr/local/bin/moreplugins/kubectl-foo` anytime that the `kubectl` command `kubectl foo` was invoked, we would simply change the value of our PATH to be `PATH=/usr/local/bin/moreplugins:/usr/local/bin/plugins`.
+A way to resolve this issue is to ensure that the location of the plugin that you wish to use with `kubectl` always comes first in your `PATH`. For example, if you want to always use `/usr/local/bin/moreplugins/kubectl-foo` anytime that the `kubectl` command `kubectl foo` was invoked, change the value of your `PATH` to be `/usr/local/bin/moreplugins:/usr/local/bin/plugins`.
 
 #### Invocation of the longest executable filename
 
-There is another kind of overshadowing that can occur with plugin filenames. Given two plugins present in a user's PATH `kubectl-foo-bar` and `kubectl-foo-bar-baz`, the `kubectl` plugin mechanism will always choose the longest possible plugin name for a given user command. Some examples below, clarify this further:
+There is another kind of overshadowing that can occur with plugin filenames. Given two plugins present in a user's `PATH`: `kubectl-foo-bar` and `kubectl-foo-bar-baz`, the `kubectl` plugin mechanism will always choose the longest possible plugin name for a given user command. Some examples below, clarify this further:
 
 ```bash
 # for a given kubectl command, the plugin with the longest possible filename will always be preferred
 kubectl foo bar baz
 ```
+
 ```
 Plugin kubectl-foo-bar-baz is executed
 ```
 
 ```bash
 kubectl foo bar
 ```
+
 ```
 Plugin kubectl-foo-bar is executed
 ```
 
 ```bash
 kubectl foo bar baz buz
 ```
+
 ```
 Plugin kubectl-foo-bar-baz is executed, with "buz" as its first argument
 ```
 
 ```bash
 kubectl foo bar buz
 ```
+
 ```
 Plugin kubectl-foo-bar is executed, with "buz" as its first argument
 ```
@@ -289,6 +301,7 @@ This design choice ensures that plugin sub-commands can be implemented across mu
 ```bash
 ls ./plugin_command_tree
 ```
+
 ```
 kubectl-parent
 kubectl-parent-subcommand
@@ -302,6 +315,7 @@ You can use the aforementioned `kubectl plugin list` command to ensure that your
 ```bash
 kubectl plugin list
 ```
+
 ```
 The following kubectl-compatible plugins are available:
 
@@ -316,41 +330,60 @@ error: 2 plugin warnings were found
 
 ### Using the command line runtime package
 
-As part of the plugin mechanism update in the v1.12.0 release, an additional set of utilities have been made available to plugin authors. These utilities
-exist under the [k8s.io/cli-runtime](https://github.com/kubernetes/cli-runtime) repository, and can be used by plugins written in Go to parse and update
-a user's KUBECONFIG file, obtain REST clients to talk to the API server, and automatically bind flags associated with configuration and printing.
+If you're writing a plugin for kubectl and you're using Go, you can make use
+of the
+[cli-runtime](https://github.com/kubernetes/cli-runtime) utility libraries.
 
-Plugins *do not* have to be written in Go in order to be recognized as valid plugins by `kubectl`, but they do have to use Go in order to take advantage of
-the tools and utilities in the CLI Runtime repository.
+These libraries provide helpers for parsing or updating a user's
+[kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
+file, for making REST-style requests to the API server, or to bind flags
+associated with configuration and printing.
 
-See the [Sample CLI Plugin](https://github.com/kubernetes/sample-cli-plugin) for an example usage of the tools provided in the CLI Runtime repo.
+See the [Sample CLI Plugin](https://github.com/kubernetes/sample-cli-plugin) for
+an example usage of the tools provided in the CLI Runtime repo.
 
 ## Distributing kubectl plugins
 
 If you have developed a plugin for others to use, you should consider how you
 package it, distribute it and deliver updates to your users.
 
-[Krew](https://sigs.k8s.io/krew) project offers a cross-platform way to package
-and distribute your plugins. This way, you use a single packaging format for all
+### Krew {#distributing-krew}
+
+[Krew](https://krew.dev/) offers a cross-platform way to package and
+distribute your plugins. This way, you use a single packaging format for all
 target platforms (Linux, Windows, macOS etc) and deliver updates to your users.
-Since Krew also maintains a [plugin
-index](https://github.com/kubernetes-sigs/krew-index), others can discover your
-plugin and install it. Read the [Krew developer
-guide](https://github.com/kubernetes-sigs/krew/blob/master/docs/DEVELOPER_GUIDE.md)
-to learn how to package kubectl plugins for Krew.
+Krew also maintains a [plugin
+index](https://index.krew.dev/) so that other people can
+discover your plugin and install it.
+
+
+### Native / platform specific package management {#distributing-native}
 
 Alternatively, you can use traditional package managers such as, `apt` or `yum`
-on Linux, Chocolatey on Windows, Homebrew on macOS, since kubectl plugins are
-just executables placed somewhere in client's PATH. This comes with the burden
-of updating your kubectl plugin’s distribution package in multiple platforms
-when you release a newer version.
+on Linux, Chocolatey on Windows, and Homebrew on macOS. Any package
+manager will be suitable if it can place new executables placed somewhere
+in the user's `PATH`.
+As a plugin author, if you pick this option then you also have the burden
+of updating your kubectl plugin’s distribution package across multiple
+platforms for each release.
+
+### Source code {#distributing-source-code}
+
+You can publish the source code; for example, as a Git repository. If you
+choose this option, someone who wants to use that plugin must fetch the code,
+set up a build environment (if it needs compiling), and deploy the plugin.
+If you also make compiled packages available, or use Krew, that will make
+installs easier.
 
 {{% /capture %}}
 
 {{% capture whatsnext %}}
 
-* Install [Krew – kubectl plugin manager](https://sigs.k8s.io/krew) to discover and install plugins.
-* Check the Sample CLI Plugin repository for [a detailed example](https://github.com/kubernetes/sample-cli-plugin) of a plugin written in Go.
-* In case of any questions, feel free to reach out to the [CLI SIG team](https://github.com/kubernetes/community/tree/master/sig-cli).
+* Check the Sample CLI Plugin repository for a
+  [detailed example](https://github.com/kubernetes/sample-cli-plugin) of a
+  plugin written in Go.
+  In case of any questions, feel free to reach out to the
+  [SIG CLI team](https://github.com/kubernetes/community/tree/master/sig-cli).
+* Read about [Krew](https://krew.dev/), a package manager for kubectl plugins.
 
 {{% /capture %}}