mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-13 01:50:55 +00:00
Merge pull request #35 from monopole/baseOverlayNotes
Base overlay notes
This commit is contained in:
Jeff Regan
68
README.md
68
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.
|
||||
[](https://travis-ci.org/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
|
||||
|
||||
@@ -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.
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user