Add kubectl create [SUBCOMMAND] pattern #16028

derekwaynecarr · 2015-10-21T14:47:31Z

UPDATED TO ALIGN WITH CURRENT PR STATUS

The PR now supports the following:

Create

Create a resource by filename or stdin.

JSON and YAML formats are accepted.

Usage:
  kubectl create -f FILENAME [flags]
  kubectl create [command]

Examples:
# Create a pod using the data in pod.json.
$ kubectl create -f ./pod.json

# Create a pod based on the JSON passed into stdin.
$ cat pod.json | kubectl create -f -

Available Commands:
  namespace   Create a namespace with the specified name.
  secret      Create a secret using specified subcommand.

Create namespace

Create a namespace with the specified name.

Usage:
  kubectl create namespace NAME [--dry-run] [flags]

Aliases:
  namespace, ns


Examples:
  # Create a new namespace named my-namespace
  $ kubectl create namespace my-namespace

Create secret

Create a secret using specified subcommand.

Usage:
  kubectl create secret [flags]
  kubectl create secret [command]

Available Commands:
  docker-registry Create a secret for use with a Docker registry.
  generic         Create a secret from a local file, directory or literal value.

Create a secret that is generic

Create a secret based on a file, directory, or specified literal value

A single secret may package one or more key/value pairs.

When creating a secret based on a file, the key will default to the basename of the file, and the value will
default to the file content.  If the basename is an invalid key, you may specify an alternate key.

When creating a secret based on a directory, each file whose basename is a valid key in the directory will be
packaged into the secret.  Any directory entries except regular files are ignored (e.g. subdirectories,
symlinks, devices, pipes, etc).

Usage:
  kubectl create secret generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run] [flags]

Examples:
  # Create a new secret named my-secret with keys for each file in folder bar
  $ kubectl create secret generic my-secret --from-file=path/to/bar

  # Create a new secret named my-secret with specified keys instead of names on disk
  $ kubectl create secret generic my-secret --from-file=ssh-privatekey=~/.ssh/id_rsa --from-file=ssh-publickey=~/.ssh/id_rsa.pub

  # Create a new secret named my-secret with key1=supersecret and key2=topsecret
  $ kubectl create secret generic my-secret --from-literal=key1=supersecret --from-literal=key2=topsecret

Create secret for use with docker registry

Create a new secret for use with Docker registries.

Dockercfg secrets are used to authenticate against Docker registries.

When using the Docker command line to push images, you can authenticate to a given registry by running
  'docker login DOCKER_REGISTRY_SERVER --username=DOCKER_USER --password=DOCKER_PASSWORD --email=DOCKER_EMAIL'.
That produces a ~/.dockercfg file that is used by subsequent 'docker push' and 'docker pull' commands to
authenticate to the registry.

When creating applications, you may have a Docker registry that requires authentication.  In order for the
nodes to pull images on your behalf, they have to have the credentials.  You can provide this information
by creating a dockercfg secret and attaching it to your service account.

Usage:
  kubectl create secret docker-registry NAME --docker-username=user --docker-password=password --docker-email=email [--docker-server=string] [--from-literal=key1=value1] [--dry-run=bool] [flags]

Examples:
  # If you don't already have a .dockercfg file, you can create a dockercfg secret directly by using:
  $ kubectl create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL

EDITED: To reflect latest state of commit as of 12/14/15

k8s-github-robot · 2015-10-21T14:53:53Z

Labelling this PR as size/XXL

pmorie · 2015-10-21T14:55:12Z

So make is a top-level aggregator for macros, right? With special cases for things like run that don't sound good or make sense to group there?

derekwaynecarr · 2015-10-21T14:57:51Z

@pmorie - yes, make is a macro top-level container for porcelain commands we end up needing. we could argue that expose should become make service --from but I am not making that argument in this PR. I do think this is more natural to read, and make is a sensible top-level command for other macros persistent-volume, node, daemon-set, etc in the future.

run is an obvious meet the user where they are coming from scenario when they are familiar with docker run so I am not in favor of moving that - so its an obvious special case.

pmorie · 2015-10-21T15:00:10Z

I do think this is more natural to read, and make is a sensible top-level command for other macros persistent-volume, node, daemon-set, etc in the future.

+1 to that

k8s-bot · 2015-10-21T15:12:39Z

GCE e2e test build/test passed for commit 9e089f96593cdd3e4a3c773ef29ce60b71ddb315.

bgrant0607 · 2015-10-21T17:02:26Z

I prefer this pattern. It does read better and is more in line with our other commands. When I suggested using secret in #4822, it was as a verb, not as a concept area.

