change kinflate to kustomize

docs/Kube-manifest.yaml

@@ -0,0 +1,22 @@
+# This is a generated example; do not edit.  Rebuild with 'make docs'.
+ 
+apiVersion: manifest.k8s.io/v1alpha1
+kind: Manifest
+metadata:
+  name: helloworld
+description: helloworld does useful stuff.
+namePrefix: some-prefix
+# Labels to add to all objects and selectors.
+# These labels would also be used to form the selector for apply --prune
+# Named differently than “labels” to avoid confusion with metadata for this object
+objectLabels:
+  app: helloworld
+objectAnnotations:
+  note: This is an example annotation
+resources: []
+#- service.yaml
+#- ../some-dir/
+# There could also be configmaps in Base, which would make these overlays
+configMapGenerator: []
+# There could be secrets in Base, if just using a fork/rebase workflow
+secretGenerator: []

docs/glossary.md

@@ -0,0 +1,261 @@
+# Glossary
+
+[DAM]: #declarative-application-management
+[JSON]: https://www.json.org/
+[Resource]: #resource
+[YAML]: http://www.yaml.org/start.html
+[application]: #application
+[apply]: #apply
+[apt]: https://en.wikipedia.org/wiki/APT_(Debian)
+[base]: #base
+[bases]: #base
+[bespoke]: #bespoke-configuration
+[kustomize]: #kustomize
+[manifest]: #manifest
+[off-the-shelf]: #off-the-shelf
+[overlay]: #overlay
+[overlays]: #overlay
+[patch]: #patch
+[patches]: #patch
+[proposal]: https://github.com/kubernetes/community/pull/1629
+[rebase]: https://git-scm.com/docs/git-rebase
+[resource]: #resource
+[resources]: #resource
+[rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
+[target]: #target
+[workflow]: workflows.md
+
+## application
+
+An _application_ is a group of k8s resources related by
+some common purpose, e.g.  a load balancer in front of a
+webserver backed by a database.
+[Resource] labelling, naming and metadata schemes have
+historically served to group resources together for
+collective operations like _list_ and _remove_.
+
+This [proposal] describes a new k8s resource called
+_application_ to more formally describe this idea and
+provide support for application-level operations and
+dashboards.
+
+[kustomize] configures k8s resources, and the proposed
+application resource is just another resource.
+
+
+## apply
+
+The verb _apply_ in the context of k8s refers to a
+kubectl command and an in-progress [API
+endpoint](https://goo.gl/UbCRuf) for mutating a
+cluster.
+
+One _applies_ a statement of what one wants to a
+cluster in the form of a complete resource list.
+
+The cluster merges this with the previously applied
+state and the actual state to arrive at a new desired
+state, which the cluster's reconcilation loop attempts
+to create.  This is the foundation of level-based state
+management in k8s.
+
+## base
+
+A _base_ is a [target] that some [overlay] modifies.
+
+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.
+
+## bespoke configuration
+
+A _bespoke_ configuration is a [manifest] and some
+[resources] created and maintained internally by some
+organization for their own purposes.
+
+The [workflow] associated with a _bespoke_ config is
+simpler than the workflow associated with an
+[off-the-shelf] config, because there's no notion of
+periodically capturing someone else's upgrades to the
+[off-the-shelf] config.
+
+## declarative application management
+
+_Declarative Application Management_ (DAM) is a [set of
+ideas](https://goo.gl/T66ZcD) aiming to ease management
+of k8s clusters.
+
+ * Works with any configuration, be it bespoke,
+   off-the-shelf, stateless, stateful, etc.
+ * Supports common customizations, and creation of
+   instance variants (dev vs, staging vs. production).
+ * Exposes and teaches native k8s APIs, rather than
+   hiding them.
+ * No friction integration with version control to
+   support reviews and audit trails.
+ * Composable with other tools in a unix sense.
+ * Eschews crossing the line into templating, domain
+   specific languages, etc., frustrating the other
+   goals.
+
+## instance
+
+An _instance_ is the outcome, in a cluster, of applying
+an [overlay] to a [base].
+
+> E.g., a _staging_ and _production_ overlay both modify some
+> common base to create distinct instances.
+>
+> The _staging_ instance is the set of resources
+> exposed to quality assurance testing, or to some
+> external users who'd like to see what the next
+> version of production will look like.
+>
+> The _production_ instance is the set of resources
+> exposed to production traffic, and thus may employ
+> deployments with a large number of replicas and higher
+> cpu and memory requests.
+
+
+## kustomize
+
+_kustomize_ is a command line tool supporting template-free
+customization of declarative configuration targetted to
+k8s.
+
+_Targetted to k8s means_ that kustomize may need some
+limited understanding of API resources, k8s concepts
+like names, labels, namespaces, etc. and the semantics
+of resource patching.
+
+kustomize is an implementation of [DAM].
+
+## manifest
+
+A _manifest_ is a file called `kustomize.yaml` that
+describes a configuration consumable by [kustomize].
+
+Here's an [example](Kube-manifest.yaml).
+
+A manifest contains fields falling into these categories:
+
+ * Immediate customization instructions -
+   _nameprefix_, _labelprefix_, etc.
+ * Resource _generators_ for configmaps and secrets.
+ * References to _external files_ in these categories:
+   * [resources] - completely specified k8s API objects,
+      e.g. `deployment.yaml`, `configmap.yaml`, etc.
+   * [patches] - _partial_ resources that modify full
+     resources defined in a [base]
+     (only meaningful in an [overlay]).
+   * [bases] - path to a directory containing
+     a [manifest] (only meaningful in an [overlay]).
+ * (_TBD_) Standard k8s API kind-version fields.
+
+## off-the-shelf configuration
+
+An _off-the-shelf_ configuration is a manifest and
+resources intentionally published somewhere for others
+to use.
+
+E.g. one might create a github repository like this:
+
+> ```
+> github.com/username/someapp/
+>   kustomize.yaml
+>   deployment.yaml
+>   configmap.yaml
+>   README.md
+> ```
+
+Someone could then _fork_ this repo (on github) and
+_clone_ their fork to their local disk for
+customization.
+
+This clone could act as a [base] for the user's
+own [overlays] to do further customization.
+
+## overlay
+
+An _overlay_ is a [target] that modifies (and thus
+depends on) another target.
+
+The [manifest] in an overlay refers to (via file path,
+URI or other method) to _some other manifest_, 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 instances.
+
+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 cluser like this:
+
+> ```
+>  kustomize inflate someapp/overlays/staging |\
+>      kubectl apply -f -
+>
+>  kustomize inflate someapp/overlays/production |\
+>      kubectl apply -f -
+> ```
+
+Usage of the base is implicit (the overlay's manifest
+points to the base).
+
+An overlay may act as a base to another overlay.
+
+## package
+
+The word _package_ has no meaning in kustomize, as
+kustomize is not to be confused with a package
+management tool in the tradition of, say, [apt] or
+[rpm].
+
+## patch
+
+A _patch_ is a partially defined k8s resource with a
+name that must match a resource already known per
+traversal rules built into [kustomize].
+
+_Patch_ is a field in the manifest, 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
+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.
+
+## sub-target / sub-application / sub-package
+
+A _sub-whatever_ is not a thing. There are only [bases] and [overlays].
+
+## target
+
+The _target_ is the argument to `build`, e.g.:
+
+> ```
+>  kustomize build $target
+> ```
+
+`$target` must be a path to a directory that
+immediately contains a file called
+`kustomize.yaml` (i.e. a [manifest]).
+
+The target contains, or refers to, all the information
+needed to create customized resources to send to the
+[apply] operation.
+
+A target is a [base] or an [overlay].

docs/workflows.md

@@ -0,0 +1,127 @@
+[OTS]: glossary.md#off-the-shelf
+[apply]: glossary.md#apply
+[applying]: glossary.md#apply
+[base]: glossary.md#base
+[fork]: https://guides.github.com/activities/forking/
+[instances]: glossary.md#instance
+[manifest]: glossary.md#manifest
+[off-the-shelf]: glossary.md#off-the-shelf
+[overlays]: glossary.md#overlay
+[patch]: glossary.md#patch
+[patches]: glossary.md#patch
+[rebase]: https://git-scm.com/docs/git-rebase
+[resources]: glossary.md#resources
+[workflowBespoke]: workflowBespoke.jpg
+[workflowOts]: workflowOts.jpg
+
+# workflows
+
+A _workflow_ is the sequence of steps one takes to
+use and maintain a configuration.
+
+## Bespoke configuration
+
+In this workflow, all configuration files are owned by
+the user.  No content is incorporated from version
+control repositories owned by others.
+
+![bespoke config workflow image][workflowBespoke]
+
+#### 1) create a directory in version control
+
+> ```
+> git init ~/ldap
+> ```
+
+#### 2) create a [base]
+
+> ```
+> mkdir -p ~/ldap/base
+> ```
+
+In this directory, create and commit a [manifest]
+and a set of [resources].
+
+#### 3) create [overlays]
+
+> ```
+> mkdir -p ~/ldap/overlays/staging
+> mkdir -p ~/ldap/overlays/production
+> ```
+
+Each of these directories needs a [manifest]
+and one or more [patches].
+
+The _staging_ directory might get a patch
+that turns on an experiment flag in a configmap.
+
+The _production_ directory might get a patch
+that increases the replica count in a deployment
+specified in the base.
+
+#### 4) bring up [instances]
+
+Run kustomize, and pipe the output to [apply].
+
+> ```
+> kustomize ~/ldap/overlays/staging | kubectl apply -f -
+> kustomize ~/ldap/overlays/production | kubectl apply -f -
+> ```
+
+
+## Off-the-shelf configuration
+
+In this workflow, all files are owned by the user and
+maintained in a repository under their control, but
+they are based on an [off-the-shelf] configuration that
+is periodically consulted for updates.
+
+
+![off-the-shelf config workflow image][workflowOts]
+
+#### 1) find and [fork] an [OTS] config
+
+#### 2) clone it as your [base]
+
+The [base] directory is maintained in a repo whose
+upstream is an [OTS] configuration, in this case
+https://github.com/kinflate/ldap.
+
+> ```
+> mkdir ~/ldap
+> git clone https://github.com/$USER/ldap ~/ldap/base
+> cd ~/ldap/base
+> git remote add upstream git@github.com:kustomize/ldap
+> ```
+
+#### 3) create [overlays]
+
+As in the bespoke case above, create and populate
+an _overlays_ directory.
+
+The [overlays] are siblings to each other and to the
+[base] they depend on.
+
+> ```
+> mkdir -p ~/ldap/overlays/staging
+> mkdir -p ~/ldap/overlays/production
+> ```
+
+
+#### 4) bring up instances
+
+> ```
+> kustomize ~/ldap/overlays/staging | kubectl apply -f -
+> kustomize ~/ldap/overlays/production | kubectl apply -f -
+> ```
+
+#### 5) (optionally) capture changes from upstream
+
+The user can optionally [rebase] their [base] to
+capture changes made in the upstream repository.
+
+> ```
+> cd ~/ldap/base
+> git fetch upstream
+> git rebase upstream/master
+> ```