kubernetes: Behavior of commands with respect to errors and printing usage is inconsistent and reduces usability

The majority of kube binaries print usage when certain invalid arguments are presented. Unfortunately, most of our binaries have > 2 pages of usage output, and the result of printing that is a very confusing and context disrupting action.

In general, CLI commands try to minimize their output - for example:

$ grep --blarg
grep: unrecognized option `--blarg'
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
	[-e pattern] [-f file] [--binary-files=value] [--color=when]
	[--context[=num]] [--directories=action] [--label] [--line-buffered]
	[--null] [pattern] [file ...]

ls --foo
ls: illegal option -- -
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

both print their minimal sets. Obviously, as commands grow the number of flags some of the short options become a bit silly (yes, congratulations, you have the entire alphabet of flags) and convey less useful information to a user.

When errors are printed we also end up printing the error both above and below the command (in at least kubectl, kubelet, kube-apiserver, and controller-manager). I’m not even sure this was intentional, but coincidentally we print the errors twice and so it’s both before and after the usage.

Error feedback needs to minimize the amount of extraneous information presented to users for maximum clarity. Three are broadly four classes of help and error output:

1. A user explicitly requests help via --help or -h
2. A user provides an input that is not recognized (flag, command, or argument) and we can unambiguously know provided invalid input. User needs to change the input.
3. The user provides inputs that don’t work well together or have conflicting meaning. User needs to change the input.
4. The user provided inputs that result in a runtime error, but that error can’t be resolved by changing the input of the command.

Recommended changes:

1. Since our command and flag sets are so long, I don’t think there is value in printing the full usage info in 2 and 3. Instead, I think we should print a minimal “usage: Run “command foo --help” to see usage info” message after printing the error.
2. We should stop printing error output twice (once as Error: and once as error: ) in 2-4 and print as error: or Error: (the former is more consistent with Posix guidelines).
3. We still need to clean up output.