Clarify plugin names in code and documentation

[timblaktu]

I originally installed kauthproxy manually (not using krew) by copying the binary from release 1.2.1 into /usr/local/bin/kubectl-auth-proxy, but when I then invoke kubectl auth-proxy -n kubernetes-dashboard https://kubernetes-dashboard.svc, I get:

warning: kubectl-auth-proxy overwrites existing command: "kubectl auth"

From the plugin docs I learned that the kubectl plugin mechanism just looks for binaries on path named kubectl-<plugin name> where the <plugin name> is identical to the kubectl subcommand. Also from the section on naming plugins I learned that there can be multiple subcommands in a kubectl call, with each permutation implemented by an individual plugin binary named following the convention kubectl-<subcommand 1>-<subcommand 2>-....

This explains my issue: because I named the binary kubectl-auth-proxy¹, using hyphens, kubectl expects this binary to implement the command kubectl auth proxy, and of course auth is a built-in subcommand.

So by simply renaming the plugin binary from kubectl-auth-proxy to kubectl-ap I was then able to work around the current issue and run the kubectl ap command without this warning occurring.

I see that krew install auth-proxy installs as the kubectl-auth_proxy binary, working around the issue.

I'd like to see the naming of things here get updated to not so confuse the next person that comes here wearing shoes like mine. At the very least I'd like to see the README get fixed to state the correct command for starting the proxy:

kubectl auth_proxy -n kubernetes-dashboard https://kubernetes-dashboard.svc

But I think some clarification about the 3 different names used throughout the project and why is warranted:

---

Explanation of Plugin Names

1. The repo/project is named kauthproxy, and is completely independent of the plugin name.
2. The name of the plugin in the krew index is auth-proxy, thus the instructions to kubectl krew install auth-proxy.
3. The installed plugin is named auth_proxy, corresponding to the installed binary kubectl-auth_proxy.

The naming discrepancy between 2. and 3. is required to prevent the plugin from masking the built-in auth kubectl sub-command. Although auth and auth-proxy are distinct strings, plugins which implement multiple kubectl subcommands are implemented by a binary expected to be named kubectl-<subcommand 1>-<subcommand 2>-..... Therefore, essentially, hyphens must be omitted from plugin names.

But IMO it's much better to just clean up the naming discrepancies in the code, in which case the documentation clarification is unnecesasry.

Footnotes

1. which I did because the command documented in the Run section of your README is wrong. ↩