Merge branch 'master' into patch-1

README.md

@@ -10,15 +10,22 @@
 [overlay]: docs/glossary.md#overlay
 [resources]: docs/glossary.md#resource
 [workflows]: docs/workflows.md
+[kubernetes style]: docs/glossary.md#kubernetes-style-object
 
 `kustomize` is a command line tool supporting
-template-free customization of declarative
-configuration targetted to kubernetes.
+template-free customization of YAML (or JSON)
+objects that conform to the [kubernetes style].
+
+If your objects have a `kind` and a `metadata` field,
+kustomize can patch them to help you manage
+configuration sharing and re-use.
+
+For more details, try a [demo].
 
 ## Installation
 
-Assumes [Go](https://golang.org/) is installed
-and your `PATH` contains `$GOPATH/bin`:
+This assumes [Go](https://golang.org/) (v1.10.1 or higher)
+is installed and your `PATH` contains `$GOPATH/bin`:
 
 <!-- @installkustomize @test -->
 ```
@@ -48,5 +55,3 @@ _development, staging and production_.
 Run kustomize on your overlay.  The result
 is printed to `stdout` as a set of complete
 resources, ready to be [applied] to a cluster.
-
-For more details, try a [demo].

demos/README.md

@@ -11,3 +11,5 @@ These demos are covered by presubmit tests.
 
  * [springboot](springboot.md) - Create a Spring Boot application production
    configuration from scratch.
+
+ * [breakfast](breakfast.md) - Customize breakfast for Alice and Bob.

demos/breakfast.md

@@ -0,0 +1,123 @@
+[kubernetes API object style]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+# Demo: configure breakfast
+
+
+Define a place to work:
+
+<!-- @makeWorkplace @test -->
+```
+DEMO_HOME=$(mktemp -d)
+```
+
+Make a place to put the base breakfast configuration:
+
+<!-- @baseDir @test -->
+```
+mkdir -p $DEMO_HOME/breakfast/base
+```
+
+Make a `kustomization` to define what goes into
+breakfast.  This breakfast has coffee and pancakes:
+
+<!-- @baseKustomization @test -->
+```
+cat <<EOF >$DEMO_HOME/breakfast/base/kustomization.yaml
+resources:
+- coffee.yaml
+- pancakes.yaml
+EOF
+```
+
+Here's a _coffee_ type.  Give it a `kind` and `metdata/name` field
+to conform to [kubernetes API object style]; no other
+file or definition is needed:
+
+<!-- @coffee @test -->
+```
+cat <<EOF >$DEMO_HOME/breakfast/base/coffee.yaml
+kind: Coffee
+metadata:
+  name: morningCup
+temperature: lukewarm
+data:
+  greeting: "Good Morning!"
+EOF
+```
+
+The `name` field merely distinguishes this instance of coffee from others (if
+there were any).
+
+Likewise, define _pancakes_:
+<!-- @pancakes @test -->
+```
+cat <<EOF >$DEMO_HOME/breakfast/base/pancakes.yaml
+kind: Pancakes
+metadata:
+  name: comfort
+stacksize: 3
+topping: none
+EOF
+```
+
+Make a custom version of breakfast for Alice, who
+likes her coffee hot:
+
+<!-- @aliceOverlay @test -->
+```
+mkdir -p $DEMO_HOME/breakfast/overlays/alice
+
+cat <<EOF >$DEMO_HOME/breakfast/overlays/alice/kustomization.yaml
+commonLabels:
+  who: alice
+bases:
+- ../../base
+patches:
+- temperature.yaml
+EOF
+
+cat <<EOF >$DEMO_HOME/breakfast/overlays/alice/temperature.yaml
+kind: Coffee
+metadata:
+  name: morningCup
+temperature: hot!
+EOF
+```
+
+And likewise for Bob, who wants _five_ pancakes, with strawberries:
+
+<!-- @bobOverlay @test -->
+```
+mkdir -p $DEMO_HOME/breakfast/overlays/bob
+
+cat <<EOF >$DEMO_HOME/breakfast/overlays/bob/kustomization.yaml
+commonLabels:
+  who: bob
+bases:
+- ../../base
+patches:
+- topping.yaml
+EOF
+
+cat <<EOF >$DEMO_HOME/breakfast/overlays/bob/topping.yaml
+kind: Pancakes
+metadata:
+  name: comfort
+stacksize: 5
+topping: strawberries
+EOF
+```
+
+One can now generate the configs for Alice’s breakfast:
+
+<!-- @generateAlice @test -->
+```
+kustomize build $DEMO_HOME/breakfast/overlays/alice
+```
+
+Likewise for Bob:
+
+<!-- @generateBob @test -->
+```
+kustomize build $DEMO_HOME/breakfast/overlays/bob
+```

docs/glossary.md

@@ -10,6 +10,8 @@
 [base]: #base
 [bases]: #base
 [bespoke]: #bespoke-configuration
+[k8s]: #kubernetes
+[kubernetes]: #kubernetes
 [kustomize]: #kustomize
 [kustomization]: #kustomization
 [off-the-shelf]: #off-the-shelf
@@ -143,11 +145,30 @@ A kustomization contains fields falling into these categories:
      a [kustomization] (only meaningful in an [overlay]).
  * (_TBD_) Standard k8s API kind-version fields.
 
+## kubernetes
+
+[Kubernetes](https://kubernetes.io) is an open-source
+system for automating deployment, scaling, and
+management of containerized applications.
+
+It's often abbreviated as _k8s_.
+
+## kubernetes-style object
+
+[fields required]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+An object, expressed in a YAML or JSON file, with the
+[fields required] by kubernetes.  Basically just a
+`kind` field to identify the type, a `metadata/name`
+field to identify the instance, and an `apiVersion`
+field to identify the version (if there's more than one
+version).
+
 ## kustomize
 
 _kustomize_ is a command line tool supporting template-free
 customization of declarative configuration targetted to
-k8s.
+k8s-style objects.
 
 _Targetted to k8s means_ that kustomize may need some
 limited understanding of API resources, k8s concepts
@@ -229,15 +250,28 @@ traversal rules built into [kustomize].
 _Patch_ is a field in the kustomization, distinct from
 resources, because a patch file looks like a resource
 file, but has different semantics.  A patch depends on
-(modifies) a resource, whereas a resourse has no
+(modifies) a resource, whereas a resource has no
 dependencies.  Since any resource file can be used as a
 patch, one cannot reliably distinguish a resource from
 a patch just by looking at the file's [YAML].
 
 ## resource
 
-A _resource_ is a path to a [YAML] or [JSON] file that
-completely defines a functional k8s API object.
+A _resource_, in the context of kustomize, is a path to
+a [YAML] or [JSON] file that completely defines a
+functional k8s API object, like a deployment or a
+configmap.
+
+More generally, a resource can be any correct YAML file
+that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)
+with a `kind` and a `metadata/name` field.
+
+
+A _resource_ in the content of a REST-ful API is the
+target of an HTTP operation like _GET_, _PUT_ or
+_POST_.  k8s offers a RESTful API surface to interact
+with clients.
+
 
 ## sub-target / sub-application / sub-package