diff --git a/demos/README.md b/demos/README.md index 45d922c85..aef195f51 100644 --- a/demos/README.md +++ b/demos/README.md @@ -4,11 +4,11 @@ These demos assume that `kustomize` is on your `$PATH`. They are covered by pre-submit tests. * [hello world](helloWorld.md) - Deploy multiple - (differently configured) instances of a simple Hello + (differently configured) variants of a simple Hello World server. * [LDAP](ldap.md) - Deploy multiple - (differently configured) instances of a LDAP server. + (differently configured) variants of a LDAP server. * [mySql](mySql.md) - Create a MySQL production configuration from scratch. diff --git a/demos/breakfast.md b/demos/breakfast.md index 4f3dba0a9..f627fb437 100644 --- a/demos/breakfast.md +++ b/demos/breakfast.md @@ -1,4 +1,5 @@ [kubernetes API object style]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields +[variant]: ../docs/glossary.md#variant # Demo: configure breakfast @@ -45,8 +46,8 @@ data: EOF ``` -The `name` field merely distinguishes this instance of coffee from others (if -there were any). +The `name` field merely distinguishes this [variant] of +coffee from others (if there were any). Likewise, define _pancakes_: diff --git a/demos/helloWorld.md b/demos/helloWorld.md index 929d8b194..731e7ce92 100644 --- a/demos/helloWorld.md +++ b/demos/helloWorld.md @@ -2,14 +2,14 @@ [config]: https://github.com/kinflate/example-hello [gitops]: ../docs/glossary.md#gitops [hello]: https://github.com/monopole/hello -[instance]: ../docs/glossary.md#instance -[instances]: ../docs/glossary.md#instance [kustomization]: ../docs/glossary.md#kustomization [original]: https://github.com/kinflate/example-hello [overlay]: ../docs/glossary.md#overlay [overlays]: ../docs/glossary.md#overlay +[variant]: ../docs/glossary.md#variant +[variants]: ../docs/glossary.md#variant -# Demo: hello world with instances +# Demo: hello world with variants Steps: @@ -36,7 +36,7 @@ Alternatively, use Let's run the [hello] service. -To use [overlays] to create [instances], we must +To use [overlays] to create [variants], we must first establish a common [base]. To keep this document shorter, the base resources are @@ -125,7 +125,7 @@ Create a _staging_ and _production_ [overlay]: * _Staging_ enables a risky feature not enabled in production. * _Production_ has a higher replica count. * Web server greetings from these cluster - [instances] will differ from each other. + [variants] will differ from each other. ``` @@ -144,7 +144,7 @@ defining a new name prefix, and some different labels. cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml namePrefix: staging- commonLabels: - instance: staging + variant: staging org: acmeCorporation commonAnnotations: note: Hello, I am staging! @@ -185,7 +185,7 @@ with a different name prefix and labels. cat <$OVERLAYS/production/kustomization.yaml namePrefix: production- commonLabels: - instance: production + variant: production org: acmeCorporation commonAnnotations: note: Hello, I am production! @@ -224,7 +224,7 @@ EOF - an _overlays_ directory, containing the kustomizations and patches required to create distinct _staging_ - and _production_ instances in a cluster. + and _production_ [variants] in a cluster. Review the directory structure and differences: @@ -276,9 +276,9 @@ something like > --- > > note: Hello, I am production! > 11c11 -> < instance: staging +> < variant: staging > --- -> > instance: production +> > variant: production > 13c13 > (...truncated) > ``` @@ -346,7 +346,7 @@ collected. [patch]: ../docs/glossary.md#patch -The _staging_ instance here has a configMap [patch]: +The _staging_ [variant] here has a configMap [patch]: ``` diff --git a/demos/ldap.md b/demos/ldap.md index 3c7ad5c3c..ae286c3c7 100644 --- a/demos/ldap.md +++ b/demos/ldap.md @@ -1,12 +1,12 @@ [base]: ../docs/glossary.md#base [gitops]: ../docs/glossary.md#gitops -[instance]: ../docs/glossary.md#instance -[instances]: ../docs/glossary.md#instance [kustomization]: ../docs/glossary.md#kustomization [overlay]: ../docs/glossary.md#overlay [overlays]: ../docs/glossary.md#overlay +[variant]: ../docs/glossary.md#variant +[variants]: ../docs/glossary.md#variant -# Demo: LDAP with instances +# Demo: LDAP with variants Steps: @@ -31,7 +31,7 @@ Alternatively, use ## Establish the base -To use [overlays] to create [instances], we must +To use [overlays] to create [variants], we must first establish a common [base]. To keep this document shorter, the base resources are @@ -118,7 +118,7 @@ Create a _staging_ and _production_ [overlay]: * _Staging_ adds a configMap. * _Production_ has a higher replica count and a persistent disk. - * [instances] will differ from each other. + * [variants] will differ from each other. ``` @@ -195,7 +195,7 @@ The production customization adds 6 replica as well as a consistent disk. - an _overlays_ directory, containing the kustomizations and patches required to create distinct _staging_ - and _production_ instances in a cluster. + and _production_ [variants] in a cluster. Review the directory structure and differences: @@ -282,4 +282,3 @@ To deploy, pipe the above commands to kubectl apply: > kustomize build $OVERLAYS/production |\ > kubectl apply -f - > ``` - diff --git a/docs/glossary.md b/docs/glossary.md index 1b25d14f7..eb5f91d88 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -26,6 +26,8 @@ [resources]: #resource [rpm]: https://en.wikipedia.org/wiki/Rpm_(software) [target]: #target +[variant]: #variant +[variants]: #variant [workflow]: workflows.md ## application @@ -107,7 +109,7 @@ 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). + [variants] (dev vs. staging vs. production). * Exposes and teaches native k8s APIs, rather than hiding them. * No friction integration with version control to @@ -123,20 +125,20 @@ Devops or CICD workflows that use a git repository as a single source of truth and take action (e.g., build, test or deploy) when that truth changes. -## instance +## variant -An _instance_ is the outcome, in a cluster, of applying +An _variant_ 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. +> common base to create distinct variants. > -> The _staging_ instance is the set of resources +> The _staging_ variant 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 +> The _production_ variant 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. @@ -179,7 +181,7 @@ 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 instance, and an `apiVersion` +field to identify the variant, and an `apiVersion` field to identify the version (if there's more than one version). @@ -225,15 +227,15 @@ own [overlays] to do further customization. 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_, known as -its [base]. +The [kustomization] in an overlay refers to (via file +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 instances. +environment variants. The configuration of these environments is specified in individual overlays (one per environment) that all diff --git a/docs/workflows.md b/docs/workflows.md index b94aa4536..ef0f84e8c 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -3,7 +3,7 @@ [applying]: glossary.md#apply [base]: glossary.md#base [fork]: https://guides.github.com/activities/forking/ -[instances]: glossary.md#instance +[variants]: glossary.md#variant [kustomization]: glossary.md#kustomization [off-the-shelf]: glossary.md#off-the-shelf [overlays]: glossary.md#overlay @@ -59,7 +59,7 @@ The _production_ directory might get a patch that increases the replica count in a deployment specified in the base. -#### 4) bring up [instances] +#### 4) bring up [variants] Run kustomize, and pipe the output to [apply]. @@ -108,7 +108,7 @@ The [overlays] are siblings to each other and to the > ``` -#### 4) bring up instances +#### 4) bring up [variants] > ``` > kustomize ~/ldap/overlays/staging | kubectl apply -f -