diff --git a/Makefile b/Makefile index 9b0d1685e..c1fefaef3 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ SHELL := /bin/bash -euo pipefail -config_file_name = Kube-manifest.yaml +config_file_name = kustomize.yaml example_config = docs/$(config_file_name) .PHONY: all diff --git a/README.md b/README.md index c3c474f3e..a71a50593 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [demo]: demos/README.md [imageBase]: docs/base.jpg [imageOverlay]: docs/overlay.jpg -[manifest]: docs/glossary.md#manifest +[kustomization]: docs/glossary.md#kustomization [overlay]: docs/glossary.md#overlay [resources]: docs/glossary.md#resource [workflows]: docs/workflows.md @@ -29,7 +29,7 @@ go get k8s.io/kubectl/cmd/kustomize #### 1) Make a base -A [base] configuration is a [manifest] listing a set of +A [base] configuration is a [kustomization] file listing a set of k8s [resources] - deployments, services, configmaps, secrets that serve some common purpose. diff --git a/demos/helloWorld.md b/demos/helloWorld.md index 63a02513a..f9a92bf58 100644 --- a/demos/helloWorld.md +++ b/demos/helloWorld.md @@ -3,7 +3,7 @@ [hello]: https://github.com/monopole/hello [instance]: ../docs/glossary.md#instance [instances]: ../docs/glossary.md#instance -[manifest]: ../docs/glossary.md#manifest +[kustomization]: ../docs/glossary.md#kustomization [original]: https://github.com/kinflate/example-hello [overlay]: ../docs/glossary.md#overlay [overlays]: ../docs/glossary.md#overlay @@ -74,11 +74,11 @@ cluster: to instantiate the _hello_ service. `kubectl` would only recognize the resource files. -## The Base Manifest +## The Base Kustomization -The `base` directory has a [manifest] file: +The `base` directory has a [kustomization] file: - + ``` BASE=$DEMO_HOME/base more $BASE/kustomize.yaml @@ -125,12 +125,12 @@ mkdir -p $OVERLAYS/staging mkdir -p $OVERLAYS/production ``` -#### Staging Manifest +#### Staging Kustomization -In the `staging` directory, make a manifest +In the `staging` directory, make a kustomization defining a new name prefix, and some different labels. - + ``` cat <<'EOF' >$OVERLAYS/staging/kustomize.yaml kustomizationName: makes-staging-hello @@ -167,12 +167,12 @@ data: EOF ``` -#### Production Manifest +#### Production Kustomization -In the production directory, make a manifest +In the production directory, make a kustomization with a different name prefix and labels. - + ``` cat <$OVERLAYS/production/kustomize.yaml kustomizationName: makes-production-tuthello @@ -215,7 +215,7 @@ EOF - a _base_ directory - a slightly customized clone of the original configuration, and - - an _overlays_ directory, containing the manifests + - an _overlays_ directory, containing the kustomizations and patches required to create distinct _staging_ and _production_ instances in a cluster. diff --git a/docs/glossary.md b/docs/glossary.md index e35db30ef..4484769d4 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -11,7 +11,7 @@ [bases]: #base [bespoke]: #bespoke-configuration [kustomize]: #kustomize -[manifest]: #manifest +[kustomization]: #kustomization [off-the-shelf]: #off-the-shelf [overlay]: #overlay [overlays]: #overlay @@ -73,7 +73,7 @@ be able to [apply] a base to a cluster directly. ## bespoke configuration -A _bespoke_ configuration is a [manifest] and some +A _bespoke_ configuration is a [kustomization] and some [resources] created and maintained internally by some organization for their own purposes. @@ -120,6 +120,27 @@ an [overlay] to a [base]. > deployments with a large number of replicas and higher > cpu and memory requests. +## kustomization + +A _kustomization_ is a file called `kustomize.yaml` that +describes a configuration consumable by [kustomize]. + +Here's an [example](kustomize.yaml). + +A kustomization 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 [kustomization] (only meaningful in an [overlay]). + * (_TBD_) Standard k8s API kind-version fields. ## kustomize @@ -134,31 +155,10 @@ 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 +An _off-the-shelf_ configuration is a kustomization and resources intentionally published somewhere for others to use. @@ -184,8 +184,8 @@ own [overlays] to do further customization. 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 +The [kustomization] in an overlay refers to (via file path, +URI or other method) to _some other kustomization_, known as its [base]. An overlay is unusable without its base. @@ -207,7 +207,7 @@ One configures the cluser like this: > kubectl apply -f - > ``` -Usage of the base is implicit (the overlay's manifest +Usage of the base is implicit (the overlay's kustomization points to the base). An overlay may act as a base to another overlay. @@ -225,7 +225,7 @@ 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 +_Patch_ is a field in the kustomization, 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 @@ -252,7 +252,7 @@ The _target_ is the argument to `build`, e.g.: `$target` must be a path to a directory that immediately contains a file called -`kustomize.yaml` (i.e. a [manifest]). +`kustomize.yaml` (i.e. a [kustomization]). The target contains, or refers to, all the information needed to create customized resources to send to the diff --git a/docs/Kube-manifest.yaml b/docs/kustomize.yaml similarity index 88% rename from docs/Kube-manifest.yaml rename to docs/kustomize.yaml index 98e59dfb8..1f5fb695e 100644 --- a/docs/Kube-manifest.yaml +++ b/docs/kustomize.yaml @@ -1,9 +1,5 @@ # This is a generated example; do not edit. Rebuild with 'make docs'. - -apiVersion: manifest.k8s.io/v1alpha1 -kind: Manifest -metadata: - name: helloworld +kustomizationName: helloworld description: helloworld does useful stuff. namePrefix: some-prefix # Labels to add to all objects and selectors. diff --git a/docs/workflows.md b/docs/workflows.md index 2c05249c2..b94aa4536 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -4,7 +4,7 @@ [base]: glossary.md#base [fork]: https://guides.github.com/activities/forking/ [instances]: glossary.md#instance -[manifest]: glossary.md#manifest +[kustomization]: glossary.md#kustomization [off-the-shelf]: glossary.md#off-the-shelf [overlays]: glossary.md#overlay [patch]: glossary.md#patch @@ -39,8 +39,8 @@ control repositories owned by others. > mkdir -p ~/ldap/base > ``` -In this directory, create and commit a [manifest] -and a set of [resources]. +In this directory, create and commit a [kustomization] +file and a set of [resources]. #### 3) create [overlays] @@ -49,8 +49,8 @@ and a set of [resources]. > mkdir -p ~/ldap/overlays/production > ``` -Each of these directories needs a [manifest] -and one or more [patches]. +Each of these directories needs a [kustomization] +file and one or more [patches]. The _staging_ directory might get a patch that turns on an experiment flag in a configmap.