kubectl create -f ... to create from file
kubectl new resource to create from a template
kubectl make resource ... to create from resource-specific flags

Where there are more familiar verbs (run, expose, autoscale), we should keep them, especially where, as with run, they don't create resources of just a single type.

bgrant0607 · 2015-10-21T17:03:28Z

This is also similar to what I proposed here:
#4822 (comment)

derekwaynecarr · 2015-10-21T17:45:10Z

@bgrant0607 - ack, will pursue completing this PR, add tests, etc.

smarterclayton · 2015-10-21T20:24:49Z

Wow, 3 verbs just to create something. That won't confuse users at all

smarterclayton · 2015-10-21T20:25:29Z

How do I create something that is an aggregate of multiple types of things? I.e. a generator that creates several things?

smarterclayton · 2015-10-21T20:27:48Z

I must be missing the distinction between new and make. Is it about input or output? I'm going to want to look at the output of new and make as YAML (without creating on the server a lot), so I don't think the fact that new is about an editor makes sense. I'd rather have -o editor. And what sort of templates are new?

derekwaynecarr · 2015-10-21T20:44:39Z

@smarterclayton - I am going to abstain from noun-verb / verb-verb discussions.

In OpenShift alone, we have 4 different commands to create a secret depending upon the type of secret as a result of wanting to scope flag proliferation. Trying to do it all in new seems like the worst possible scenario for flag proliferation issues. So it seems at a given, there are some resource types that have common enough usage scenarios for 4 different variations of porcelain commands where new alone will not help solve all possible scenarios.

If you want to blend new and make, then the challenge is cobra I think, or I could just be ignorant here. arg[0] has completely different semantics between TYPE and subcommand. I also don't think you would advocate for each new to take the same set of global flags.

kubectl new replication-controller --name=foo --capacity=... makes no sense.
kubectl make persistent-volume foo --capacity=... does.

I agree that kubectl make [SUBCOMMAND] --editor=true is a nice semantic to take the output of the porcelain command as input to the editor is a nice to do in the future.

I think describing make as macro based and new as template based is sensible enough to me.

I am tired of going back and forth.

/cc @DirectXMan12

derekwaynecarr · 2015-10-21T21:14:01Z

As alternative based on in-person discussions with @smarterclayton , I am fine with:

kubectl create -f foo.yaml
kubectl create namespace foo
kubectl create secret foo --from-literal=key1=value1
kubectl create secret-dockercfg foo --docker-server=foo
kubectl create quota my-quota --hard=cpu=4,memory=4Mi,pods=10
kubectl create config foo --from-literal=key1=value1
kubectl create persistent-volume foo --capacity=size=X,iops=y
kubectl create limits my-limit --min=cpu=100m --max=cpu=1

So basically, macros become sub-commands of create which would work since create takes no args.

Wait for closure before proceeding.

UPDATED with macro examples for many other objects

smarterclayton · 2015-10-21T21:21:48Z

Some discussions with Derek. There are several ways to create things

Generators (complex input, specialized use case with help, or output that varies based on input significantly)
- run
```
kubectl run <name> <image> [ ... lots of args ] -- <command>
```
- expose
- podex
- openshift new-app (create apps from source)
```
oc new-app php https://github.com/somerepo/myapp.git
```
- openshift new-build (create builds based on source)
- create from template (parameterize with arguments and then send)
Complex use case driven
- Add a persistent volume to a deployment by creating or binding a PVC, identifying the volume name, and identifying where to mount in the container
```
oc volume deployment/foo --add --claim-size=10G --mount-path=/var/lib/mysql
```
Creating API objects from simple inputs
- secrets, config (from files or args, many different types)
```
kubectl make|create dockercfg-secret <file>
```
- volumes, nodes, limits, quotas, networks, pvcs, possibly services in the future
Totally generic
- Create
```
kubectl create -f <JSON>
```
- Apply
- The proposed new command straddles this category and the one above

A new user, coming to Kube or OpenShift, opens the CLI and tries to find the familiar command that begins their path. If they haven't gotten a hint ahead of time (run or new-app), they'll probably likely gravitate to something like create. Create is not a novice end-user concept. It is a high skill concept. New is not much better. The ideal case for most new Kube users is "run", and for OpenShift is "new-app". We'll probably need to change "new-app" to something in the future, but it represents our introduction verb (go from source to production).

I'd rather not have both "create" and "make", because the distinction between them is arbitrary and will distract users. Create is the lowest verb, but Make is only slightly above it.

smarterclayton · 2015-10-21T21:24:56Z

Edited comment

