262 lines
7.5 KiB
Markdown
262 lines
7.5 KiB
Markdown
# Glossary
|
|
|
|
[DAM]: #declarative-application-management
|
|
[JSON]: https://www.json.org/
|
|
[Resource]: #resource
|
|
[YAML]: http://www.yaml.org/start.html
|
|
[application]: #application
|
|
[apply]: #apply
|
|
[apt]: https://en.wikipedia.org/wiki/APT_(Debian)
|
|
[base]: #base
|
|
[bases]: #base
|
|
[bespoke]: #bespoke-configuration
|
|
[kustomize]: #kustomize
|
|
[kustomization]: #kustomization
|
|
[off-the-shelf]: #off-the-shelf
|
|
[overlay]: #overlay
|
|
[overlays]: #overlay
|
|
[patch]: #patch
|
|
[patches]: #patch
|
|
[proposal]: https://github.com/kubernetes/community/pull/1629
|
|
[rebase]: https://git-scm.com/docs/git-rebase
|
|
[resource]: #resource
|
|
[resources]: #resource
|
|
[rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
|
|
[target]: #target
|
|
[workflow]: workflows.md
|
|
|
|
## application
|
|
|
|
An _application_ is a group of k8s resources related by
|
|
some common purpose, e.g. a load balancer in front of a
|
|
webserver backed by a database.
|
|
[Resource] labelling, naming and metadata schemes have
|
|
historically served to group resources together for
|
|
collective operations like _list_ and _remove_.
|
|
|
|
This [proposal] describes a new k8s resource called
|
|
_application_ to more formally describe this idea and
|
|
provide support for application-level operations and
|
|
dashboards.
|
|
|
|
[kustomize] configures k8s resources, and the proposed
|
|
application resource is just another resource.
|
|
|
|
|
|
## apply
|
|
|
|
The verb _apply_ in the context of k8s refers to a
|
|
kubectl command and an in-progress [API
|
|
endpoint](https://goo.gl/UbCRuf) for mutating a
|
|
cluster.
|
|
|
|
One _applies_ a statement of what one wants to a
|
|
cluster in the form of a complete resource list.
|
|
|
|
The cluster merges this with the previously applied
|
|
state and the actual state to arrive at a new desired
|
|
state, which the cluster's reconcilation loop attempts
|
|
to create. This is the foundation of level-based state
|
|
management in k8s.
|
|
|
|
## base
|
|
|
|
A _base_ is a [target] that some [overlay] modifies.
|
|
|
|
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.
|
|
|
|
## bespoke configuration
|
|
|
|
A _bespoke_ configuration is a [kustomization] and some
|
|
[resources] created and maintained internally by some
|
|
organization for their own purposes.
|
|
|
|
The [workflow] associated with a _bespoke_ config is
|
|
simpler than the workflow associated with an
|
|
[off-the-shelf] config, because there's no notion of
|
|
periodically capturing someone else's upgrades to the
|
|
[off-the-shelf] config.
|
|
|
|
## declarative application management
|
|
|
|
_Declarative Application Management_ (DAM) is a [set of
|
|
ideas](https://goo.gl/T66ZcD) aiming to ease management
|
|
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).
|
|
* Exposes and teaches native k8s APIs, rather than
|
|
hiding them.
|
|
* No friction integration with version control to
|
|
support reviews and audit trails.
|
|
* Composable with other tools in a unix sense.
|
|
* Eschews crossing the line into templating, domain
|
|
specific languages, etc., frustrating the other
|
|
goals.
|
|
|
|
## instance
|
|
|
|
An _instance_ 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.
|
|
>
|
|
> The _staging_ instance 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
|
|
> exposed to production traffic, and thus may employ
|
|
> 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_, _labelsToAdd_, 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
|
|
|
|
_kustomize_ is a command line tool supporting template-free
|
|
customization of declarative configuration targetted to
|
|
k8s.
|
|
|
|
_Targetted to k8s means_ that kustomize may need some
|
|
limited understanding of API resources, k8s concepts
|
|
like names, labels, namespaces, etc. and the semantics
|
|
of resource patching.
|
|
|
|
kustomize is an implementation of [DAM].
|
|
|
|
|
|
## off-the-shelf configuration
|
|
|
|
An _off-the-shelf_ configuration is a kustomization and
|
|
resources intentionally published somewhere for others
|
|
to use.
|
|
|
|
E.g. one might create a github repository like this:
|
|
|
|
> ```
|
|
> github.com/username/someapp/
|
|
> kustomize.yaml
|
|
> deployment.yaml
|
|
> configmap.yaml
|
|
> README.md
|
|
> ```
|
|
|
|
Someone could then _fork_ this repo (on github) and
|
|
_clone_ their fork to their local disk for
|
|
customization.
|
|
|
|
This clone could act as a [base] for the user's
|
|
own [overlays] to do further customization.
|
|
|
|
## overlay
|
|
|
|
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) to _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.
|
|
|
|
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 cluser like this:
|
|
|
|
> ```
|
|
> kustomize build someapp/overlays/staging |\
|
|
> kubectl apply -f -
|
|
>
|
|
> kustomize build someapp/overlays/production |\
|
|
> kubectl apply -f -
|
|
> ```
|
|
|
|
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
|
|
|
|
The word _package_ has no meaning in kustomize, as
|
|
kustomize is not to be confused with a package
|
|
management tool in the tradition of, say, [apt] or
|
|
[rpm].
|
|
|
|
## patch
|
|
|
|
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 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
|
|
dependencies. Since any resource file can be used as a
|
|
patch, one cannot reliably distinguish a resource from
|
|
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.
|
|
|
|
## sub-target / sub-application / sub-package
|
|
|
|
A _sub-whatever_ is not a thing. There are only [bases] and [overlays].
|
|
|
|
## target
|
|
|
|
The _target_ is the argument to `build`, e.g.:
|
|
|
|
> ```
|
|
> kustomize build $target
|
|
> ```
|
|
|
|
`$target` must be a path to a directory that
|
|
immediately contains a file called
|
|
`kustomize.yaml` (i.e. a [kustomization]).
|
|
|
|
The target contains, or refers to, all the information
|
|
needed to create customized resources to send to the
|
|
[apply] operation.
|
|
|
|
A target is a [base] or an [overlay].
|