We should do this eventually, but for now we have a bunch of examples and
other dependencies.

We should start by adding a deprecated print out on startup, and then
remove after a suitable period (3 months?)

Brendan
On Nov 3, 2014 5:11 PM, "Daniel Smith" notifications@github.com wrote:

Do we have plans to keep both kubectl and kubecfg? If so, why? If not,
what are we waiting for to get rid of kubecfg?

There's a lot of duplicated code between them. Also, it's annoying to have
to fix two clients.

—
Reply to this email directly or view it on GitHub
#2144.

@lavalamp We're waiting for replacements for all of the things that kubecfg currently does. Once we do, then we can fix examples, docs, etc.

/cc @smarterclayton @ghodss

Do we have a list of the things we're waiting for?

Also, if I add an event search function only to kubectl and not kubecfg, will that rustle anyone's jimmies?

@lavalamp Re. event search: I'm fine with that going into kubectl only.

Functionality we're waiting for is higher-level orchestration related to replication controllers:

• Stop replacement. Consistently support graceful and immediate termination for all objects #1535. This one is a PITA. One has to do something like cluster/kubectl.sh get pods --no-headers | cut -d " " -f 1 | xargs -n 1 cluster/kubectl.sh delete pod
• Run replacement. Please review Config generator suite #1980.
• Resize replacement. Update w/ merge functionality described Kubectl can apply config files in bulk #1905 (comment) and a resize verb Proposal: scaling interface #1629.
• Rolling update replacement. Robust rollingupdate and rollback #1353.

Potentially reopening worm can; I went back and read the discussion in #1325, but I still can't shake that we are losing important functionality by completely removing the high-level controller commands from kubectl.

What are the reasons for us to not support 'run', 'resize', 'stop', and 'rollingupdate' in kubectl? I understand for update and stop we want to push that functionality into the server, but that doesn't preclude supporting it client side for now, and then removing or redirecting the client command to the API when it is added.

I don't think it's enough that we can use wrapper scripts/config generators/various composable pieces to achieve the same functionality. Providing a client that makes it simple and understandable to interact with Kubernetes at a higher level seems critical to a positive user experience, especially for new users. The 'run' command is a prime example of this. 'docker run' is simple enough for new users to instantly grok. Shouldn't 'kubectl run' be equally simple?

I want to re-add this functionality to kubectl (or some other binary).
Concretely, I think that the verbs should be:

run
connect
update
export
delete

A user should be able to construct their complete app from those verbs:

$kube run app # creates a
single pod
$kube run app2 --replicas 3 --connect app # creates a replica controller
for app2 and a service for app
$kube export app2 # creates a service
for app2 and externalizes it.
$kube update app2 --replicas 4 # resize app2

On Tue, Dec 9, 2014 at 1:03 PM, Jeff Lowdermilk notifications@github.com
wrote:

Potentially reopening worm can; I went back and read the discussion in
#1325 #1325, but
I still can't shake that we are losing important functionality by
completely removing the high-level controller commands from kubectl.

What are the reasons for us to not support 'run', 'resize', 'stop', and
'rollingupdate' in kubectl? I understand for update and stop we want to
push that functionality into the server, but that doesn't preclude
supporting it client side for now, and then removing or redirecting the
client command to the API when it is added.

I don't think it's enough that we can use wrapper scripts/config
generators/various composable pieces to achieve the same functionality.
Providing a client that makes it simple and understandable to interact with
Kubernetes at a higher level seems critical to a positive user experience,
especially for new users. The 'run' command is a prime example of this.
'docker run' is simple enough for new users to instantly grok. Shouldn't
'kubectl run' be equally simple?

—
Reply to this email directly or view it on GitHub
#2144 (comment)
.