thockin · 2015-10-22T00:21:53Z

I am eager to use this, whether we go with 'create' or 'make' or 'new' (I don't know what new does).

I think new users or relative novices will often think "what was that command again..." and run kubectl -?. If that spits out 3 lines (create, make, new) the user will want to blow their brains out. That makes me agree with the latest proposal - create as the one true way.

Can we fold new into this? kubectl create --edit namespace = take all the defaults for flags and pop open $EDITOR.

@ghodss because of historical interest :)

thockin · 2015-10-22T00:24:12Z

Also, do we have precedent for --foo=key=value vs --foo=key:value - I find the latter more readable (and is closer to docker FWIW).

derekwaynecarr · 2015-10-22T00:50:05Z

@thockin we have precedent for key=value syntax for kubectl run

derekwaynecarr · 2015-10-22T00:54:04Z

If @bgrant0607 acks with an ok that resource macros become subcommand of create , I will finish this up tomorrow and do the initial implement of secret and namespace and move on :-)

smarterclayton · 2015-10-22T02:39:18Z

Or "-o editor"

On Oct 21, 2015, at 8:22 PM, Tim Hockin notifications@github.com wrote:

I am eager to use this, whether we go with 'create' or 'make' or 'new' (I
don't know what new does).

I think new users or relative novices will often think "what was that
command again..." and run kubectl -?. If that spits out 3 lines (create,
make, new) the user will want to blow their brains out. That makes me agree
with the latest proposal - create as the one true way.

Can we fold new into this? kubectl create --edit namespace = take all the
defaults for flags and pop open $EDITOR.

@ghodss https://github.com/ghodss because of historical interest :)

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

pmorie · 2015-10-22T02:44:27Z

I think new users or relative novices will often think "what was that command again..." and run kubectl -?. If that spits out 3 lines (create, make, new) the user will want to blow their brains out.

I literally lol'd reading this. +1

bgrant0607 · 2015-10-22T02:46:13Z

cc @janetkuo

bgrant0607 · 2015-10-22T02:51:43Z

Regardless what we do, we're going to need good documentation, with examples.

I'm fine with adding sub-behaviors to create.

I'd rather use --edit than -o editor.

The main difference, though, for new was the input. So, we'd need something like --from-template or --from-example.

Still catching up on the other comments.

bgrant0607 · 2015-10-22T02:52:48Z

Aggregate of multiple things, like run: custom command. Don't use resource-specific commands like create/make/new/whatever.

bgrant0607 · 2015-10-22T03:04:28Z

We should try to make all variants of currently accepted resource names (e.g., svc) work as subcommands, and not introduce new ones (e.g., persistent-volume) if we follow that approach.

derekwaynecarr · 2015-12-14T15:28:58Z

@deads2k - still wrapping up the test-cmd.sh changes, but take a look.

deads2k · 2015-12-14T15:48:31Z

pkg/kubectl/cmd/create.go

+		return f.PrintObject(cmd, obj, out)
+	}
+
+	useShortOutput := options.OutputFormat == "name"


This is always false because you checked for "" above, right?

k8s-bot · 2015-12-14T16:45:48Z

GCE e2e test build/test passed for commit cab6a17f2acbbffe275b7263fadc67247175920b.

derekwaynecarr · 2015-12-14T17:51:58Z

@deads2k - here is the issue for evaluating support of a --confirm flag: #18663

Updates made to hack/test-cmd.sh, I had to fall back to grep (similar to pod templates test) because my go-template-fu was not working nicely with the secret data map with multiple keys; PTAL

deads2k · 2015-12-14T17:57:06Z

hack/test-cmd.sh

+  # Pre-condition: only the "default" namespace exists
+  kube::test::get_object_assert 'namespaces' "{{range.items}}{{$id_field}}:{{end}}" 'default:'
+  # Command
+  kubectl create namespace other


I'd choose a different name, since the next test is expecting that namespace "other" doesn't exist.

deads2k · 2015-12-14T18:00:32Z

a couple comments on test-cmd, then this #16028 (comment) and I think its good.

k8s-bot · 2015-12-14T18:24:14Z

GCE e2e test build/test passed for commit 2bc3a5e0414db3531971780dba3ecc7cc7ada2a1.

k8s-bot · 2015-12-14T18:31:57Z

GCE e2e test build/test passed for commit c438594a3e593907f1ae896639e483004e6e0a1a.

derekwaynecarr · 2015-12-14T18:44:07Z

@deads2k - last two updates addressed, PTAL

deads2k · 2015-12-14T18:54:33Z

lgtm

