diff --git a/cmd/kinflate/README.md b/cmd/kinflate/README.md index 5d806a13d..69a629589 100644 --- a/cmd/kinflate/README.md +++ b/cmd/kinflate/README.md @@ -1,8 +1,8 @@ # kinflate -[_kubectl apply_]: glossary.md#apply -[DAM]: glossary.md#declarative-application-management -[workflows]: workflows.md +[_kubectl apply_]: docs/glossary.md#apply +[DAM]: docs/glossary.md#declarative-application-management +[workflows]: docs/workflows.md `kinflate` is a command line tool supporting template-free customization of declarative diff --git a/cmd/kinflate/glossary.md b/cmd/kinflate/docs/glossary.md similarity index 100% rename from cmd/kinflate/glossary.md rename to cmd/kinflate/docs/glossary.md diff --git a/cmd/kinflate/docs/workflowBespoke.jpg b/cmd/kinflate/docs/workflowBespoke.jpg new file mode 100644 index 000000000..4064286b1 Binary files /dev/null and b/cmd/kinflate/docs/workflowBespoke.jpg differ diff --git a/cmd/kinflate/docs/workflowOts.jpg b/cmd/kinflate/docs/workflowOts.jpg new file mode 100644 index 000000000..e7969fedb Binary files /dev/null and b/cmd/kinflate/docs/workflowOts.jpg differ diff --git a/cmd/kinflate/docs/workflows.md b/cmd/kinflate/docs/workflows.md new file mode 100644 index 000000000..e38f17627 --- /dev/null +++ b/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 +> ``` diff --git a/cmd/kinflate/workflows.md b/cmd/kinflate/workflows.md deleted file mode 100644 index 9b0500172..000000000 --- a/cmd/kinflate/workflows.md +++ /dev/null @@ -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.