add workflow figs

cmd/kinflate/README.md

@@ -1,8 +1,8 @@
 # kinflate
 
-[_kubectl apply_]: glossary.md#apply
+[_kubectl apply_]: docs/glossary.md#apply
-[DAM]: glossary.md#declarative-application-management
+[DAM]: docs/glossary.md#declarative-application-management
-[workflows]: workflows.md
+[workflows]: docs/workflows.md
 
 `kinflate` is a command line tool supporting
 template-free customization of declarative

cmd/kinflate/docs/workflows.md

@@ -0,0 +1,125 @@
+[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/
+[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 files are owner by the user and
+maintained in a repository under their control.
+
+![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 kinflate, and pipe the output to [apply].
+
+> ```
+> kinflate ~/ldap/overlays/staging | kubectl apply -f -
+> kinflate ~/ldap/overlays/production | kubectl apply -f -
+> ```
+
+
+## Off-the-shelf configuration
+
+Another complete workflow, with all files owner by the
+user and maintained in a repository under their
+control, but 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:kinflate/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
+
+> ```
+> kinflate ~/ldap/overlays/staging | kubectl apply -f -
+> kinflate ~/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
+> ```

cmd/kinflate/workflows.md

@@ -1,90 +0,0 @@
-# workflows
-
-A _workflow_ is the steps one takes to maintain and use
-a configuration.
-
-
-### No local files
-
-> ```
-> kinflate inflate -f https://github.com/kinflate/ldap
-> ```
-
-You just install some configuration from the web.
-
-### local, bare manifest
-
-> ```
-> kinflate inflate -f ~/Kube-manifest.yaml
-> ```
-
-The manifest is a simple overlay of some web-based
-customization target, e.g. specifiying a name prefix.
-It references no other files in ~, and the user doesn’t
-maintain it in a repo.
-
-### one local overlay
-
-> ```
-> kinflate inflate -f ~/myldap
-> ```
-
-The myldap dir contains a `Kube-manifest.yaml`
-referencing the base via URL, and a `deployment.yaml`
-that increase the replica count specified in the base.
-
-### multiple instances
-
-> ```
-> # Make a workspace
-> mkdir ldap
->
-> # Clone your fork of some target you wish to customize:
-> git clone https://github.com/kinflate/ldap ldap/base
->
-> # Create a directory to hold overlays.
-> mkdir ldap/overlays
->
-> # Create an overlay, in this case called “staging”
-> mkdir ldap/overlays/staging
->
-> # To “staging” add a Kube-manifest.yaml file,
-> # and optionally some resources and/or patches,
-> # e.g. a configmap that turns on an experiment flag.
->
-> # Create another overlay.
-> mkdir ldap/overlays/production
-> # And add customization to this directory as was done in staging,
-> # e.g. a patch that increases a replica count.
->
-> # Apply the instances to a cluster:
-> kinflate inflate -f ldap/overlays/staging | kubectl apply -f -
-> kinflate inflate -f ldap/overlays/production | kubectl apply -f -
->
-> ```
-
-[overlays]: glossary.md#overlay
-[base]: glossary.md#base
-[off-the-shelf]: glossary.md#off-the-shelf
-[rebase]: https://git-scm.com/docs/git-rebase
-
-The [overlays] are siblings to each other and to the
-[base] they depend on.  The overlays directory is
-maintained in its own repo.
-
-The [base] directory is maintained in another repo whose
-upstream is an [off-the-shelf] configuration, in this case
-https://github.com/kinflate/ldap.  The user can [rebase]
-this [base] at will to capture upgrades.
-
-### bad practice
-
-> ```
-> git clone https://github.com/kinflate/ldap
-> mkdir ldap/staging
-> mkdir ldap/production # ...
-> ```
-
-This nests kinflate targets, confusing one’s ability to
-maintain them in distinct git repos, and and increases
-the chance of a cycle.