@jlowdermilk This will definitely be part of the usability plan for 1.0. The contrib wrappers are not the long-term solution, but are proof-of-concept implementations, pending proper infrastructure in kubectl. Since kubecfg is still available, it hasn't been a high priority to hack these into kubectl. We've been waiting for at least proper support for bulk operations on lists of objects (#1905) and a better understanding of where we want to go with some of the operations (e.g., stop #1535, #2789).

@jlowdermilk @brendandburns run is just too ad hoc to include as a primitive, and I actually think it hurts us by hiding Kubernetes concepts and making its primitives look pointlessly complex. Unlike simplegen, the current kubecfg implementation is also neither transparent nor composable. We do need an easy kick-the-tires experience, but just porting the existing run implementation is not the way to get there.

@brendandburns I don't understand kube app2 --connect app. app2 is a client of app? Is this supposed to be like Docker's links?

connect and export would share the problem of run that it would be unclear how they map to Kubernetes primitives. I like the idea of creating a service that targets a pod or replication controller's pods, though. I could also imagine doing that for replication controller (and for pod templates, once they exist as distinct objects). I'd use some kind of flag on "create service" and "create rc" rather than a new verb.

We need the following:

• Pluggable config generators and transformations in kubectl, with commonly useful generators there by default
• Lots of flavors of updates: imperative updates (conceptually similar to PATCH) of specific fields (e.g., replicas, labels, annotations), forced whole-object updates, updates that merge config data and existing state, rolling updates (as per Robust rollingupdate and rollback #1353, not the way it's done in kubecfg), eventually first-class resize (Proposal: scaling interface #1629)
• A fairly general-purpose way to specify fields on the command line during creation and update, not just from a config file
• More intelligent defaulting of fields (e.g., container name should be optional in pod manifest #2643)
• Easy creation of new objects from existing ones (e.g., cloning pods, deriving pod templates from pods, creating services and replication controllers that target pods)
• Easy generation of clean configuration files from existing objects (including containers -- podex)
• Possibly better/shorter/clearer names for replicationController and service.

I think we absolutely want to have commands line "run" and "connect". I'd
be ok calling them "simple-run" or something like that. I think of these
commands as being examples or templates. As long as they are like that,
then we're being true to our API objects, but also providing an easier to
use, easier to understand interface.

kube run app2 --connect app

Says:

I want to run app2, it connects to app, so create a service if one doesn't
exist, and add labels to app2, indicating to UX etc. that app2 is connected
to app.

I feel pretty strongly that we need to provide an initial "kick the tires"
or "simplified" experience that has a low concept count and is easy to grok.

It should have a forward path into the API objects that is logical and
consistent, but I don't think we should be afraid of providing a "porcelin"
layer to go along with the API plumbing.

--brendan

On Tue, Dec 9, 2014 at 2:27 PM, bgrant0607 notifications@github.com wrote:

@jlowdermilk https://github.com/jlowdermilk This will definitely be
part of the usability plan for 1.0. The contrib wrappers are not the
long-term solution, but are proof-of-concept implementations, pending
proper infrastructure in kubectl. Since kubecfg is still available, it
hasn't been a high priority to hack these into kubectl. We've been waiting
for at least proper support for bulk operations on lists of objects (#1905
#1905) and a
better understanding of where we want to go with some of the operations
(e.g., stop #1535
#1535, #2789
#2789).

@jlowdermilk https://github.com/jlowdermilk @brendandburns
https://github.com/brendandburns run is just too ad hoc to include as a
primitive, and I actually think it hurts us by hiding Kubernetes concepts
and making its primitives look pointlessly complex. Unlike simplegen, the
current kubecfg implementation is also neither transparent nor composable.
We do need an easy kick-the-tires experience, but just porting the existing
run implementation is not the way to get there.

@brendandburns https://github.com/brendandburns I don't understand kube
app2 --connect app. app2 is a client of app? Is this supposed to be like
Docker's links?

connect and export would share the problem of run that it would be unclear
how they map to Kubernetes primitives. I like the idea of creating a
service that targets a pod or replication controller's pods, though. I
could also imagine doing that for replication controller (and for pod
templates, once they exist as distinct objects). I'd use some kind of flag
on "create service" and "create rc" rather than a new verb.

We need the following:

• Pluggable config generators and transformations in kubectl, with
  commonly useful generators there by default
• Lots of flavors of updates: imperative updates (conceptually similar
  to PATCH) of specific fields (e.g., replicas, labels, annotations), forced
  whole-object updates, updates that merge config data and existing state,
  rolling updates (as per Robust rollingupdate and rollback #1353
  Robust rollingupdate and rollback #1353, not
  the way it's done in kubecfg), eventually first-class resize (Proposal: scaling interface #1629
  Proposal: scaling interface #1629)
• A fairly general-purpose way to specify fields on the command line
  during creation and update, not just from a config file
• More intelligent defaulting of fields (e.g., container name should be optional in pod manifest #2643
  container name should be optional in pod manifest #2643)
• Easy creation of new objects from existing ones (e.g., cloning pods,
  deriving pod templates from pods, creating services and replication
  controllers that target pods)
• Easy generation of clean configuration files from existing objects
• Possibly better/shorter/clearer names for replicationController and
  service.

—
Reply to this email directly or view it on GitHub
#2144 (comment)
.

I'm happy with a few simple config generators being available by default, but they should be treated similarly to the API objects, with the same create/update/delete verbs.

I actually think there is even more potential to confuse if you do that.

If you use different verbs, then people will understand that they are
different from the base commands, but if I run "create" and there isn't a
corresponding API object that is created, I'm going to be super confused.

--brendan

On Tue, Dec 9, 2014 at 2:52 PM, bgrant0607 notifications@github.com wrote:

I'm happy with a few simple config generators being available by default,
but they should be treated similarly to the API objects, with the same
create/update/delete verbs.

—
Reply to this email directly or view it on GitHub
#2144 (comment)
.

I'm also fine with creating "macro objects" in the API (not just in the client) that cause multiple lower-level primitives to be generated. "Forever pod" falls into this category. That would be another way to support run-like functionality.

If we want to represent dependencies, for deployment sequencing or even just for UI purposes, we'll need a declarative way to represent/generate them, also.

@brendandburns That's an issue for any kind of declarative configuration generation. Yes, we need to clarify the distinction, but the answer isn't a custom verb for each generator.

There are some custom verbs that are more intuitive and important than
others. I think that you need a small set of first order custom verbs that
exist at a level above the raw declarative template generation stuff.

It's a sacrifice of principle to ensure easy usability.

--brendan

On Tue, Dec 9, 2014 at 3:08 PM, bgrant0607 notifications@github.com wrote:

@brendandburns https://github.com/brendandburns That's an issue for any
kind of declarative configuration generation. Yes, we need to clarify the
distinction, but the answer isn't a custom verb for each generator.

—
Reply to this email directly or view it on GitHub
#2144 (comment)
.

Since kubecfg is still available, it hasn't been a high priority to hack these into kubectl. We've been waiting for at least proper support for bulk operations on lists of objects (#1905) and a better understanding of where we want to go with some of the operations (e.g., stop #1535, #2789).

It is precisely this chicken-and-egg problem that is preventing us from deprecating kubecfg. My motivation for having at least a basic implementation of these commands in kubectl is to unblock said deprecation, to prevent us having to maintain both clients for the next few months.

run is just too ad hoc to include as a primitive, and I actually think it hurts us by hiding Kubernetes concepts and making its primitives look pointlessly complex.

I agree with Brendan here; we absolutely need a set of simple custom verbs for usability. But I don't think hiding Kubernetes concepts initially makes its primitives look pointlessly complex; I think it's a reasonable approach to give new users a simple verb and then later explain the underlying primitives that make it work. The converse is, if I as a new user have to read a page of documentation and grok the interaction of multiple underlying primitives before I can just "run my container in a cluster and keep it running", that is too high an entry cost, and I'm going to go use something simpler.

Before we add a lot more verbs to kubectl I'd want to prove them out individually and then have some deliberate discussion about it. We depend on kubectl and have a ton of verbs we've been considering as well - I'd want to add ours without stomping on upstream concepts, and make sure the verbs have a really concrete focus.

For us, the discussions have touched on:

• start (as in, trigger a new thing to be created and run based on a parent)
• run, as in docker exec on the cluster
• cancel, as in cancel a build
• new, as in generate an object from parameters
• change, as in alter certain attributes of an object based on parameters (change service foo --selector=labelquery)

Agree with Brendan you want some core verbs that build up to deeper experience.

On Dec 9, 2014, at 6:13 PM, Brendan Burns notifications@github.com wrote:

There are some custom verbs that are more intuitive and important than
others. I think that you need a small set of first order custom verbs that
exist at a level above the raw declarative template generation stuff.

It's a sacrifice of principle to ensure easy usability.

--brendan

On Tue, Dec 9, 2014 at 3:08 PM, bgrant0607 notifications@github.com wrote:

@brendandburns https://github.com/brendandburns That's an issue for any
kind of declarative configuration generation. Yes, we need to clarify the
distinction, but the answer isn't a custom verb for each generator.

—
Reply to this email directly or view it on GitHub
#2144 (comment)
.

—
Reply to this email directly or view it on GitHub.

@jlowdermilk It's not a chicken-and-egg problem. It just wasn't prioritized.

@smarterclayton Do you have any openshift docs/issues you could point to that would explain any of these verbs in more detail?

Yet another possible source of user confusion with our "run" is that it isn't compatible with docker run.

I'll work on requirements for a real run replacement (#1695), and a more complete proposal.

I've got a few. Note many of these are not truly generic, so I don't think they're in the same class as create/get/update/delete.

Overview diagram of most commands:

https://www.dropbox.com/s/jqpcpl1iccs4o0h/OpenShift%20CLI%20Org.png?dl=0

Start build command (resource specific transformation of template resource to instance resource): openshift/origin#492
Cancel build (sets a flag on the spec): openshift/origin#443

No issue/pull yet for "new-", but that might be the equiv of srvexpand or similar. "alter/config/change-" would take flags corresponding to their attributes.

None of these seemed to resolve to generic verbs, since each subtype will have different flags (new-build and new-app have few flags in common, start build and cancel build require specific attributes). They might be custom verbs, but I would prefer to find those after the system exists for a while and then roll them up (start/cancel might reflect jobs controller, or an equiv deployment). These are all more specific to use cases, rather than cross cutting.

I do want to keep kubectl slightly generic - perhaps more use case oriented flows should be clearly separated from the other commands. A lot of that can be done with clever help arrangement (see Git), but your core help page really needs to highlight 5-10 most important actions and then unfold to reveal more. We found in the past it was useful to make main help be "get started" commands and "maintain what you create" commands, with a deeper help for everything else.

On Dec 9, 2014, at 7:40 PM, bgrant0607 notifications@github.com wrote:

@smarterclayton Do you have any openshift docs/issues you could point to that would explain any of these verbs in more detail?

Yet another possible source of user confusion with our "run" is that it isn't compatible with docker run.

—
Reply to this email directly or view it on GitHub.

As for the cost of maintaining 2 CLIs: Think of kubecfg as the alpha/beta CLI and kubectl as the v1 release candidate CLI. This is no different than supporting v1beta1 while building and even after completing v1beta3. It's a consequence of wanting to not break existing users.

All the necessary functionality has been added to kubectl. Now we can complete the removal of kubecfg.

#1928 is subsumed by this bug.

I am trying to do a very important demo of Kubernetes using a tutorial on Google.com - but the issue is the tutorial uses the deprecated kubecfg.sh, and the instructions on the tutorial have not been updated to reflect the new kubectl.sh commands. Can someone please look at the below and advise the equivalent command line entries to do the same thing using kubectl.sh? Need help on this urgently please.

https://cloud.google.com/solutions/real-time/kubernetes-redis-bigquery

"list pods" -> "get pods"
" -f create " -> "create -f " (type automatically deduced)
"resize foo 0" -> "stop foo"
"delete pods/foo" -> "delete pod foo"

(All from memory and unchecked, YMMV)

I filed a bug report internally to get this page updated.

Awesome ! Thanks for the quick response :)

On Sunday, March 8, 2015, Daniel Smith notifications@github.com wrote:

"list pods" -> "get pods"
" -f create " -> "create -f " (type automatically deduced)
"resize foo 0" -> "stop foo"
"delete pods/foo" -> "delete pod foo"

(All from memory and unchecked, YMMV)

I filed a bug report internally to get this page updated.

—
Reply to this email directly or view it on GitHub
#2144 (comment)
.