From fb308353d33e2a33a4a2c024f6c37ae815c674f4 Mon Sep 17 00:00:00 2001 From: Jeffrey Regan Date: Tue, 24 Apr 2018 12:57:29 -0700 Subject: [PATCH] breakfast --- README.md | 17 ++++--- demos/README.md | 6 ++- demos/breakfast.md | 123 +++++++++++++++++++++++++++++++++++++++++++++ docs/glossary.md | 40 +++++++++++++-- 4 files changed, 175 insertions(+), 11 deletions(-) create mode 100644 demos/breakfast.md diff --git a/README.md b/README.md index a71a50593..5f7382c84 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,22 @@ [overlay]: docs/glossary.md#overlay [resources]: docs/glossary.md#resource [workflows]: docs/workflows.md +[kubernetes style]: docs/glossary.md#kubernetes-style-object `kustomize` is a command line tool supporting -template-free customization of declarative -configuration targetted to kubernetes. +template-free customization of YAML (or JSON) +objects that conform to the [kubernetes style]. + +If your objects have a `kind` and a `metadata` field, +kustomize can patch them to help you manage +configuration sharing and re-use. + +For more details, try a [demo]. ## Installation -Assumes [Go](https://golang.org/) is installed -and your `PATH` contains `$GOPATH/bin`: +This assumes [Go](https://golang.org/) (v1.10.1 or higher) +is installed and your `PATH` contains `$GOPATH/bin`: ``` @@ -48,5 +55,3 @@ _development, staging and production_. Run kustomize on your overlay. The result is printed to `stdout` as a set of complete resources, ready to be [applied] to a cluster. - -For more details, try a [demo]. diff --git a/demos/README.md b/demos/README.md index e3818f1b9..6d941f851 100644 --- a/demos/README.md +++ b/demos/README.md @@ -7,7 +7,9 @@ These demos are covered by presubmit tests. World server. * [mysql](mySql.md) - Create a mySql production - configuration from scratch. - + configuration from scratch. + * [springboot](springboot.md) - Create a Spring Boot application production configuration from scratch. + + * [breakfast](breakfast.md) - Customize breakfast for Alice and Bob. diff --git a/demos/breakfast.md b/demos/breakfast.md new file mode 100644 index 000000000..4f3dba0a9 --- /dev/null +++ b/demos/breakfast.md @@ -0,0 +1,123 @@ +[kubernetes API object style]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + +# Demo: configure breakfast + + +Define a place to work: + + +``` +DEMO_HOME=$(mktemp -d) +``` + +Make a place to put the base breakfast configuration: + + +``` +mkdir -p $DEMO_HOME/breakfast/base +``` + +Make a `kustomization` to define what goes into +breakfast. This breakfast has coffee and pancakes: + + +``` +cat <$DEMO_HOME/breakfast/base/kustomization.yaml +resources: +- coffee.yaml +- pancakes.yaml +EOF +``` + +Here's a _coffee_ type. Give it a `kind` and `metdata/name` field +to conform to [kubernetes API object style]; no other +file or definition is needed: + + +``` +cat <$DEMO_HOME/breakfast/base/coffee.yaml +kind: Coffee +metadata: + name: morningCup +temperature: lukewarm +data: + greeting: "Good Morning!" +EOF +``` + +The `name` field merely distinguishes this instance of coffee from others (if +there were any). + +Likewise, define _pancakes_: + +``` +cat <$DEMO_HOME/breakfast/base/pancakes.yaml +kind: Pancakes +metadata: + name: comfort +stacksize: 3 +topping: none +EOF +``` + +Make a custom version of breakfast for Alice, who +likes her coffee hot: + + +``` +mkdir -p $DEMO_HOME/breakfast/overlays/alice + +cat <$DEMO_HOME/breakfast/overlays/alice/kustomization.yaml +commonLabels: + who: alice +bases: +- ../../base +patches: +- temperature.yaml +EOF + +cat <$DEMO_HOME/breakfast/overlays/alice/temperature.yaml +kind: Coffee +metadata: + name: morningCup +temperature: hot! +EOF +``` + +And likewise for Bob, who wants _five_ pancakes, with strawberries: + + +``` +mkdir -p $DEMO_HOME/breakfast/overlays/bob + +cat <$DEMO_HOME/breakfast/overlays/bob/kustomization.yaml +commonLabels: + who: bob +bases: +- ../../base +patches: +- topping.yaml +EOF + +cat <$DEMO_HOME/breakfast/overlays/bob/topping.yaml +kind: Pancakes +metadata: + name: comfort +stacksize: 5 +topping: strawberries +EOF +``` + +One can now generate the configs for Alice’s breakfast: + + +``` +kustomize build $DEMO_HOME/breakfast/overlays/alice +``` + +Likewise for Bob: + + +``` +kustomize build $DEMO_HOME/breakfast/overlays/bob +``` diff --git a/docs/glossary.md b/docs/glossary.md index 1ab3fb8ba..439df94a8 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -10,6 +10,8 @@ [base]: #base [bases]: #base [bespoke]: #bespoke-configuration +[k8s]: #kubernetes +[kubernetes]: #kubernetes [kustomize]: #kustomize [kustomization]: #kustomization [off-the-shelf]: #off-the-shelf @@ -143,11 +145,30 @@ A kustomization contains fields falling into these categories: a [kustomization] (only meaningful in an [overlay]). * (_TBD_) Standard k8s API kind-version fields. +## kubernetes + +[Kubernetes](https://kubernetes.io) is an open-source +system for automating deployment, scaling, and +management of containerized applications. + +It's often abbreviated as _k8s_. + +## kubernetes-style object + +[fields required]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + +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 version (if there's more than one +version). + ## kustomize _kustomize_ is a command line tool supporting template-free customization of declarative configuration targetted to -k8s. +k8s-style objects. _Targetted to k8s means_ that kustomize may need some limited understanding of API resources, k8s concepts @@ -236,8 +257,21 @@ 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. +A _resource_, in the context of kustomize, is a path to +a [YAML] or [JSON] file that completely defines a +functional k8s API object, like a deployment or a +configmap. + +More generally, a resource can be any correct YAML file +that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) +with a `kind` and a `metadata/name` field. + + +A _resource_ in the content of a REST-ful API is the +target of an HTTP operation like _GET_, _PUT_ or +_POST_. k8s offers a RESTful API surface to interact +with clients. + ## sub-target / sub-application / sub-package