From 158348654680a600d68005a9cce574320ddbac19 Mon Sep 17 00:00:00 2001 From: Jeffrey Regan Date: Thu, 24 May 2018 16:39:25 -0700 Subject: [PATCH] base overlay notes --- README.md | 68 +++++++++++++++++++++++++++--------------------- docs/glossary.md | 42 ++++++++++++++---------------- 2 files changed, 57 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index da3660033c..c53df9b294 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [demos]: demos/README.md [imageBase]: docs/base.jpg [imageOverlay]: docs/overlay.jpg -[installation]: INSTALL.md +[install]: INSTALL.md [kubernetes style]: docs/glossary.md#kubernetes-style-object [kustomization]: docs/glossary.md#kustomization [overlay]: docs/glossary.md#overlay @@ -35,67 +35,64 @@ and it's like [`sed`], in that it emits editted text. [![Build Status](https://travis-ci.org/kubernetes-sigs/kustomize.svg?branch=master)](https://travis-ci.org/kubernetes-sigs/kustomize) [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/kustomize)](https://goreportcard.com/report/github.com/kubernetes-sigs/kustomize) -**Installation**: -Download a binary from the [release page], or -see these [installation] alternatives. - -Be sure to try one of the tested [demos]. +**Installation**: Download a binary from the [release +page], or see these [install] notes. Then try one of +the tested [demos]. ## Usage -### Make a [base] +### 1) Make a [kustomization] file In some directory containing your YAML [resource] files (deployments, services, configmaps, etc.), create a [kustomization] file. This file should declare those resources, and any -common customization to apply to them, e.g. _add a -common label_. +customization to apply to them, e.g. _add a common +label_. ![base image][imageBase] File structure: > ``` -> ~/yourApp -> └── base -> ├── deployment.yaml -> ├── kustomization.yaml -> └── service.yaml +> ~/someApp +> ├── deployment.yaml +> ├── kustomization.yaml +> └── service.yaml > ``` -This is your [base]. The resources in it could be a -fork of someone else's configuration. If so, you can -easily rebase from the source material to capture +The resources in this directory could be a fork of +someone else's configuration. If so, you can easily +rebase from the source material to capture improvements, because you don't modify the resources directly. Generate customized YAML with: ``` -kustomize build ~/yourApp/base +kustomize build ~/someApp ``` The YAML can be directly [applied] to a cluster: > ``` -> kustomize build ~/yourApp/base | kubectl apply -f - +> kustomize build ~/someApp | kubectl apply -f - > ``` -### Create [variants] of a common base using [overlays] +### 2) Create [variants] using [overlays] -Manage traditional [variants] of a configuration like -_development_, _staging_ and _production_ using -[overlays]. +Manage traditional [variants] of a configuration - like +_development_, _staging_ and _production_ - using +[overlays] that modify a common [base]. ![overlay image][imageOverlay] File structure: > ``` -> ~/yourApp +> ~/someApp > ├── base > │   ├── deployment.yaml > │   ├── kustomization.yaml @@ -111,21 +108,32 @@ File structure: > └── replica_count.yaml > ``` -Store your overlays in your own repository. On disk, -the overlay can reference a base in a sibling -directory. This avoids trouble with nesting git -repositories. +Take the work from step (1) above, move it into a +`someApp` subdirectory called `base`, then +place overlays in a sibling directory. + +An overlay is just another kustomization, refering to +the base, and referring to patches to apply to that +base. + +This arrangement makes it easy to manage your +configuration with `git`. The base could have files +from an upstream repository managed by someone else. +The overlays could be in a repository you own. +Arranging the repo clones as siblings on disk avoids +the need for git submodules (though that works fine, if +you are a submodule fan). Generate YAML with ``` -kustomize build ~/yourApp/overlays/production +kustomize build ~/someApp/overlays/production ``` The YAML can be directly [applied] to a cluster: > ``` -> kustomize build ~/yourApp/overlays/production | kubectl apply -f - +> kustomize build ~/someApp/overlays/production | kubectl apply -f - > ``` ## About diff --git a/docs/glossary.md b/docs/glossary.md index 3fa5f54c04..3657d76c6c 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -68,25 +68,17 @@ management in k8s. A _base_ is a [target] that some [overlay] modifies. -Any target, including an overlay, can be a base to +Any target, including an [overlay], can be a base to another target. A base has no knowledge of the overlays that refer to it. -A base is usable in isolation, i.e. one should -be able to [apply] a base to a cluster directly. - For simple [gitops] management, a base configuration could be the _sole content of a git repository dedicated to that purpose_. Same with [overlays]. Changes in a repo could generate a build, test and deploy cycle. -Some of the demos for [kustomize] will break from this -idiom and store all demo config files in directories -_next_ to the `kustomize` code so that the code and -demos can be more easily maintained by the same group -of people. ## bespoke configuration @@ -163,9 +155,9 @@ 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 variant, and an _apiVersion_ -field to identify the version (if there's more than one -version). +field to identify the particular instance, and an +_apiVersion_ field to identify the version (if there's +more than one version). ## kustomize @@ -210,19 +202,24 @@ 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_, +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 variants. +An overlay may act as a base to another overlay. + +Overlays make the most sense when there is _more than +one_, because they create different [variants] of a +common base - e.g. _development_, _QA_, _staging_ and +_production_ environment variants. -The configuration of these environments is specified in -individual overlays (one per environment) that all -refer to a common base that holds common configuration. -One configures the cluster like this: +These variants use the same overall resources, and vary +in relatively simple ways, e.g. the number of replicas +in a deployment, the CPU to a particular pod, the data +source used in a configmap, etc. + +One configures a cluster like this: > ``` > kustomize build someapp/overlays/staging |\ @@ -232,10 +229,9 @@ One configures the cluster like this: > kubectl apply -f - > ``` -Usage of the base is implicit (the overlay's kustomization -points to the base). +Usage of the base is implicit - the overlay's +kustomization points to the base. -An overlay may act as a base to another overlay. ## package