Merge pull request #25130 from deads2k/create-guidelines

Automatic merge from submit-queue

create command guidance

`kubectl create <resource>` commands are multiplying (configmap, namespace, secret (2 flavors and a pull for a third), and serviceaccounts so far) and I think we should agree on the goal of those subcommands.

Right now, `kubectl run` is an easy entrypoint for new users or users who don't really care which resources are created.  It is possible to get stable output from `kubectl run`, but it really is intent-based: make this image go in some reasonable way.  At the other end of the spectrum, you can craft yaml files by hand get exactly the object you want, but that requires pretty deep API knowledge.  I think that `kubectl create <resource>` should be the starting point of the middle ground.

`kubectl create <resource>` commands should have just enough arguments to create valid objects and the expectation should be that users will use those objects as skeletons to tweak using `kubectl edit` or the future `kubectl set` to modify them after the fact.  Editing an already existing and valid object is a lot easier than creating one from scratch, so it reduces the barrier to entry.

@kubernetes/kubectl @smarterclayton @bgrant0607 @liggitt

docs/devel/kubectl-conventions.md

@@ -42,6 +42,7 @@ Updated: 8/27/2015
 
   - [Principles](#principles)
   - [Command conventions](#command-conventions)
+    - [Create commands](#create-commands)
   - [Flag conventions](#flag-conventions)
   - [Output conventions](#output-conventions)
   - [Documentation conventions](#documentation-conventions)
@@ -71,6 +72,19 @@ Updated: 8/27/2015
 * Commands that generate resources, such as `run` or `expose`, should obey specific conventions, see [generators](#generators).
 * A command group (e.g., `kubectl config`) may be used to group related non-standard commands, such as custom generators, mutations, and computations.
 
+
+### Create commands
+
+`kubectl create <resource>` commands fill the gap between "I want to try Kubernetes, but I don't know or care what gets created" (`kubectl run`) and "I want to create exactly this" (author yaml and run `kubectl create -f`).
+They provide an easy way to create a valid object without having to know the vagaries of particular kinds, nested fields, and object key typos that are ignored by the yaml/json parser.
+Because editing an already created object is easier than authoring one from scratch, these commands only need to have enough parameters to create a valid object and set common immutable fields.  It should default as much as is reasonably possible.
+Once that valid object is created, it can be further manipulated using `kubectl edit` or the eventual `kubectl set` commands.
+
+`kubectl create <resource> <special-case>` commands help in cases where you need to perform non-trivial configuration generation/transformation tailored for a common use case.
+`kubectl create secret` is a good example, there's a `generic` flavor with keys mapping to files, then there's a `docker-registry` flavor that is tailored for creating an image pull secret,
+and there's a `tls` flavor for creating tls secrets.  You create these as separate commands to get distinct flags and separate help that is tailored for the particular usage.
+
+
 ## Flag conventions
 
 * Flags are all lowercase, with words separated by hyphens
@@ -253,6 +267,7 @@ func (g *NamespaceGeneratorV1) validate() error {
 The generator struct (`NamespaceGeneratorV1`) holds the necessary fields for namespace generation. It also satisfies the `kubectl.StructuredGenerator` interface by implementing the `StructuredGenerate() (runtime.Object, error)` method which configures the generated namespace that callers of the generator (`kubectl create namespace` in our case) need to create.
 * `--dry-run` should output the resource that would be created, without creating it.
 
+
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/kubectl-conventions.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->