Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Proposal for new kubecfg design (kubectl) #1325
_UPDATE: This proposal was reworked many times throughout this PR. I am keeping this parent message the same for historical purposes, but you can find the closest description of the final design in this comment (with the exception that
The intent of this pull request is to propose a design for the present and future of kubecfg. The conversation from #1167 was the primary input into this design. The idea is to have kubecfg solve two use cases:
The problem with the current design is that it is too generic to effectively support (1). The proposed redesign enables custom commands per resource (e.g. kubecfg pods, kubecfg services, etc.) but generic subcommands to satisfy (2) (kubecfg submit, kubecfg diff, kubecfg reconcile, etc.).
Proposed set of subcommands
Only a subset of these have been implemented in the attached commit.
Here is what the current commit produces:
These examples are out of date - see this comment for the latest.
I like your idea that
Wondering if you had thoughts on how submit might interact with version control.
And, if there is parameterization of config, as Joe suggested, does parameter substitution happen before commit or before pushing to k8s?
Not stuff that this PR needs to address, but would welcome your thoughts.
I am aiming towards having all the output of the resource commands be parseable in the sed/awk style, e.g. with consistent and parseable whitespace, but in general I believe the kubecfg resource commands (
I think today kubecfg can parse and export both JSON and YAML, so I'd be fine to keep that. Did you mean something else?
I think we can make it really flexible - you can use one file, many files, recursive directories, do selective updates, etc. Mostly will come down to which style we want to prioritize implementing first.
Glad to see that I'm heading in the right direction!
Probably the latter. If anything looks off or doesn't make sense I would expect the user to just run the command again, just as if they were navigating around the REST API.
I think we could support many different workflows. Some people may prefer to have a git repo with all their config and have a git hook on receive which runs kubecfg automatically to synchronize the config state with the cluster. Other people may prefer to run all the synchronizing commands manually but keep a record of all changes in a repo somewhere. I think that if we provide the primitive of "take this file and sync it up with the cluster," people can create their own ways of using it that fit them best. For parameter substitution, we can see what needs there are for templating and see if that's best done in kubecfg or directly in the REST API itself.
wrt machine readable output: while it is possible to hit the k8s API directly from curl, I'd still recommend we (probably via an option) provide easily parseable output:
We can add it later, of course, but I'd love to keep the awk/sed/grep/cut to a minimum.
I'll make comments on the text before I go look at code.
On Mon, Sep 15, 2014 at 5:48 PM, Sam Ghods email@example.com wrote:
For concrete example, assume 3 output modes: table, key-value, json"
$ clitool -t something
$ clitool -k something
$ clitool -j something
Internally the data can all be stored as key-value, but the varying output
What about a generic "select" operation that evaluates a selector? Like:
$ kubecfg -k pods select "user in (thockin)"
This pattern could apply to all REST resource types.
What about creating and updating a service?
kubecfg -a="/tmp/foo" pods list -l "foo in (bar)" or do flags have to come
referenced this pull request
Sep 17, 2014
A lot of really good points have been brought up in this thread. I want to specifically try and resolve one of them: how kubecfg reconciles with the REST data model.
(I am only talking about read operations here (like listing, querying and filtering), not updating config - I think config updates and diffs should match 1:1 with the REST API data model.)
If I try and look at the raw JSON dump of a Pod (using the latest v1beta3 spec), I get something like this:
OTOH, if I wanted to do something focused on an easy-to-read output for
Basically, to increase readability and usability, I’m doing a number of things to the original parameters:
But all told, what I’m really doing is creating a new Pod data model, which we can call KubecfgPod for convenience, that has all this information in a more user-friendly format.
Now, if all I’m doing is printing this out, this is fine. I could print out the above in the key-value textual output I have above, or I can print it in YAML or JSON, no big deal.
But if I want kubecfg to become more advanced with querying and filtering (as has been mentioned by @thockin, @bgrant0607 and @smarterclayton) or even more tightly integrated into config, this becomes problematic. What should people refer to, KubecfgPod fields or Pod fields? If they refer to KubecfgPod fields, we would have to publish it and evolve it side by side with Pod fields, and force people to potentially learn two conflicting models, making config management confusing. If we go with Pod fields, then what they see printed out and how they are querying are at odds.
The question is, how do we reconcile ease of use with the kubecfg tool compared to what the API is actually outputting and how config is structured?
Ease of use is choosing the 5 or 6 most important fields and showing those.
You can't be full featured and easy to use.
On Thu, Sep 18, 2014 at 7:00 PM, Sam Ghods firstname.lastname@example.org wrote:
referenced this pull request
Sep 19, 2014
@ghodss This is a very nice proposal and thread. In OpenShift we are in the process of writing the very first skeleton proposals for our end-user CLI and we would like to stay in conformance with the design and technology choices of
We are also considering codegangsta/cli for cleaner command definitions, specifically the clear separation of arguments and flags, default values and so on. It does appear to support global flags through
One feature I didn't find in any of them is flags that accept a list of predefined values, for example something like:
For terminal colors I'm considering fatih/color which allows you to integrate nicely with
From @thockin's comments, the idea of output formats looks really powerful specially for scripting.
I thought about --master but I don't know if that's the right word for an end user command. --server seems more appropriate to me.
----- Original Message -----
I anticipate I may have missed something in how to package a brand new binary (kubectl), so I would appreciate comments on that. But otherwise this should be pretty close to merge.