For example, the webservice script does some useful stuff. But, it wasn't clear exactly what it was doing, i.e. there was a lot of magic happening. While the magic is certainly an integral part of hiding the low-level details, it also obfuscates things. Reading the webservice script wasn't much help; it's long and complicated, and mixes grid and k8s functionality in a way that further hides what's actually going on.
Anyway, all I'm really asking is that as the docs get written for the "friendly command line interface", you also include some explanation of what's happening behind the scenes. For example, maybe have a --verbose option to all the tools which makes it print all the back end commands it's executing, so
webservice --backend=kubernetes python3.7 restart
might print:
kubectl exec -i -tshell-1645020371 --container main-app -- /bin/bash
And then somebody who already understands kubectl would instantly understand what's happening. It's not hard to guess the basic gist of what it must be doing, but having the details confessed eliminates any doubt, enhancing comprehension.
As another example, it took me a little bit to figure out that the "become" command doesn't do anything more magic than run sudo with a little sanity checking wrapped around it. Fortunately, that script is simple enough that once I looked at it, it was obvious what it was doing. But other parts of the "friendly command line interface" are rather more opaque.
One of the most prominent missing features on Kubernetes was a friendly
command line interface to schedule jobs (like jsub). We've been working
on that, and have a beta-level interface that you can try today: the
Toolforge jobs framework [4].