k8s-bot · 2015-12-14T19:20:22Z

GCE e2e test build/test passed for commit 5e09485.

derekwaynecarr · 2015-12-14T19:25:16Z

@k8s-bot - test this

ncdc · 2015-12-16T15:24:49Z

@k8s-bot unit test this

k8s-github-robot · 2015-12-16T16:01:14Z

@k8s-bot test this [submit-queue is verifying that this PR is safe to merge]

k8s-bot · 2015-12-16T16:41:37Z

GCE e2e test build/test passed for commit 5e09485.

k8s-github-robot · 2015-12-16T16:41:59Z

Automatic merge from submit-queue

Auto commit by PR queue bot

googlebot added the cla: yes label Oct 21, 2015

k8s-github-robot assigned deads2k Oct 21, 2015

k8s-github-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 21, 2015

derekwaynecarr mentioned this pull request Oct 21, 2015

WIP: improve experience to make secrets #16027

Closed

bgrant0607 mentioned this pull request Oct 22, 2015

[WIP] Introduce the 'new' Command #14294

Closed

deads2k reviewed Dec 14, 2015
View reviewed changes

derekwaynecarr force-pushed the make_cmd branch from cab6a17 to 2bc3a5e Compare December 14, 2015 17:43

derekwaynecarr force-pushed the make_cmd branch from 2bc3a5e to c438594 Compare December 14, 2015 17:54

deads2k reviewed Dec 14, 2015
View reviewed changes

Add kubectl create [SUBCOMMAND] pattern

5e09485

derekwaynecarr force-pushed the make_cmd branch from c438594 to 5e09485 Compare December 14, 2015 18:43

deads2k added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Dec 14, 2015

k8s-github-robot pushed a commit that referenced this pull request Dec 16, 2015

Merge pull request #16028 from derekwaynecarr/make_cmd

5a579a2

Auto commit by PR queue bot

k8s-github-robot merged commit 5a579a2 into kubernetes:master Dec 16, 2015

erictune mentioned this pull request Dec 18, 2015

Update secret docs to use kubectl create secret #18912

Closed

0xmichalis mentioned this pull request Jan 15, 2016

Add a kubectl 'import' command for imported services #19509

Closed

bgrant0607 mentioned this pull request Jan 17, 2016

Simplified resource generation (was kubectl command to create a namespace) #10495

Closed

liggitt mentioned this pull request Feb 5, 2017

kubectl run supports more options for deployment than kubectl create deployment #40961

Closed

Add kubectl create [SUBCOMMAND] pattern #16028

Add kubectl create [SUBCOMMAND] pattern #16028

Conversation

derekwaynecarr commented Oct 21, 2015

k8s-github-robot commented Oct 21, 2015

pmorie commented Oct 21, 2015

derekwaynecarr commented Oct 21, 2015

pmorie commented Oct 21, 2015

k8s-bot commented Oct 21, 2015

bgrant0607 commented Oct 21, 2015

bgrant0607 commented Oct 21, 2015

derekwaynecarr commented Oct 21, 2015

smarterclayton commented Oct 21, 2015

smarterclayton commented Oct 21, 2015

smarterclayton commented Oct 21, 2015

derekwaynecarr commented Oct 21, 2015

derekwaynecarr commented Oct 21, 2015

smarterclayton commented Oct 21, 2015

smarterclayton commented Oct 21, 2015

thockin commented Oct 22, 2015

thockin commented Oct 22, 2015

derekwaynecarr commented Oct 22, 2015

derekwaynecarr commented Oct 22, 2015

smarterclayton commented Oct 22, 2015

pmorie commented Oct 22, 2015

bgrant0607 commented Oct 22, 2015

bgrant0607 commented Oct 22, 2015

bgrant0607 commented Oct 22, 2015

bgrant0607 commented Oct 22, 2015

derekwaynecarr commented Dec 14, 2015

deads2k Dec 14, 2015

Choose a reason for hiding this comment

k8s-bot commented Dec 14, 2015

derekwaynecarr commented Dec 14, 2015

deads2k Dec 14, 2015

Choose a reason for hiding this comment

deads2k commented Dec 14, 2015

k8s-bot commented Dec 14, 2015

k8s-bot commented Dec 14, 2015

derekwaynecarr commented Dec 14, 2015

deads2k commented Dec 14, 2015

k8s-bot commented Dec 14, 2015

derekwaynecarr commented Dec 14, 2015

ncdc commented Dec 16, 2015

k8s-github-robot commented Dec 16, 2015

k8s-bot commented Dec 16, 2015

k8s-github-robot commented Dec 16, 2015