Merge pull request kubernetes-sigs#35 from monopole/baseOverlayNotes

Base overlay notes

Author: monopole

README.md

@@ -8,7 +8,7 @@
 [demos]: demos/README.md
 [imageBase]: docs/base.jpg
 [imageOverlay]: docs/overlay.jpg
-[installation]: INSTALL.md
+[install]: INSTALL.md
 [kubernetes style]: docs/glossary.md#kubernetes-style-object
 [kustomization]: docs/glossary.md#kustomization
 [overlay]: docs/glossary.md#overlay
@@ -35,67 +35,64 @@ and it's like [`sed`], in that it emits editted text.
 [![Build Status](https://travis-ci.org/kubernetes-sigs/kustomize.svg?branch=master)](https://travis-ci.org/kubernetes-sigs/kustomize)
 [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/kustomize)](https://goreportcard.com/report/github.com/kubernetes-sigs/kustomize)
 
-**Installation**:
-Download a binary from the [release page], or
-see these [installation] alternatives.
-
-Be sure to try one of the tested [demos].
+**Installation**: Download a binary from the [release
+page], or see these [install] notes. Then try one of
+the tested [demos].
 
 ## Usage
 
 
-### Make a [base]
+### 1) Make a [kustomization] file
 
 In some directory containing your YAML [resource]
 files (deployments, services, configmaps, etc.), create a
 [kustomization] file.
 
 This file should declare those resources, and any
-common customization to apply to them, e.g. _add a
-common label_.
+customization to apply to them, e.g. _add a common
+label_.
 
 ![base image][imageBase]
 
 File structure:
 
 > ```
-> ~/yourApp
-> └── base
->     ├── deployment.yaml
->     ├── kustomization.yaml
->     └── service.yaml
+> ~/someApp
+> ├── deployment.yaml
+> ├── kustomization.yaml
+> └── service.yaml
 > ```
 
-This is your [base].  The resources in it could be a
-fork of someone else's configuration.  If so, you can
-easily rebase from the source material to capture
+The resources in this directory could be a fork of
+someone else's configuration.  If so, you can easily
+rebase from the source material to capture
 improvements, because you don't modify the resources
 directly.
 
 Generate customized YAML with:
 
 ```
-kustomize build ~/yourApp/base
+kustomize build ~/someApp
 ```
 
 The YAML can be directly [applied] to a cluster:
 
 > ```
-> kustomize build ~/yourApp/base | kubectl apply -f -
+> kustomize build ~/someApp | kubectl apply -f -
 > ```
 
 
-###  Create [variants] of a common base using [overlays]
+### 2) Create [variants] using [overlays]
 
-Manage traditional [variants] of a configuration like
-_development_, _staging_ and _production_ using
-[overlays].
+Manage traditional [variants] of a configuration - like
+_development_, _staging_ and _production_ - using
+[overlays] that modify a common [base].
 
 ![overlay image][imageOverlay]
 
 File structure:
 > ```
-> ~/yourApp
+> ~/someApp
 > ├── base
 > │   ├── deployment.yaml
 > │   ├── kustomization.yaml
@@ -111,21 +108,32 @@ File structure:
 >         └── replica_count.yaml
 > ```
 
-Store your overlays in your own repository.  On disk,
-the overlay can reference a base in a sibling
-directory.  This avoids trouble with nesting git
-repositories.
+Take the work from step (1) above, move it into a
+`someApp` subdirectory called `base`, then
+place overlays in a sibling directory.
+
+An overlay is just another kustomization, refering to
+the base, and referring to patches to apply to that
+base.
+
+This arrangement makes it easy to manage your
+configuration with `git`.  The base could have files
+from an upstream repository managed by someone else.
+The overlays could be in a repository you own.
+Arranging the repo clones as siblings on disk avoids
+the need for git submodules (though that works fine, if
+you are a submodule fan).
 
 Generate YAML with
 
 ```
-kustomize build ~/yourApp/overlays/production
+kustomize build ~/someApp/overlays/production
 ```
 
 The YAML can be directly [applied] to a cluster:
 
 > ```
-> kustomize build ~/yourApp/overlays/production | kubectl apply -f -
+> kustomize build ~/someApp/overlays/production | kubectl apply -f -
 > ```
 
 ## About

docs/glossary.md

@@ -68,25 +68,17 @@ management in k8s.
 
 A _base_ is a [target] that some [overlay] modifies.
 
-Any target, including an overlay, can be a base to
+Any target, including an [overlay], can be a base to
 another target.
 
 A base has no knowledge of the overlays that refer to it.
 
-A base is usable in isolation, i.e. one should
-be able to [apply] a base to a cluster directly.
-
 For simple [gitops] management, a base configuration
 could be the _sole content of a git repository
 dedicated to that purpose_.  Same with [overlays].
 Changes in a repo could generate a build, test and
 deploy cycle.
 
-Some of the demos for [kustomize] will break from this
-idiom and store all demo config files in directories
-_next_ to the `kustomize` code so that the code and
-demos can be more easily maintained by the same group
-of people.
 
 ## bespoke configuration
 
@@ -163,9 +155,9 @@ It's often abbreviated as _k8s_.
 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 variant, and an _apiVersion_
-field to identify the version (if there's more than one
-version).
+field to identify the particular instance, and an
+_apiVersion_ field to identify the version (if there's
+more than one version).
 
 ## kustomize
 
@@ -210,19 +202,24 @@ An _overlay_ is a [target] that modifies (and thus
 depends on) another target.
 
 The [kustomization] in an overlay refers to (via file
-path, URI or other method) _some other kustomization_,
+path, URI or other method) some other kustomization,
 known as its [base].
 
 An overlay is unusable without its base.
 
-An overlay supports the typical notion of a
-_development_, _QA_, _staging_ and _production_
-environment variants.
+An overlay may act as a base to another overlay.
+
+Overlays make the most sense when there is _more than
+one_, because they create different [variants] of a
+common base - e.g.  _development_, _QA_, _staging_ and
+_production_ environment variants.
 
-The configuration of these environments is specified in
-individual overlays (one per environment) that all
-refer to a common base that holds common configuration.
-One configures the cluster like this:
+These variants use the same overall resources, and vary
+in relatively simple ways, e.g. the number of replicas
+in a deployment, the CPU to a particular pod, the data
+source used in a configmap, etc.
+
+One configures a cluster like this:
 
 > ```
 >  kustomize build someapp/overlays/staging |\
@@ -232,10 +229,9 @@ One configures the cluster like this:
 >      kubectl apply -f -
 > ```
 
-Usage of the base is implicit (the overlay's kustomization
-points to the base).
+Usage of the base is implicit - the overlay's
+kustomization points to the base.
 
-An overlay may act as a base to another overlay.
 
 ## package