mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-11 17:12:51 +00:00
Remove duplicate kustomize docs content
This commit is contained in:
Phillip Wittrock
@@ -11,3 +11,5 @@ description: >
|
||||
---
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/" />
|
||||
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,474 +8,3 @@ description: >
|
||||
---
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/glossary/" />
|
||||
|
||||
|
||||
# Glossary
|
||||
|
||||
[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
|
||||
[CRD]: #custom-resource-definition
|
||||
[DAM]: #declarative-application-management
|
||||
[Declarative Application Management]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md
|
||||
[JSON]: https://www.json.org/
|
||||
[JSONPatch]: https://tools.ietf.org/html/rfc6902
|
||||
[JSONMergePatch]: https://tools.ietf.org/html/rfc7386
|
||||
[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
|
||||
[gitops]: #gitops
|
||||
[k8s]: #kubernetes
|
||||
[kubernetes]: #kubernetes
|
||||
[kustomize]: #kustomize
|
||||
[kustomization]: #kustomization
|
||||
[kustomizations]: #kustomization
|
||||
[off-the-shelf]: #off-the-shelf-configuration
|
||||
[overlay]: #overlay
|
||||
[overlays]: #overlay
|
||||
[patch]: #patch
|
||||
[patches]: #patch
|
||||
[patchJson6902]: #patchjson6902
|
||||
[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/jsonpatch.md
|
||||
[patchesJson6902]: #patchjson6902
|
||||
[proposal]: https://github.com/kubernetes/community/pull/1629
|
||||
[rebase]: https://git-scm.com/docs/git-rebase
|
||||
[resource]: #resource
|
||||
[resources]: #resource
|
||||
[root]: #kustomization-root
|
||||
[rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
|
||||
[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md
|
||||
[target]: #target
|
||||
[transformer]: #transformer
|
||||
[variant]: #variant
|
||||
[variants]: #variant
|
||||
[workflow]: /kustomize/guides
|
||||
|
||||
## 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 reconciliation loop attempts
|
||||
to create. This is the foundation of level-based state
|
||||
management in k8s.
|
||||
|
||||
## base
|
||||
|
||||
A _base_ is a [kustomization] referred to
|
||||
by some other [kustomization].
|
||||
|
||||
Any kustomization, including an [overlay], can be a base to
|
||||
another kustomization.
|
||||
|
||||
A base has no knowledge of the overlays that refer to it.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## custom resource definition
|
||||
|
||||
One can extend the k8s API by making a
|
||||
Custom Resource Definition ([CRD spec]).
|
||||
|
||||
This defines a custom [resource] (CD), an entirely
|
||||
new resource that can be used alongside _native_
|
||||
resources like ConfigMaps, Deployments, etc.
|
||||
|
||||
Kustomize can customize a CD, but to do so
|
||||
kustomize must also be given the corresponding CRD
|
||||
so that it can interpret the structure correctly.
|
||||
|
||||
## declarative application management
|
||||
|
||||
Kustomize aspires to support [Declarative Application Management],
|
||||
a set of best practices around managing k8s clusters.
|
||||
|
||||
In brief, kustomize should
|
||||
|
||||
* Work with any configuration, be it bespoke,
|
||||
off-the-shelf, stateless, stateful, etc.
|
||||
* Support common customizations, and creation of
|
||||
[variants] (e.g. _development_ vs.
|
||||
_staging_ vs. _production_).
|
||||
* Expose and teach native k8s APIs, rather than
|
||||
hide them.
|
||||
* Add no friction to version control integration to
|
||||
support reviews and audit trails.
|
||||
* Compose with other tools in a unix sense.
|
||||
* Eschew crossing the line into templating, domain
|
||||
specific languages, etc., frustrating the other
|
||||
goals.
|
||||
|
||||
## generator
|
||||
|
||||
A generator makes resources that can be used as is,
|
||||
or fed into a [transformer].
|
||||
|
||||
## gitops
|
||||
|
||||
Devops or CICD workflows that use a git repository as a
|
||||
single source of truth and take action (e.g., build,
|
||||
test or deploy) when that truth changes.
|
||||
|
||||
## kustomization
|
||||
|
||||
The term _kustomization_ refers to a
|
||||
`kustomization.yaml` file, or more generally to a
|
||||
directory (the [root]) containing the
|
||||
`kustomization.yaml` file and all the relative file
|
||||
paths that it immediately references (all the local
|
||||
data that doesn't require a URL specification).
|
||||
|
||||
I.e. if someone gives you a _kustomization_ for use
|
||||
with [kustomize], it could be in the form of
|
||||
|
||||
* one file called `kustomization.yaml`,
|
||||
* a tarball (containing that YAML file plus what it references),
|
||||
* a git archive (ditto),
|
||||
* a URL to a git repo (ditto), etc.
|
||||
|
||||
A kustomization file contains [fields](fields.md)
|
||||
falling into four categories:
|
||||
|
||||
* _resources_ - what existing [resources] are to be customized.
|
||||
Example fields: _resources_, _crds_.
|
||||
|
||||
* _generators_ - what _new_ resources should be created.
|
||||
Example fields: _configMapGenerator_ (legacy),
|
||||
_secretGenerator_ (legacy), _generators_ (v2.1).
|
||||
|
||||
* _transformers_ - what to _do_ to the aforementioned resources.
|
||||
Example fields: _namePrefix_, _nameSuffix_, _images_,
|
||||
_commonLabels_, _patchesJson6902_, etc. and the more
|
||||
general _transformers_ (v2.1) field.
|
||||
|
||||
* _meta_ - fields which may influence all or some of
|
||||
the above. Example fields: _vars_, _namespace_,
|
||||
_apiVersion_, _kind_, etc.
|
||||
|
||||
## kustomization root
|
||||
|
||||
The directory that immediately contains a
|
||||
`kustomization.yaml` file.
|
||||
|
||||
When a kustomization file is processed, it may or may
|
||||
not be able to access files outside its root.
|
||||
|
||||
Data files like resource YAML files, or text files
|
||||
containing _name=value_ pairs intended for a ConfigMap
|
||||
or Secret, or files representing a patch to be used in
|
||||
a patch transformation, must live _within or below_ the
|
||||
root, and as such are specified via _relative
|
||||
paths_ exclusively.
|
||||
|
||||
A special flag (in v2.1), `--load_restrictions none`,
|
||||
is provided to relax this security feature, to, say,
|
||||
allow a patch file to be shared by more than one
|
||||
kustomization.
|
||||
|
||||
Other kustomizations (other directories containing a
|
||||
`kustomization.yaml` file) may be referred to by URL, by
|
||||
absolute path, or by relative path.
|
||||
|
||||
If kustomization __A__ depends on kustomization __B__, then
|
||||
|
||||
* __B__ may not _contain_ __A__.
|
||||
* __B__ may not _depend on_ __A__, even transitively.
|
||||
|
||||
__A__ may contain __B__, but in this case it might be
|
||||
simplest to have __A__ directly depend on __B__'s
|
||||
resources and eliminate __B__'s kustomization.yaml file
|
||||
(i.e. absorb __B__ into __A__).
|
||||
|
||||
Conventionally, __B__ is in a directory that's sibling
|
||||
to __A__, or __B__ is off in a completely independent
|
||||
git repository, referencable from any kustomization.
|
||||
|
||||
A common layout is
|
||||
|
||||
> ```
|
||||
> ├── base
|
||||
> │ ├── deployment.yaml
|
||||
> │ ├── kustomization.yaml
|
||||
> │ └── service.yaml
|
||||
> └── overlays
|
||||
> ├── dev
|
||||
> │ ├── kustomization.yaml
|
||||
> │ └── patch.yaml
|
||||
> ├── prod
|
||||
> │ ├── kustomization.yaml
|
||||
> │ └── patch.yaml
|
||||
> └── staging
|
||||
> ├── kustomization.yaml
|
||||
> └── patch.yaml
|
||||
> ```
|
||||
|
||||
The three roots `dev`, `prod` and `staging`
|
||||
(presumably) all refer to the `base` root. One would
|
||||
have to inspect the `kustomization.yaml` files to be
|
||||
sure.
|
||||
|
||||
## 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 particular 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, structured customization of declarative
|
||||
configuration targeted to k8s-style objects.
|
||||
|
||||
_Targeted to k8s means_ that kustomize has some
|
||||
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/
|
||||
> kustomization.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 kustomization that depends on
|
||||
another kustomization.
|
||||
|
||||
The [kustomizations] an overlay refers to (via file
|
||||
path, URI or other method) are called [bases].
|
||||
|
||||
An overlay is unusable without its bases.
|
||||
|
||||
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.
|
||||
|
||||
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 |\
|
||||
> 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.
|
||||
|
||||
See also [root].
|
||||
|
||||
## 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
|
||||
|
||||
General instructions to modify a resource.
|
||||
|
||||
There are two alternative techniques with similar
|
||||
power but different notation - the
|
||||
[strategic merge patch](#patchstrategicmerge)
|
||||
and the [JSON patch](#patchjson6902).
|
||||
|
||||
## patchStrategicMerge
|
||||
|
||||
A _patchStrategicMerge_ is [strategic-merge]-style patch (SMP).
|
||||
|
||||
An SMP looks like an incomplete YAML specification of
|
||||
a k8s resource. The SMP includes `TypeMeta`
|
||||
fields to establish the group/version/kind/name of the
|
||||
[resource] to patch, then just enough remaining fields
|
||||
to step into a nested structure to specify a new field
|
||||
value, e.g. an image tag.
|
||||
|
||||
By default, an SMP _replaces_ values. This is
|
||||
usually desired when the target value is a simple
|
||||
string, but may not be desired when the target
|
||||
value is a list.
|
||||
|
||||
To change this
|
||||
default behavior, add a _directive_. Recognized
|
||||
directives in YAML patches are _replace_ (the default)
|
||||
and _delete_ (see [these notes][strategic-merge]).
|
||||
|
||||
Note that for custom resources, SMPs are treated as
|
||||
[json merge patches][JSONMergePatch].
|
||||
|
||||
Fun fact - any resource file can be used as
|
||||
an SMP, overwriting matching fields in another
|
||||
resource with the same group/version/kind/name,
|
||||
but leaving all other fields as they were.
|
||||
|
||||
TODO(monopole): add ptr to example.
|
||||
|
||||
## patchJson6902
|
||||
|
||||
A _patchJson6902_ refers to a kubernetes [resource] and
|
||||
a [JSONPatch] specifying how to change the resource.
|
||||
|
||||
A _patchJson6902_ can do almost everything a
|
||||
_patchStrategicMerge_ can do, but with a briefer
|
||||
syntax. See this [example][patchExampleJson6902].
|
||||
|
||||
## plugin
|
||||
|
||||
A chunk of code used by kustomize, but not necessarily
|
||||
compiled into kustomize, to generate and/or transform a
|
||||
kubernetes resource as part of a kustomization.
|
||||
|
||||
Details [here](../../guides/plugins).
|
||||
|
||||
## resource
|
||||
|
||||
A _resource_ in the context of a REST-ful API is the
|
||||
target object of an HTTP operation like _GET_, _PUT_ or
|
||||
_POST_. k8s offers a REST-ful API surface to interact
|
||||
with clients.
|
||||
|
||||
A _resource_, in the context of a kustomization, is a
|
||||
[root] relative path to a [YAML] or [JSON] file
|
||||
describing a k8s API object, like a Deployment or a
|
||||
ConfigMap, or it's a path to a kustomization, or a URL
|
||||
that resolves to a kustomization.
|
||||
|
||||
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.
|
||||
|
||||
## root
|
||||
|
||||
See [kustomization root][root].
|
||||
|
||||
## 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 `kustomize build`, e.g.:
|
||||
|
||||
> ```
|
||||
> kustomize build $target
|
||||
> ```
|
||||
|
||||
`$target` must be a path or a url to a [kustomization].
|
||||
|
||||
The target contains, or refers to, all the information
|
||||
needed to create customized resources to send to the
|
||||
[apply] operation.
|
||||
|
||||
A target can be a [base] or an [overlay].
|
||||
|
||||
## transformer
|
||||
|
||||
A transformer can modify a resource, or merely
|
||||
visit it and collect information about it in the
|
||||
course of a `kustomize build`.
|
||||
|
||||
## variant
|
||||
|
||||
A _variant_ 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 variants.
|
||||
|
||||
The _staging_ variant 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_ variant 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.
|
||||
|
||||
@@ -9,4 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/" />
|
||||
|
||||
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,11 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/bases/" />
|
||||
|
||||
{{% pageinfo color="warning" %}}
|
||||
The `bases` field was deprecated in v2.1.0
|
||||
{{% /pageinfo %}}
|
||||
|
||||
Move entries into the [resources](/kustomize/api-reference/kustomization/resources)
|
||||
field. This allows bases - which are still a
|
||||
[central concept](/kustomize/api-reference/glossary#base) - to be
|
||||
ordered relative to other input resources.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,52 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/commonannotations/" />
|
||||
|
||||
Add annotations to all resources. If the annotation key is already present on the resource,
|
||||
the value will be overridden.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonAnnotations:
|
||||
oncallPager: 800-555-1212
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
### File Input
|
||||
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonAnnotations:
|
||||
oncallPager: 800-555-1212
|
||||
|
||||
resources:
|
||||
- deploy.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
spec:
|
||||
...
|
||||
```
|
||||
|
||||
### Build Output
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
annotations:
|
||||
oncallPager: 800-555-1212
|
||||
spec:
|
||||
...
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,97 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/commonlabels/" />
|
||||
|
||||
|
||||
Add labels and selectors to all resources. If the label key already is present on the resource,
|
||||
the value will be overridden.
|
||||
|
||||
{{% pageinfo color="warning" %}}
|
||||
Selectors for resources such as Deployments and Services shouldn't be changed once the
|
||||
resource has been applied to a cluster.
|
||||
|
||||
Changing commonLabels to live resources could result in failures.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonLabels:
|
||||
someName: someValue
|
||||
owner: alice
|
||||
app: bingo
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
### File Input
|
||||
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
commonLabels:
|
||||
someName: someValue
|
||||
owner: alice
|
||||
app: bingo
|
||||
|
||||
resources:
|
||||
- deploy.yaml
|
||||
- service.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
```
|
||||
|
||||
```yaml
|
||||
# service.yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: example
|
||||
```
|
||||
|
||||
### Build Output
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
labels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
name: example
|
||||
spec:
|
||||
selector:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
labels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
name: example
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: bingo
|
||||
owner: alice
|
||||
someName: someValue
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,4 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/components/" />
|
||||
|
||||
Please see <https://kubectl.docs.kubernetes.io/guides/config_management/components/>
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,87 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/configmapgenerator/" />
|
||||
|
||||
|
||||
Each entry in this list results in the creation of
|
||||
one ConfigMap resource (it's a generator of n maps).
|
||||
|
||||
The example below creates four ConfigMaps:
|
||||
|
||||
- first, with the names and contents of the given files
|
||||
- second, with key/value as data using key/value pairs from files
|
||||
- third, also with key/value as data, directly specified using `literals`
|
||||
- and a fourth, which sets an annotation and label via `options` for that single ConfigMap
|
||||
|
||||
Each configMapGenerator item accepts a parameter of
|
||||
`behavior: [create|replace|merge]`.
|
||||
This allows an overlay to modify or
|
||||
replace an existing configMap from the parent.
|
||||
|
||||
Also, each entry has an `options` field, that has the
|
||||
same subfields as the kustomization file's `generatorOptions` field.
|
||||
|
||||
This `options` field allows one to add labels and/or
|
||||
annotations to the generated instance, or to individually
|
||||
disable the name suffix hash for that instance.
|
||||
Labels and annotations added here will not be overwritten
|
||||
by the global options associated with the kustomization
|
||||
file `generatorOptions` field. However, due to how
|
||||
booleans behave, if the global `generatorOptions` field
|
||||
specifies `disableNameSuffixHash: true`, this will
|
||||
trump any attempt to locally override it.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
# These labels are added to all configmaps and secrets.
|
||||
generatorOptions:
|
||||
labels:
|
||||
fruit: apple
|
||||
|
||||
configMapGenerator:
|
||||
- name: my-java-server-props
|
||||
behavior: merge
|
||||
files:
|
||||
- application.properties
|
||||
- more.properties
|
||||
- name: my-java-server-env-file-vars
|
||||
envs:
|
||||
- my-server-env.properties
|
||||
- more-server-props.env
|
||||
- name: my-java-server-env-vars
|
||||
literals:
|
||||
- JAVA_HOME=/opt/java/jdk
|
||||
- JAVA_TOOL_OPTIONS=-agentlib:hprof
|
||||
options:
|
||||
disableNameSuffixHash: true
|
||||
labels:
|
||||
pet: dog
|
||||
- name: dashboards
|
||||
files:
|
||||
- mydashboard.json
|
||||
options:
|
||||
annotations:
|
||||
dashboard: "1"
|
||||
labels:
|
||||
app.kubernetes.io/name: "app1"
|
||||
```
|
||||
|
||||
It is also possible to
|
||||
[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file)
|
||||
to set a name different than the filename.
|
||||
|
||||
The example below creates a ConfigMap
|
||||
with the name of file as `myFileName.ini`
|
||||
while the _actual_ filename from which the
|
||||
configmap is created is `whatever.ini`.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
configMapGenerator:
|
||||
- name: app-whatever
|
||||
files:
|
||||
- myFileName.ini=whatever.ini
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,36 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/crds/" />
|
||||
|
||||
|
||||
Each entry in this list should be a relative path to
|
||||
a file for custom resource definition (CRD).
|
||||
|
||||
The presence of this field is to allow kustomize be
|
||||
aware of CRDs and apply proper
|
||||
transformation for any objects in those types.
|
||||
|
||||
Typical use case: A CRD object refers to a
|
||||
ConfigMap object. In a kustomization, the ConfigMap
|
||||
object name may change by adding namePrefix,
|
||||
nameSuffix, or hashing. The name reference for this
|
||||
ConfigMap object in CRD object need to be updated
|
||||
with namePrefix, nameSuffix, or hashing in the
|
||||
same way.
|
||||
|
||||
The annotations can be put into openAPI definitions are:
|
||||
|
||||
- "x-kubernetes-annotation": ""
|
||||
- "x-kubernetes-label-selector": ""
|
||||
- "x-kubernetes-identity": ""
|
||||
- "x-kubernetes-object-ref-api-version": "v1",
|
||||
- "x-kubernetes-object-ref-kind": "Secret",
|
||||
- "x-kubernetes-object-ref-name-key": "name",
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
crds:
|
||||
- crds/typeA.yaml
|
||||
- crds/typeB.yaml
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,24 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/generatoroptions/" />
|
||||
|
||||
|
||||
Additionally, generatorOptions can be set on a per resource level within each
|
||||
generator. For details on per-resource generatorOptions usage see
|
||||
[field-name-configMapGenerator](/kustomize/api-reference/kustomization/configmapgenerator) and See [field-name-secretGenerator](/kustomize/api-reference/kustomization/secretgenerator).
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
generatorOptions:
|
||||
# labels to add to all generated resources
|
||||
labels:
|
||||
kustomize.generated.resources: somevalue
|
||||
# annotations to add to all generated resources
|
||||
annotations:
|
||||
kustomize.generated.resource: somevalue
|
||||
# disableNameSuffixHash is true disables the default behavior of adding a
|
||||
# suffix to the names of generated resources that is a hash of
|
||||
# the resource contents.
|
||||
disableNameSuffixHash: true
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,48 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/images/" />
|
||||
|
||||
|
||||
Images modify the name, tags and/or digest for images without creating patches. E.g. Given this
|
||||
kubernetes Deployment fragment:
|
||||
|
||||
```yaml
|
||||
kind: Deployment
|
||||
...
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: mypostgresdb
|
||||
image: postgres:8
|
||||
- name: nginxapp
|
||||
image: nginx:1.7.9
|
||||
- name: myapp
|
||||
image: my-demo-app:latest
|
||||
- name: alpine-app
|
||||
image: alpine:3.7
|
||||
```
|
||||
|
||||
one can change the `image` in the following ways:
|
||||
|
||||
- `postgres:8` to `my-registry/my-postgres:v1`,
|
||||
- nginx tag `1.7.9` to `1.8.0`,
|
||||
- image name `my-demo-app` to `my-app`,
|
||||
- alpine's tag `3.7` to a digest value
|
||||
|
||||
all with the following *kustomization*:
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
images:
|
||||
- name: postgres
|
||||
newName: my-registry/my-postgres
|
||||
newTag: v1
|
||||
- name: nginx
|
||||
newTag: 1.8.0
|
||||
- name: my-demo-app
|
||||
newName: my-app
|
||||
- name: alpine
|
||||
digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,12 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/nameprefix/" />
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
namePrefix: alices-
|
||||
```
|
||||
|
||||
A deployment named `wordpress` would become `alices-wordpress`.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,12 +9,4 @@ description: >
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/namespace/" />
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
namespace: my-namespace
|
||||
```
|
||||
|
||||
Will override the existing namespace if it is set on a resource, or add it
|
||||
if it is not set on a resource.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,13 +9,4 @@ description: >
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/namesuffix/" />
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
nameSuffix: -v2
|
||||
```
|
||||
|
||||
A deployment named `wordpress` would become `wordpress-v2`.
|
||||
|
||||
**Note:** The suffix is appended before the content hash if the resource type is ConfigMap or Secret.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,152 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/patches/" />
|
||||
|
||||
|
||||
[strategic merge]: /kustomize/api-reference/glossary#patchstrategicmerge
|
||||
[JSON]: /kustomize/api-reference/glossary#patchjson6902
|
||||
|
||||
Patches (also call overlays) add or override fields on resources. They are provided using the
|
||||
`patches` Kustomization field.
|
||||
|
||||
The `patches` field contains a list of patches to be applied in the order they are specified.
|
||||
|
||||
Each patch may:
|
||||
|
||||
- be either a [strategic merge] patch, or a [JSON] patch
|
||||
- be either a file, or an inline string
|
||||
- target a single resource or multiple resources
|
||||
|
||||
The patch target selects resources by group, version, kind, name, namespace, labelSelector and
|
||||
annotationSelector. Any resource which matches all the **specified** fields has the patch applied
|
||||
to it (regular expressions).
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patches:
|
||||
- path: patch.yaml
|
||||
target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: deploy.*
|
||||
labelSelector: "env=dev"
|
||||
annotationSelector: "zone=west"
|
||||
- patch: |-
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: new value
|
||||
target:
|
||||
kind: MyKind
|
||||
labelSelector: "env=dev"
|
||||
```
|
||||
|
||||
The `name` and `namespace` fields of the patch target selector are
|
||||
automatically anchored regular expressions. This means that the value `myapp`
|
||||
is equivalent to `^myapp$`.
|
||||
|
||||
Consider the following `deployment.yaml` common for both the examples:
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: the-deployment
|
||||
spec:
|
||||
replicas: 5
|
||||
template:
|
||||
containers:
|
||||
- name: the-container
|
||||
image: registry/conatiner:latest
|
||||
```
|
||||
|
||||
## Example I
|
||||
|
||||
### Intent
|
||||
|
||||
To Make the container image point to a specific version and not to the latest container in the
|
||||
registry.
|
||||
|
||||
### File Input
|
||||
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
resources:
|
||||
- deployment.yaml
|
||||
|
||||
patches:
|
||||
- path: patch.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# patch.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: the-deployment
|
||||
spec:
|
||||
template:
|
||||
containers:
|
||||
- name: the-container
|
||||
image: registry/conatiner:1.0.0
|
||||
```
|
||||
|
||||
### Build Output
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: the-deployment
|
||||
spec:
|
||||
replicas: 5
|
||||
template:
|
||||
containers:
|
||||
- image: registry/conatiner:1.0.0
|
||||
name: the-container
|
||||
```
|
||||
|
||||
## Example II
|
||||
|
||||
### Intent
|
||||
|
||||
To Make the container image point to a specific version and not to the latest container in the
|
||||
registry.
|
||||
|
||||
### File Input
|
||||
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
resources:
|
||||
- deployment.yaml
|
||||
|
||||
patches:
|
||||
- target:
|
||||
kind: Deployment
|
||||
name: the-deployment
|
||||
path: patch.json
|
||||
```
|
||||
|
||||
```yaml
|
||||
# patch.json
|
||||
[
|
||||
{"op": "replace", "path": "/spec/template/containers/0/image", "value": "registry/conatiner:1.0.0"}
|
||||
]
|
||||
|
||||
```
|
||||
|
||||
### Build Output
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: the-deployment
|
||||
spec:
|
||||
replicas: 5
|
||||
template:
|
||||
containers:
|
||||
- image: registry/container:1.0.0
|
||||
name: the-container
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,53 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/patchesstrategicmerge/" />
|
||||
|
||||
|
||||
Each entry in this list should be either a relative
|
||||
file path or an inline content
|
||||
resolving to a partial or complete resource
|
||||
definition.
|
||||
|
||||
The names in these (possibly partial) resource
|
||||
files must match names already loaded via the
|
||||
`resources` field. These entries are used to
|
||||
_patch_ (modify) the known resources.
|
||||
|
||||
Small patches that do one thing are best, e.g. modify
|
||||
a memory request/limit, change an env var in a
|
||||
ConfigMap, etc. Small patches are easy to review and
|
||||
easy to mix together in overlays.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesStrategicMerge:
|
||||
- service_port_8888.yaml
|
||||
- deployment_increase_replicas.yaml
|
||||
- deployment_increase_memory.yaml
|
||||
```
|
||||
|
||||
The patch content can be a inline string as well.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesStrategicMerge:
|
||||
- |-
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: nginx
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nignx:latest
|
||||
```
|
||||
|
||||
Note that kustomize does not support more than one patch
|
||||
for the same object that contain a _delete_ directive. To remove
|
||||
several fields / slice elements from an object create a single
|
||||
patch that performs all the needed deletions.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,67 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/patchesjson6902/" />
|
||||
|
||||
|
||||
Each entry in this list should resolve to a kubernetes object and a JSON patch that will be applied
|
||||
to the object.
|
||||
The JSON patch is documented at <https://tools.ietf.org/html/rfc6902>
|
||||
|
||||
target field points to a kubernetes object within the same kustomization
|
||||
by the object's group, version, kind, name and namespace.
|
||||
path field is a relative file path of a JSON patch file.
|
||||
The content in this patch file can be either in JSON format as
|
||||
|
||||
```json
|
||||
[
|
||||
{"op": "add", "path": "/some/new/path", "value": "value"},
|
||||
{"op": "replace", "path": "/some/existing/path", "value": "new value"}
|
||||
]
|
||||
```
|
||||
|
||||
or in YAML format as
|
||||
|
||||
```yaml
|
||||
- op: add
|
||||
path: /some/new/path
|
||||
value: value
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: new value
|
||||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
path: add_init_container.yaml
|
||||
- target:
|
||||
version: v1
|
||||
kind: Service
|
||||
name: my-service
|
||||
path: add_service_annotation.yaml
|
||||
```
|
||||
|
||||
The patch content can be an inline string as well:
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
patch: |-
|
||||
- op: add
|
||||
path: /some/new/path
|
||||
value: value
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: "new value"
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,40 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/replicas/" />
|
||||
|
||||
|
||||
Given this kubernetes Deployment fragment:
|
||||
|
||||
```
|
||||
# deployment.yaml
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: deployment-name
|
||||
spec:
|
||||
replicas: 3
|
||||
```
|
||||
|
||||
one can change the number of replicas to 5
|
||||
by adding the following to your kustomization:
|
||||
|
||||
```
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
replicas:
|
||||
- name: deployment-name
|
||||
count: 5
|
||||
```
|
||||
|
||||
This field accepts a list, so many resources can
|
||||
be modified at the same time.
|
||||
|
||||
As this declaration does not take in a `kind:` nor a `group:`
|
||||
it will match any `group` and `kind` that has a matching name and
|
||||
that is one of:
|
||||
|
||||
- `Deployment`
|
||||
- `ReplicationController`
|
||||
- `ReplicaSet`
|
||||
- `StatefulSet`
|
||||
|
||||
For more complex use cases, revert to using a patch.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,30 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/resources/" />
|
||||
|
||||
|
||||
Each entry in this list must be a path to a _file_, or a path (or URL) referring to another
|
||||
kustomization _directory_, e.g.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- myNamespace.yaml
|
||||
- sub-dir/some-deployment.yaml
|
||||
- ../../commonbase
|
||||
- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6
|
||||
- deployment.yaml
|
||||
- github.com/kubernets-sigs/kustomize/examples/helloWorld?ref=test-branch
|
||||
```
|
||||
|
||||
Resources will be read and processed in depth-first order.
|
||||
|
||||
Files should contain k8s resources in YAML form. A file may contain multiple resources separated by
|
||||
the document marker `---`. File paths should be specified _relative_ to the directory holding the
|
||||
kustomization file containing the `resources` field.
|
||||
|
||||
[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format
|
||||
|
||||
Directory specification can be relative, absolute, or part of a URL. URL specifications should
|
||||
follow the [hashicorp URL] format. The directory must contain a `kustomization.yaml` file.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,40 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/secretegenerator/" />
|
||||
|
||||
|
||||
Each entry in the argument list results in the creation of one Secret resource (it's a generator of N secrets).
|
||||
|
||||
This works like the [configMapGenerator](/kustomize/api-reference/kustomization/configmapgenerator).
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
secretGenerator:
|
||||
- name: app-tls
|
||||
files:
|
||||
- secret/tls.cert
|
||||
- secret/tls.key
|
||||
type: "kubernetes.io/tls"
|
||||
- name: app-tls-namespaced
|
||||
# you can define a namespace to generate
|
||||
# a secret in, defaults to: "default"
|
||||
namespace: apps
|
||||
files:
|
||||
- tls.crt=catsecret/tls.cert
|
||||
- tls.key=secret/tls.key
|
||||
type: "kubernetes.io/tls"
|
||||
- name: env_file_secret
|
||||
envs:
|
||||
- env.txt
|
||||
type: Opaque
|
||||
- name: secret-with-annotation
|
||||
files:
|
||||
- app-config.yaml
|
||||
type: Opaque
|
||||
options:
|
||||
annotations:
|
||||
app_config: "true"
|
||||
labels:
|
||||
app.kubernetes.io/name: "app2"
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,112 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/vars/" />
|
||||
|
||||
|
||||
Vars are used to capture text from one resource's field
|
||||
and insert that text elsewhere - a reflection feature.
|
||||
|
||||
For example, suppose one specifies the name of a k8s Service
|
||||
object in a container's command line, and the name of a
|
||||
k8s Secret object in a container's environment variable,
|
||||
so that the following would work:
|
||||
|
||||
```yaml
|
||||
# consider it is a deployment
|
||||
containers:
|
||||
- image: myimage
|
||||
command: ["start", "--host", "$(MY_SERVICE_NAME)"]
|
||||
env:
|
||||
- name: SECRET_TOKEN
|
||||
value: $(SOME_SECRET_NAME)
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /healthz
|
||||
# it enables the parser to lookup this field
|
||||
port: $(APP_PORT)
|
||||
```
|
||||
|
||||
To do so, add an entry to `vars:` as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
configMapGenerator:
|
||||
- name: my-config
|
||||
literals:
|
||||
- MY_PORT=8080
|
||||
|
||||
vars:
|
||||
- name: SOME_SECRET_NAME
|
||||
objref:
|
||||
kind: Secret
|
||||
name: my-secret
|
||||
apiVersion: v1
|
||||
- name: MY_SERVICE_NAME
|
||||
objref:
|
||||
kind: Service
|
||||
name: my-service
|
||||
apiVersion: v1
|
||||
fieldref:
|
||||
fieldpath: metadata.name
|
||||
- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY
|
||||
objref:
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
apiVersion: apps/v1
|
||||
fieldref:
|
||||
fieldpath: spec.template.spec.restartPolicy
|
||||
# it exports a value as `APP_PORT`
|
||||
# from `ConfigMap` named `my-config`
|
||||
# in `data.MY_PORT`
|
||||
- name: APP_PORT
|
||||
objref:
|
||||
kind: ConfigMap
|
||||
name: my-config
|
||||
apiVersion: v1
|
||||
fieldref:
|
||||
fieldpath: data.MY_PORT
|
||||
|
||||
configurations:
|
||||
- lookup.yaml
|
||||
```
|
||||
|
||||
Define the consuming resource(s) and the field(s) inside need to lookup.
|
||||
|
||||
```yaml
|
||||
# lookup.yaml
|
||||
varReference:
|
||||
# the path of field that you want the parser to lookups and replace.
|
||||
- path: spec/template/spec/containers/livenessProbe/httpGet/port
|
||||
kind: Deployment
|
||||
```
|
||||
|
||||
A var is a tuple of variable name, object
|
||||
reference and field reference within that object.
|
||||
That's where the text is found.
|
||||
|
||||
The field reference is optional; it defaults to
|
||||
`metadata.name`, a normal default, since kustomize
|
||||
is used to generate or modify the names of
|
||||
resources.
|
||||
|
||||
At time of writing, only string type fields are
|
||||
supported. No ints, bools, arrays etc. It's not
|
||||
possible to, say, extract the name of the image in
|
||||
container number 2 of some pod template.
|
||||
|
||||
A variable reference, i.e. the string '$(FOO)',
|
||||
can only be placed in particular fields of
|
||||
particular objects as specified by kustomize's
|
||||
configuration data.
|
||||
|
||||
The default config data for vars is at [/api/konfig/builtinpluginconsts/varreference.go](https://github.com/kubernetes-sigs/kustomize/blob/master/api/konfig/builtinpluginconsts/varreference.go)
|
||||
Long story short, the default targets are all
|
||||
container command args and env value fields.
|
||||
|
||||
Vars should _not_ be used for inserting names in
|
||||
places where kustomize is already handling that
|
||||
job. E.g., a Deployment may reference a ConfigMap
|
||||
by name, and if kustomize changes the name of a
|
||||
ConfigMap, it knows to change the name reference
|
||||
in the Deployment.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -7,3 +7,5 @@ menu:
|
||||
---
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/blog/" />
|
||||
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -5,3 +5,5 @@ weight: 20
|
||||
---
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/blog/releases" />
|
||||
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,51 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/bugs" />
|
||||
|
||||
|
||||
[krusty package]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty
|
||||
[reusable custom transformer test]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty/customconfigreusable_test.go
|
||||
|
||||
File issues as desired, but if you've found a problem
|
||||
with how `kustomize build` works, please report
|
||||
|
||||
* the output of `kustomize version`,
|
||||
* the input (the content of `kustomization.yaml`
|
||||
and any files it refers to),
|
||||
* the expected YAML output.
|
||||
|
||||
## If you have `go` installed
|
||||
|
||||
kustomize has a simple test harness in the [krusty
|
||||
package] for specifying a kustomization's input and the
|
||||
expected output.
|
||||
|
||||
Copy one of those tests, e.g. this [reusable custom
|
||||
transformer test], to a new test file in the
|
||||
krusty package.
|
||||
|
||||
Insert the inputs you want to use, and run it as
|
||||
you'd run the reusable custom transformer test:
|
||||
|
||||
```
|
||||
(cd api; go test -run TestReusableCustomTransformers ./krusty)
|
||||
```
|
||||
|
||||
The output will demonstrate the bug or missing feature.
|
||||
|
||||
Record this output in the test file in a call to
|
||||
`AssertActualEqualsExpected`, per all the other tests
|
||||
in the [krusty package]. This makes the test pass,
|
||||
albeit with output demonstrating behavior you
|
||||
presumably want to change.
|
||||
|
||||
Send the new test in a PR, along with commentary (in
|
||||
the test) on what you'd prefer to see.
|
||||
|
||||
The person who fixes the bug then has a clear bug
|
||||
reproduction and a test to modify when the bug is
|
||||
fixed.
|
||||
|
||||
Any bug fix first requires a test demonstrating the bug
|
||||
(so we have permanent regression coverage), so if the
|
||||
_bug reporter_ does this, it saves time and avoids
|
||||
misunderstandings.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,18 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/community" />
|
||||
|
||||
|
||||
[CLI special interest group]: https://github.com/kubernetes/community/tree/master/sig-cli#cli-special-interest-group
|
||||
[contributor roles]: https://github.com/kubernetes/community/blob/master/community-membership.md#community-membership
|
||||
[mailing list]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli
|
||||
[bi-weekly meetings]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit?usp=sharing
|
||||
[slack channel]: https://kubernetes.slack.com/messages/sig-cli
|
||||
|
||||
Kustomize is a sub project of the Kubernetes [CLI special interest group] and follows the Kubernetes
|
||||
project [contributor roles].
|
||||
|
||||
If you are interested in contributing towards Kustomize or getting more involved with the community:
|
||||
|
||||
- join the [mailing list] and reach out
|
||||
- join the [slack channel] and reach out
|
||||
- attend one of the [bi-weekly meetings] (alternating Wednesdays at 9:00am Pacific Time)
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,76 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/docs" />
|
||||
|
||||
|
||||
Kustomize uses [Docsy](https://www.docsy.dev) for the site, and was
|
||||
forked from the [docsy-example](https://github.com/google/docsy-example)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Install hugo](https://gohugo.io/getting-started/installing/#fetch-from-github)
|
||||
- Clone kustomize
|
||||
- `git clone git@github.com:kubernetes-sigs/kustomize && cd kustomize/`
|
||||
|
||||
## Development
|
||||
|
||||
The doc input files are in the `site` directory. The site can be hosted locally using
|
||||
`hugo serve`.
|
||||
|
||||
```shell script
|
||||
cd site/
|
||||
hugo serve
|
||||
```
|
||||
|
||||
```shell script
|
||||
...
|
||||
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
|
||||
Web Server is available at http://localhost:1313/kustomize/ (bind address 127.0.0.1)
|
||||
```
|
||||
|
||||
## Publishing
|
||||
|
||||
Hugo compiles the files under `site` Hugo into html which it puts in the `docs` folder:
|
||||
|
||||
```shell script
|
||||
cd site/
|
||||
hugo
|
||||
```
|
||||
|
||||
```shell script
|
||||
| EN
|
||||
-------------------+-----
|
||||
Pages | 99
|
||||
Paginator pages | 0
|
||||
Non-page files | 0
|
||||
Static files | 47
|
||||
Processed images | 0
|
||||
Aliases | 2
|
||||
Sitemaps | 1
|
||||
Cleaned | 0
|
||||
```
|
||||
|
||||
Add the `site/` and `docs/` folders to a commit, then create a PR.
|
||||
|
||||
## Publishing docs to your kustomize fork
|
||||
|
||||
It is possible to have the kustomize docs published to your forks github pages.
|
||||
|
||||
### Setup GitHub Pages for the fork
|
||||
|
||||
1. Go to the *forked repo's* **Settings** tab
|
||||
- e.g. [https://github.com/pwittrock/kustomize](https://github.com/pwittrock/kustomize)
|
||||
2. Go to the **GitHub Pages** section
|
||||
3. Set the source to master branch **/docs folder**
|
||||
|
||||
### Publish to the fork's GitHub Pages
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
Changes must be pushed to the fork's **master branch** to be served as the fork's GitHub Page.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
1. Make a change to a file under `site/content`
|
||||
2. Run `hugo` from the `site/` directory
|
||||
3. Add the `site` and `docs` directories to the **master branch**
|
||||
4. Commit and push the changes to the *remote fork's* **master branch**
|
||||
5. After a few minutes, the docs should be served from the fork's GitHub Page
|
||||
- e.g. [https://pwittrock.github.io/kustomize/](https://pwittrock.github.io/kustomize/)
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,32 +8,4 @@ description: >
|
||||
---
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/features" />
|
||||
|
||||
|
||||
[issue]: https://github.com/kubernetes-sigs/kustomize/issues
|
||||
[sig-cli]: /kustomize/contributing/community/
|
||||
[meeting agenda]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit#heading=h.himo1st0tqyy
|
||||
[KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli
|
||||
[table-driven]: https://github.com/kubernetes-sigs/kustomize/blob/a8b9741866cf8e0c43e643ab7a9f40a3bd7e2a4d/api/filters/imagetag/imagetag_test.go#L15
|
||||
[eschewed feature list]: https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/
|
||||
[kind/feature]: https://github.com/kubernetes-sigs/kustomize/labels/kind%2Ffeature
|
||||
|
||||
Following is the process for proposing a new Kustomize feature:
|
||||
|
||||
1. Check the [eschewed feature list] to see if the feature has already been proposed
|
||||
2. File an [issue] describing the desired feature
|
||||
- label it [kind/feature]
|
||||
- the motivation for the feature
|
||||
- example of how you would accomplish the motivating task *without* the feature
|
||||
- example of how you would accomplish the motivating task *with* the feature
|
||||
3. Email the [sig-cli] mailing list with the issue
|
||||
4. Present the issue at [sig-cli] bi-weekly meeting on Zoom
|
||||
- add it to the [meeting agenda] doc
|
||||
- be present to discuss the feature
|
||||
- response may be -- move forward with a PoC, not to move forward, defer and come back later,
|
||||
or more information is needed.
|
||||
5. Address the feedback on the issue
|
||||
- Possibly write a KEP for tracking the feature
|
||||
6. Implement the feature and send a PR
|
||||
- Add [table-driven] tests
|
||||
- Expect comments on the PR within 2 weeks
|
||||
7. Kustomize team will release the kustomize `api` and `kustomize` modules
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,60 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/howitworks" />
|
||||
|
||||
|
||||
{{% pageinfo color="info" %}}
|
||||
To build kustomize using the locally modified modules, `replace` statements must be added to
|
||||
the `kustomize/go.mod`.
|
||||
|
||||
e.g. if code in `api` was modified, a `replace` statement would need to be added for the
|
||||
`kustomize/api` module.
|
||||
{{% /pageinfo %}}
|
||||
|
||||
Call stack when running `kustomize build`, with links to code.
|
||||
|
||||
## Run build
|
||||
|
||||
* [RunBuild](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L121)
|
||||
* [MakeKustomizer](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L32)
|
||||
* [Run](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L47): performs a kustomization. It uses its internal filesystem reference to read the file at the given path argument, interpret it as a kustomization.yaml file, perform the kustomization it represents, and return the resulting resources.
|
||||
* Create factories
|
||||
* [tranformer.NewFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/k8sdeps/transformer/factory.go#L17)
|
||||
* [resmap.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resmap/factory.go#L21)
|
||||
* [resource.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resource/factory.go#L23)
|
||||
* [kustruct.NewKunstructuredFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/kunstruct/factory.go#L28)
|
||||
* [loader.NewLoader](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/loader/loader.go#L19)
|
||||
* [validator.NewKustValidator](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/validator/validators.go#L23)
|
||||
* [NewKustTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L38)
|
||||
* [Load](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L54)
|
||||
* [MakeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L109): details in next section
|
||||
* [emitResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L143)
|
||||
|
||||
## Make resource map
|
||||
|
||||
* [makeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L117)
|
||||
* [AccumulateTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L196): returns a new ResAccumulator, holding customized resources and the data/rules used to do so. The name back references and vars are not yet fixed.
|
||||
* [accummulateResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L302): fills the given resourceAccumulator with resources read from the given list of paths.
|
||||
* Merge config from builtin and CRDs
|
||||
* [runGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L239)
|
||||
* [configureBuiltinGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L28)
|
||||
* ConfigMapGenerator
|
||||
* SecretGenerator
|
||||
* [configureExternalGenerators]()
|
||||
* Iterate all generators
|
||||
* [runTransfomers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L274)
|
||||
* [configureBuiltinTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L44)
|
||||
* PatchStrategicMergeTransformer
|
||||
* PatchTransformer
|
||||
* NamespaceTransformer
|
||||
* PrefixSuffixTransformer
|
||||
* LabelTransformer
|
||||
* AnnotationsTransformer
|
||||
* PatchJson6902Transformer
|
||||
* ReplicaCountTransformer
|
||||
* ImageTagTransformer
|
||||
* [configureExternalTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L291)
|
||||
* [MergeVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L64)
|
||||
* The following steps must be done last, not as part of the recursion implicit in AccumulateTarget.
|
||||
* [addHashesToNames](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L153)
|
||||
* [FixBackReferences](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L160): Given that names have changed (prefixs/suffixes added), fix all the back references to those names.
|
||||
* [ResolveVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L141)
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,40 +8,4 @@ description: >
|
||||
---
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/mac" />
|
||||
|
||||
First install the tools to build and run tests
|
||||
|
||||
### Install go 1.13
|
||||
|
||||
[Instructions](https://golang.org/doc/install)
|
||||
|
||||
Add `go` to your PATH
|
||||
|
||||
### Install kubeval
|
||||
|
||||
[Instructions](https://github.com/instrumenta/kubeval)
|
||||
|
||||
```sh
|
||||
go get github.com/instrumenta/kubeval
|
||||
```
|
||||
|
||||
Add `kubeval` to your PATH
|
||||
|
||||
### Install gnu tools
|
||||
|
||||
[Instructions](https://www.topbug.net/blog/2013/04/14/install-and-use-gnu-command-line-tools-in-mac-os-x/)
|
||||
|
||||
```sh
|
||||
brew install coreutils wget gnu-sed tree
|
||||
```
|
||||
|
||||
Add the new tools to your PATH
|
||||
|
||||
## Make everything
|
||||
|
||||
Verify your install by running `make`:
|
||||
|
||||
```sh
|
||||
make
|
||||
```
|
||||
|
||||
Be default, this runs all tests needed to qualify a pull request.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,60 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/contributing/kustomize/windows" />
|
||||
|
||||
This is the PowerShell script to run all go tests for Kustomize on a windows based platform which mimics /build/pre-commit.sh
|
||||
|
||||
## Pre-Reqs
|
||||
|
||||
- PowerShell installed
|
||||
- PowerShell Core is supported
|
||||
- go installed
|
||||
- golangci-lint installed
|
||||
- mdrip installed
|
||||
|
||||
This script should output to the current console and return an exit code if all tests are successful(0) or any failed(1).
|
||||
|
||||
### If you are tryin to run these tests locally you can follow these instructions
|
||||
|
||||
Assume:
|
||||
|
||||
- Running a stock Windows 10 system
|
||||
- Local Admin rights.
|
||||
- You can open [PowerShell as administrator](http://lmgtfy.com/?iie=1&q=How+to+open+powershell+as+administrator)
|
||||
- You should be knowledgeable enough to pull source for packages into your GO ```src``` directory
|
||||
- Yes, this means you also need to know a bit about **git** usually
|
||||
|
||||
#### Step 1 - Install Go
|
||||
|
||||
- [Install Go](https://golang.org/dl/) - please use the msi
|
||||
- If you use chocolatey - it's using the zip not msi and assumptions on where go is located are made for you.
|
||||
|
||||
#### Step 2 - Install Go Packages
|
||||
|
||||
- Open new PowerShell Administrative window
|
||||
- Install golangci-lint
|
||||
- ```go get -u github.com/golangci/golangci-lint/cmd/golangci-lint```
|
||||
- Install mdrip
|
||||
- ```go get github.com/monopole/mdrip```
|
||||
|
||||
You should now be able to issue these commands and see comparable responses
|
||||
|
||||
```
|
||||
C:\...> golangci-lint --help
|
||||
Smart, fast linters runner. Run it in cloud for every GitHub pull request on https://golangci.com
|
||||
...
|
||||
|
||||
C:\...> mdrip --help
|
||||
Usage: C:\_go\bin\mdrip.exe {fileName}...
|
||||
...
|
||||
```
|
||||
|
||||
#### Step 3 - Get Source and Test
|
||||
|
||||
- In your GoRoot src
|
||||
- ```Example: C:\_go\src```
|
||||
- Navigate to the Kustomize `travis` directory
|
||||
- ```Example: C:\_go\src\sigs.k8s.io\kustomize\scripts```
|
||||
- Now Execute:
|
||||
- ```.\Invoke-PreCommit.ps1```
|
||||
|
||||
This should run all pre-commit tests thus defined in the script.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,75 +9,4 @@ menu:
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/faq/kustomize/" />
|
||||
|
||||
## kubectl doesn't have the latest kustomize, when will it be updated?
|
||||
|
||||
TLDR: This is blocked on either moving kubectl into its own repo, or changing its dependencies. ETA k8s ~1.20.
|
||||
|
||||
The adoption of go modules in the kubernetes/kubernetes repo broke the update process for kustomize.
|
||||
This is due to the kustomize libraries depending on the kubernetes apimachinery libraries, which are
|
||||
published out of the kubernetes staging directory.
|
||||
|
||||
2 pieces of work are underway which will allow kustomize to be updated in kubectl:
|
||||
|
||||
- migrating kubectl out of kubernetes/kubernetes (expected Kubernetes ~1.20)
|
||||
- migrating kustomize off of the apimachinery libraries (expected Kuberntes ~1.20)
|
||||
- [2506](https://github.com/kubernetes-sigs/kustomize/issues/2506)
|
||||
|
||||
Once either of these issues is resolved we will then update kubectl with the latest kustomize version.
|
||||
|
||||
## security: file 'foo' is not in or below 'bar'
|
||||
|
||||
v2.0 added a security check that prevents
|
||||
kustomizations from reading files outside their own
|
||||
directory root.
|
||||
|
||||
This was meant to help protect the person inclined to
|
||||
download kustomization directories from the web and use
|
||||
them without inspection to control their production
|
||||
cluster
|
||||
(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693),
|
||||
[#700](https://github.com/kubernetes-sigs/kustomize/pull/700),
|
||||
[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and
|
||||
[#998](https://github.com/kubernetes-sigs/kustomize/pull/998))
|
||||
|
||||
Resources (including configmap and secret generators)
|
||||
can _still be shared_ via the recommended best practice
|
||||
of placing them in a directory with their own
|
||||
kustomization file, and referring to this directory as a
|
||||
[`base`](/kustomize/api-reference/glossary#base) from any kustomization that
|
||||
wants to use it. This encourages modularity and
|
||||
relocatability.
|
||||
|
||||
To disable this, use v3, and the `load_restrictor` flag:
|
||||
|
||||
```
|
||||
kustomize build --load_restrictor none $target
|
||||
```
|
||||
|
||||
## Some field is not transformed by kustomize
|
||||
|
||||
Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc.
|
||||
|
||||
The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g.
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
configurations:
|
||||
- kustomizeconfig.yaml
|
||||
```
|
||||
|
||||
The configuration directive allows customization of the following transformers:
|
||||
|
||||
```yaml
|
||||
commonAnnotations: []
|
||||
commonLabels: []
|
||||
nameprefix: []
|
||||
namespace: []
|
||||
varreference: []
|
||||
namereference: []
|
||||
images: []
|
||||
replicas: []
|
||||
```
|
||||
|
||||
To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,156 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/faq/kustomize/eschewedfeatures/" />
|
||||
|
||||
The maintainers established this list to
|
||||
place bounds on the kustomize feature
|
||||
set. The bounds can be changed with
|
||||
a consensus on the risks.
|
||||
|
||||
For a bigger picture about why kustomize
|
||||
does some things and not others, see the
|
||||
glossary entry for [DAM].
|
||||
|
||||
## Removal directives
|
||||
|
||||
`kustomize` supports configurations that can be reasoned about as
|
||||
_compositions_ or _mixins_ - concepts that are widely accepted as
|
||||
a best practice in various programming languages.
|
||||
|
||||
To this end, `kustomize` offers various _addition_ directives.
|
||||
One may add labels, annotations, patches, resources, bases, etc.
|
||||
Corresponding _removal_ directives are not offered.
|
||||
|
||||
Removal semantics would introduce many possibilities for
|
||||
inconsistency, and the need to add code to detect, report and
|
||||
reject it. It would also allow, and possibly encourage,
|
||||
unnecessarily complex configuration layouts.
|
||||
|
||||
When faced with a situation where removal is desirable, it's
|
||||
always possible to remove things from a base like labels and
|
||||
annotations, and/or split multi-resource manifests into individual
|
||||
resource files - then add things back as desired via the
|
||||
[kustomization].
|
||||
|
||||
If the underlying base is outside of one's control, an [OTS
|
||||
workflow] is the recommended best practice. Fork the base, remove
|
||||
what you don't want and commit it to your private fork, then use
|
||||
kustomize on your fork. As often as desired, use _git rebase_ to
|
||||
capture improvements from the upstream base.
|
||||
|
||||
## Unstructured edits
|
||||
|
||||
_Structured edits_ are changes controlled by
|
||||
knowledge of the k8s API, and YAML or JSON syntax.
|
||||
|
||||
Most edits performed by kustomize can be expressed as
|
||||
[JSON patches] or [SMP patches].
|
||||
Those can be verbose, so common patches,
|
||||
like adding labels or annotatations, get dedicated
|
||||
transformer plugins - `LabelTransformer`,
|
||||
`AnnotationsTransformer`, etc.
|
||||
These accept relatively simple YAML configuration
|
||||
allowing easy targeting of any number of resources.
|
||||
|
||||
Another class of edits take data from one specific
|
||||
object's field and use it in another (e.g. a service
|
||||
object's name found and copied into a container's
|
||||
command line). These reflection-style edits
|
||||
are called _replacements_.
|
||||
|
||||
The above edits create valid output given valid input,
|
||||
and can provide syntactically and semantically
|
||||
informed error messages if inputs are invalid.
|
||||
|
||||
_Unstructured edits_, edits that don't limit
|
||||
themselves to a syntax or object structure,
|
||||
come in many forms. A common one in the
|
||||
configuration domain is the template or
|
||||
parameterization approach.
|
||||
|
||||
In this technique, the source
|
||||
material is sprinkled with strings of the
|
||||
form `${VAR}`. A scanner replaces them
|
||||
with a value taken from a map using `VAR`
|
||||
as the map key. It's trivial to implement.
|
||||
|
||||
kustomize eschews parameterization, because
|
||||
|
||||
- The source yaml gets polluted with `$VARs`
|
||||
and can no longed be applied as is
|
||||
to the cluster (it _must_ be processed).
|
||||
- The source material is no longer structured,
|
||||
making it unusable with any YAML processor.
|
||||
It's no longer _data_, it's now logic that
|
||||
must be compiled.
|
||||
- Errors in the output are disconnected from
|
||||
the edit that caused it.
|
||||
- The input becomes [unintelligible] as the project
|
||||
scales in any number of dimensions (resource
|
||||
count, cluster count, environment count, etc.)
|
||||
|
||||
Kustomizations are meant to be sharable and stackable.
|
||||
Imagine tracing down a problem rooted in a
|
||||
clever set of stacked regexp replacements
|
||||
performed by various overlays on some remote base.
|
||||
We've used such systems, and never want to again.
|
||||
|
||||
Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet,
|
||||
etc.) provide varying degrees of unstructured editting
|
||||
and/or embedded languages, and can be used instead
|
||||
of, or in a pipe with, kustomize. If you want to
|
||||
go all-in on _configuration as a language_, consider [cue].
|
||||
|
||||
kustomize is going to stick to YAML in / YAML out.
|
||||
|
||||
## Build-time side effects from CLI args or env variables
|
||||
|
||||
`kustomize` supports the best practice of storing one's
|
||||
entire configuration in a version control system.
|
||||
|
||||
Changing `kustomize build` configuration output as a result
|
||||
of additional arguments or flags to `build`, or by
|
||||
consulting shell environment variable values in `build`
|
||||
code, would frustrate that goal.
|
||||
|
||||
`kustomize` insteads offers [kustomization] file `edit`
|
||||
commands. Like any shell command, they can accept
|
||||
environment variable arguments.
|
||||
|
||||
For example, to set the tag used on an image to match an
|
||||
environment variable, run
|
||||
|
||||
```
|
||||
kustomize edit set image nginx:$MY_NGINX_VERSION
|
||||
```
|
||||
|
||||
as part of some encapsulating work flow executed before
|
||||
`kustomize build`.
|
||||
|
||||
## Globs in kustomization files
|
||||
|
||||
`kustomize` supports the best practice of storing one's
|
||||
entire configuration in a version control system.
|
||||
|
||||
Globbing the local file system for files not explicitly
|
||||
declared in the [kustomization] file at `kustomize build` time
|
||||
would violate that goal.
|
||||
|
||||
Allowing globbing in a kustomization file would also introduce
|
||||
the same problems as allowing globbing in [java import]
|
||||
declarations or BUILD/Makefile dependency rules.
|
||||
|
||||
`kustomize` will instead provide kustomization file editting
|
||||
commands that accept globbed arguments, expand them at _edit
|
||||
time_ relative to the local file system, and store the resulting
|
||||
explicit names into the kustomization file.
|
||||
|
||||
[base]: /kustomize/api-reference/glossary#base
|
||||
[DAM]: /kustomize/api-reference/glossary#declarative-application-management
|
||||
[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards
|
||||
[JSON patches]: /kustomize/api-reference/glossary#patchjson6902
|
||||
[kustomization]: /kustomize/api-reference/glossary#kustomization
|
||||
[OTS workflow]: /kustomize/api-reference/glossary#off-the-shelf-configuration
|
||||
[SMP patches]: /kustomize/api-reference/glossary#patchstrategicmerge
|
||||
[parameterization pitfall discussion]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#parameterization-pitfalls
|
||||
[unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml
|
||||
[cue]: https://cuelang.org/
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -7,266 +7,4 @@ type: docs
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/faq/kustomize/versioningpolicy/" />
|
||||
|
||||
Running `kustomize` means one is running a
|
||||
particular version of a program (a CLI), using a
|
||||
particular version of underlying packages (a Go
|
||||
API), and reading a particular version of a
|
||||
[kustomization] file.
|
||||
|
||||
> If you're having trouble with `go get`, please
|
||||
> read [Go API Versioning](#go-api-versioning)
|
||||
> and be patient.
|
||||
|
||||
## CLI Program Versioning
|
||||
|
||||
The command `kustomize version` prints a three
|
||||
field version tag (e.g. `v3.0.0`) that aspires to
|
||||
[semantic versioning].
|
||||
|
||||
This notion of semver applies only to the CLI;
|
||||
the command names, their arguments and their flags.
|
||||
|
||||
The major version changes when some backward
|
||||
incompatibility appears in how the commands
|
||||
behave.
|
||||
|
||||
### Installation
|
||||
|
||||
See the [installation docs](INSTALL.md).
|
||||
|
||||
## Go API Versioning
|
||||
|
||||
The public methods in the public packages
|
||||
of module `sigs.k8s.io/kustomize/api` constitute
|
||||
the _kustomize Go API_.
|
||||
|
||||
#### Version sigs.k8s.io/kustomize/v3 and earlier
|
||||
|
||||
[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
|
||||
|
||||
In `kustomize/v3` (and preceding major versions), the
|
||||
kustomize program and the API live the same Go
|
||||
module at `sigs.k8s.io/kustomize`, at [import path]
|
||||
`sigs.k8s.io/kustomize/v3`.
|
||||
|
||||
This has been fine for the CLI, but it presents a
|
||||
problem for the Go API.
|
||||
|
||||
[minimal version selection]: https://research.swtch.com/vgo-mvs
|
||||
|
||||
The process around Go modules, in particular the
|
||||
notion of [minimal version selection], demands
|
||||
that the module respect semver.
|
||||
|
||||
Almost all the code in module
|
||||
`sigs.k8s.io/kustomize/v3` is exposed (not in a
|
||||
directory named `internal`). Even a minor
|
||||
refactor changing a method name or argument type
|
||||
in some deeply buried (but still public) method is
|
||||
a backward incompatible change. As a result, Go
|
||||
API semver hasn't been followed. This was a mistake.
|
||||
|
||||
Some options are
|
||||
|
||||
- continue to ignore Go API semver and stick to
|
||||
CLI semver (eliminating the usefullness of
|
||||
minimal version selection),
|
||||
|
||||
- obey semver, and increment the module's major
|
||||
version number with every release (drastically
|
||||
reducing the usefullness of minimal version
|
||||
selection - since virtually all releases will
|
||||
be major),
|
||||
|
||||
- slow down change in the huge API in favor of
|
||||
stability, yet somehow continue to deliver
|
||||
features,
|
||||
|
||||
- drastically reduce the API surface, stabilize on
|
||||
semver there, and refactor as needed inside
|
||||
`internal`.
|
||||
|
||||
The last option seems the most appealing.
|
||||
|
||||
#### The first stable API version is coming
|
||||
|
||||
The first stable API version will launch
|
||||
as the Go module
|
||||
|
||||
```
|
||||
sigs.k8s.io/kustomize/api
|
||||
```
|
||||
|
||||
The _kustomize_ program itself (`main.go`
|
||||
and CLI specific code) will have moved out of
|
||||
`sigs.k8s.io/kustomize` and into the new module
|
||||
`sigs.k8s.io/kustomize/kustomize`. This is a
|
||||
submodule in the same repo, and it will retain its
|
||||
current notion of semver (e.g. a backward
|
||||
incompatible change in command behavior will
|
||||
trigger a major version bump). This module will
|
||||
not export packages; it's just home to a `main`
|
||||
package.
|
||||
|
||||
The `sigs.k8s.io/kustomize/api` module will
|
||||
obey semver with a sustainable public
|
||||
surface, informed by current usage. Clients
|
||||
should import packages from this module, i.e.
|
||||
from import paths prefixed by
|
||||
`sigs.k8s.io/kustomize/api/` at first,
|
||||
and later by `sigs.k8s.io/kustomize/api/v2/`.
|
||||
The kustomize binary
|
||||
itself is an API client requiring this module.
|
||||
|
||||
The clients and API will evolve independently.
|
||||
|
||||
## Kustomization File Versioning
|
||||
|
||||
The kustomization file is a struct that is part of
|
||||
the kustomize Go API (the `sigs.k8s.io/kustomize`
|
||||
module), but it also evolves as a k8s API object -
|
||||
it has an `apiVersion` field containing its
|
||||
own version number.
|
||||
|
||||
### Field Change Policy
|
||||
|
||||
- A field's meaning cannot be changed.
|
||||
- A field may be deprecated, then removed.
|
||||
- Deprecation means triggering a _minor_ (semver)
|
||||
version bump in the kustomize Go API, and
|
||||
defining a migration path in a non-fatal error
|
||||
message.
|
||||
- Removal means triggering a _major_ (semver)
|
||||
version bump in the kustomize Go API, and fatal
|
||||
error if field encountered (as with any unknown
|
||||
field). Likewise a change in `apiVersion`.
|
||||
|
||||
### The `edit fix` Command
|
||||
|
||||
This `kustomize` command reads a Kustomization
|
||||
file, converts deprecated fields to new
|
||||
fields, and writes it out again in the latest
|
||||
format.
|
||||
|
||||
This is a type version upgrade mechanism that
|
||||
works within _major_ API revisions. There is no
|
||||
downgrade capability, as there's no use case for
|
||||
it (see discussion below).
|
||||
|
||||
### Examples
|
||||
|
||||
With the 2.0.0 release, there were three field
|
||||
removals:
|
||||
|
||||
- `imageTag` was deprecated when `images` was
|
||||
introduced, because the latter offers more
|
||||
general features for image data manipulation.
|
||||
`imageTag` was removed in v2.0.0.
|
||||
- `patches` was deprecated and replaced by
|
||||
`patchesStrategicMerge` when `patchesJson6902`
|
||||
was introduced, to make a clearer
|
||||
distinction between patch specification formats.
|
||||
`patches` was removed in v2.0.0.
|
||||
- `secretGenerator/commands` was removed
|
||||
due to security concerns in v2.0.0
|
||||
with no deprecation period.
|
||||
|
||||
The `edit fix` command in a v2.0.x binary
|
||||
will no longer recognize these fields.
|
||||
|
||||
## Relationship to the k8s API
|
||||
|
||||
### Review of k8s API versioning
|
||||
|
||||
The k8s API has specific [conventions] and a
|
||||
process for making [changes].
|
||||
|
||||
The presence of an `apiVersion` field in a k8s
|
||||
native type signals:
|
||||
|
||||
- its reliability level (alpha vs beta vs
|
||||
generally available),
|
||||
- the existence of code to provide default values
|
||||
to fields not present in a serialization,
|
||||
- the existence of code to provide both forward
|
||||
and backward conversion between different
|
||||
versions of types.
|
||||
|
||||
The k8s API promises a lossless _conversion_
|
||||
between versions over a specific range. This
|
||||
means that a recent client can write an object
|
||||
bearing the newest possible value for its version,
|
||||
the server will accept it and store it in
|
||||
"versionless" JSON form in storage, and can
|
||||
convert it to a range of older versions should
|
||||
an older client request data.
|
||||
|
||||
For native k8s types, this all requires writing Go
|
||||
code in the kubernetes core repo, to provide
|
||||
defaulting and conversions.
|
||||
|
||||
For CRDs, there's a [proposal] on how to manage
|
||||
versioning (e.g. a remote service can offer type
|
||||
defaulting and conversions).
|
||||
|
||||
### Differences
|
||||
|
||||
- A k8s API server is able to go _forward_ and
|
||||
_backward_ in versioning, to work with older
|
||||
clients, over [some range].
|
||||
- The `kustomize edit fix` command only moves
|
||||
_forward_ within a _major_ API
|
||||
version.
|
||||
|
||||
At the time of writing, the YAML in a
|
||||
kustomization file does not represent a [k8s API]
|
||||
object, and the kustomize command and associated
|
||||
library is neither a server of, nor a client to,
|
||||
the k8s API.
|
||||
|
||||
### Additional Kustomization file rules
|
||||
|
||||
In addition to the [field change policy] described
|
||||
above, kustomization files conform to
|
||||
the following rules.
|
||||
|
||||
#### Eschew classic k8s fields
|
||||
|
||||
Field names with dedicated meaning in k8s
|
||||
(`metadata`, `spec`, `status`, etc.) aren't used.
|
||||
This is enforced via code review.
|
||||
|
||||
#### Default values for k8s `kind` and `apiVersion`
|
||||
|
||||
In `v3` or below, the two [special] k8s
|
||||
resource fields [`kind`] and [`apiVersion`] may
|
||||
be omitted from the kustomization file.
|
||||
|
||||
If either field is present, they both must be.
|
||||
If present, the value of `kind` must be:
|
||||
|
||||
> ```
|
||||
> kind: Kustomization
|
||||
> ```
|
||||
|
||||
If missing, the value of `apiVersion` defaults to
|
||||
|
||||
> ```
|
||||
> apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
> ```
|
||||
|
||||
[field change policy]: #field-change-policy
|
||||
[some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy
|
||||
[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md
|
||||
[beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions
|
||||
[changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md
|
||||
[adapt]: /types/kustomization.go#L166
|
||||
[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources
|
||||
[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
|
||||
[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
|
||||
[release page]: https://github.com/kubernetes-sigs/kustomize/releases
|
||||
[release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md
|
||||
[kustomization]: /kustomize/api-reference/glossary#kustomization
|
||||
[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds
|
||||
[`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning
|
||||
[semantic versioning]: https://semver.org
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -10,3 +10,5 @@ description: >
|
||||
Reference for Kustomize usage and best practices
|
||||
---
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/config_management" />
|
||||
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,76 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/config_management/bespoke/" />
|
||||
|
||||
|
||||
In this workflow, all configuration (resource YAML) files are owned by the user.
|
||||
No content is incorporated from version control repositories owned by others.
|
||||
|
||||
![bespoke config workflow image][workflowBespoke]
|
||||
|
||||
#### 1) create a directory in version control
|
||||
|
||||
Speculate some overall cluster application called _ldap_;
|
||||
we want to keep its configuration in its own repo.
|
||||
|
||||
> ```
|
||||
> git init ~/ldap
|
||||
> ```
|
||||
|
||||
#### 2) create a [base]
|
||||
|
||||
> ```
|
||||
> mkdir -p ~/ldap/base
|
||||
> ```
|
||||
|
||||
In this directory, create and commit a [kustomization]
|
||||
file and a set of [resources].
|
||||
|
||||
#### 3) create [overlays]
|
||||
|
||||
> ```
|
||||
> mkdir -p ~/ldap/overlays/staging
|
||||
> mkdir -p ~/ldap/overlays/production
|
||||
> ```
|
||||
|
||||
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.
|
||||
|
||||
The _production_ directory might get a patch
|
||||
that increases the replica count in a deployment
|
||||
specified in the base.
|
||||
|
||||
#### 4) bring up [variants]
|
||||
|
||||
Run kustomize, and pipe the output to [apply].
|
||||
|
||||
> ```
|
||||
> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
|
||||
> kustomize build ~/ldap/overlays/production | kubectl apply -f -
|
||||
> ```
|
||||
|
||||
You can also use [kubectl-v1.14.0] to apply your [variants].
|
||||
>
|
||||
> ```
|
||||
> kubectl apply -k ~/ldap/overlays/staging
|
||||
> kubectl apply -k ~/ldap/overlays/production
|
||||
> ```
|
||||
|
||||
[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration
|
||||
[apply]: /kustomize/api-reference/glossary#apply
|
||||
[applying]: /kustomize/api-reference/glossary#apply
|
||||
[base]: /kustomize/api-reference/glossary#base
|
||||
[fork]: https://guides.github.com/activities/forking/
|
||||
[variants]: /kustomize/api-reference/glossary#variant
|
||||
[kustomization]: /kustomize/api-reference/glossary#kustomization
|
||||
[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration
|
||||
[overlays]: /kustomize/api-reference/glossary#overlay
|
||||
[patch]: /kustomize/api-reference/glossary#patch
|
||||
[patches]: /kustomize/api-reference/glossary#patch
|
||||
[rebase]: https://git-scm.com/docs/git-rebase
|
||||
[resources]: /kustomize/api-reference/glossary#resource
|
||||
[workflowBespoke]: /kustomize/images/workflowBespoke.jpg
|
||||
[workflowOts]: /kustomize/images/workflowOts.jpg
|
||||
[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Command Line Options"
|
||||
linkTitle: "Command Line Options"
|
||||
type: docs
|
||||
description: >
|
||||
Usage of command line options
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "build"
|
||||
linkTitle: "build"
|
||||
type: docs
|
||||
description: >
|
||||
Print configuration per contents of kustomization.yaml
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "cfg"
|
||||
linkTitle: "cfg"
|
||||
type: docs
|
||||
description: >
|
||||
Commands for reading and writing configuration.
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "create"
|
||||
linkTitle: "create"
|
||||
type: docs
|
||||
description: >
|
||||
Create a new kustomization in the current directory
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "edit"
|
||||
linkTitle: "edit"
|
||||
type: docs
|
||||
description: >
|
||||
Edits a kustomization file
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "fn"
|
||||
linkTitle: "fn"
|
||||
type: docs
|
||||
description: >
|
||||
Commands for running functions against configuration
|
||||
---
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
title: "help"
|
||||
linkTitle: "help"
|
||||
type: docs
|
||||
description: >
|
||||
Help about any command
|
||||
---
|
||||
|
||||
> ```
|
||||
> kustomize help
|
||||
>
|
||||
> Manages declarative configuration of Kubernetes.
|
||||
> See https://sigs.k8s.io/kustomize
|
||||
>
|
||||
> Usage:
|
||||
> kustomize [command]
|
||||
>
|
||||
> Available Commands:
|
||||
> build Print configuration per contents of kustomization.yaml
|
||||
> cfg Commands for reading and writing configuration.
|
||||
> create Create a new kustomization in the current directory
|
||||
> edit Edits a kustomization file
|
||||
> fn Commands for running functions against configuration.
|
||||
> help Help about any command
|
||||
> install-completion Install shell completion.
|
||||
> live Commands for reading and writing resources to a cluster.
|
||||
> version Prints the kustomize version
|
||||
>
|
||||
> Flags:
|
||||
> -h, --help help for kustomize
|
||||
> --stack-trace print a stack-trace on error
|
||||
>
|
||||
> Additional help topics:
|
||||
> kustomize docs-fn [Alpha] Documentation for developing and invoking Configuration Functions.
|
||||
> kustomize docs-fn-spec [Alpha] Documentation for Configuration Functions Specification.
|
||||
> kustomize docs-io-annotations [Alpha] Documentation for annotations used by io.
|
||||
> kustomize docs-merge [Alpha] Documentation for merging Resources (2-way merge).
|
||||
> kustomize docs-merge3 [Alpha] Documentation for merging Resources (3-way merge).
|
||||
> kustomize tutorials-command-basics [Alpha] Tutorials for using basic config commands.
|
||||
> kustomize tutorials-function-basics [Alpha] Tutorials for using functions.
|
||||
>
|
||||
> Use "kustomize [command] --help" for more information about a command.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "install-completion"
|
||||
linkTitle: "install-completion"
|
||||
type: docs
|
||||
description: >
|
||||
Installs shell completion
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "live"
|
||||
linkTitle: "live"
|
||||
type: docs
|
||||
description: >
|
||||
Commands for reading and writing resources to a cluster.
|
||||
---
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: "version"
|
||||
linkTitle: "version"
|
||||
type: docs
|
||||
description: >
|
||||
Prints the kustomize version
|
||||
---
|
||||
|
||||
Prints the current kustomize version
|
||||
|
||||
> ```
|
||||
> kustomize version
|
||||
> {Version:kustomize/v3.8.1 GitCommit:0b359d0ef0272e6545eda0e99aacd63aef99c4d0 BuildDate:2020-07-16T00:58:46Z GoOs:linux GoArch:amd64}
|
||||
> ```
|
||||
@@ -8,365 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/config_management/components/" />
|
||||
|
||||
|
||||
As of ``v3.7.0`` Kustomize supports a special type of kustomization that allows
|
||||
one to define reusable pieces of configuration logic that can be included from
|
||||
multiple overlays.
|
||||
|
||||
Components come in handy when dealing with applications that support multiple
|
||||
optional features and you wish to enable only a subset of them in different
|
||||
overlays, i.e., different features for different environments or audiences.
|
||||
|
||||
For more details regarding this feature you can read the
|
||||
[Kustomize Components KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/1802-kustomize-components.md).
|
||||
|
||||
## Use case
|
||||
|
||||
Suppose you've written a very simple Web application:
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: example
|
||||
image: example:1.0
|
||||
```
|
||||
|
||||
You want to deploy a **community** edition of this application as SaaS, so you
|
||||
add support for persistence (e.g. an external database), and bot detection
|
||||
(e.g. Google reCAPTCHA).
|
||||
|
||||
You've now attracted **enterprise** customers who want to deploy it
|
||||
on-premises, so you add LDAP support, and disable Google reCAPTCHA. At the same
|
||||
time, the **devs** need to be able to test parts of the application, so they
|
||||
want to deploy it with some features enabled and others not.
|
||||
|
||||
Here's a matrix with the deployments of this application and the features
|
||||
enabled for each one:
|
||||
|
||||
| | External DB | LDAP | reCAPTCHA |
|
||||
|------------|:------------------:|:------------------:|:------------------:|
|
||||
| Community | ✔️ | | ✔️ |
|
||||
| Enterprise | ✔️ | ✔️ | |
|
||||
| Dev | ✅ | ✅ | ✅ |
|
||||
|
||||
(✔️ enabled, ✅: optional)
|
||||
|
||||
So, you want to make it easy to deploy your application in any of the above
|
||||
three environments. Here's how you can do this with Kustomize components: each
|
||||
opt-in feature gets packaged as a component, so that it can be referred to from
|
||||
multiple higher-level overlays.
|
||||
|
||||
First, define a place to work:
|
||||
|
||||
```shell
|
||||
DEMO_HOME=$(mktemp -d)
|
||||
```
|
||||
|
||||
Define a common **base** that has a `Deployment` and a simple `ConfigMap`, that
|
||||
is mounted on the application's container.
|
||||
|
||||
```shell
|
||||
BASE=$DEMO_HOME/base
|
||||
mkdir $BASE
|
||||
|
||||
cat <<EOF >$BASE/kustomization.yaml
|
||||
resources:
|
||||
- deployment.yaml
|
||||
|
||||
configMapGenerator:
|
||||
- name: conf
|
||||
literals:
|
||||
- main.conf=|
|
||||
color=cornflower_blue
|
||||
log_level=info
|
||||
EOF
|
||||
|
||||
cat <<EOF >$BASE/deployment.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: example
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: example
|
||||
image: example:1.0
|
||||
volumeMounts:
|
||||
- name: conf
|
||||
mountPath: /etc/config
|
||||
volumes:
|
||||
- name: conf
|
||||
configMap:
|
||||
name: conf
|
||||
EOF
|
||||
```
|
||||
|
||||
Define an `external_db` component, using `kind: Component`, that creates a
|
||||
`Secret` for the DB password and a new entry in the `ConfigMap`:
|
||||
|
||||
```shell
|
||||
EXT_DB=$DEMO_HOME/components/external_db
|
||||
mkdir -p $EXT_DB
|
||||
|
||||
cat <<EOF >$EXT_DB/kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1alpha1 # <-- Component notation
|
||||
kind: Component
|
||||
|
||||
secretGenerator:
|
||||
- name: dbpass
|
||||
files:
|
||||
- dbpass.txt
|
||||
|
||||
patchesStrategicMerge:
|
||||
- configmap.yaml
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: example
|
||||
path: deployment.yaml
|
||||
EOF
|
||||
|
||||
cat <<EOF >$EXT_DB/deployment.yaml
|
||||
- op: add
|
||||
path: /spec/template/spec/volumes/0
|
||||
value:
|
||||
name: dbpass
|
||||
secret:
|
||||
secretName: dbpass
|
||||
- op: add
|
||||
path: /spec/template/spec/containers/0/volumeMounts/0
|
||||
value:
|
||||
mountPath: /var/run/secrets/db/
|
||||
name: dbpass
|
||||
EOF
|
||||
|
||||
cat <<EOF >$EXT_DB/configmap.yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: conf
|
||||
data:
|
||||
db.conf: |
|
||||
endpoint=127.0.0.1:1234
|
||||
name=app
|
||||
user=admin
|
||||
pass=/var/run/secrets/db/dbpass.txt
|
||||
EOF
|
||||
```
|
||||
|
||||
Define an `ldap` component, that creates a `Secret` for the LDAP password
|
||||
and a new entry in the `ConfigMap`:
|
||||
|
||||
```shell
|
||||
LDAP=$DEMO_HOME/components/ldap
|
||||
mkdir -p $LDAP
|
||||
|
||||
cat <<EOF >$LDAP/kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1alpha1
|
||||
kind: Component
|
||||
|
||||
secretGenerator:
|
||||
- name: ldappass
|
||||
files:
|
||||
- ldappass.txt
|
||||
|
||||
patchesStrategicMerge:
|
||||
- configmap.yaml
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: example
|
||||
path: deployment.yaml
|
||||
EOF
|
||||
|
||||
cat <<EOF >$LDAP/deployment.yaml
|
||||
- op: add
|
||||
path: /spec/template/spec/volumes/0
|
||||
value:
|
||||
name: ldappass
|
||||
secret:
|
||||
secretName: ldappass
|
||||
- op: add
|
||||
path: /spec/template/spec/containers/0/volumeMounts/0
|
||||
value:
|
||||
mountPath: /var/run/secrets/ldap/
|
||||
name: ldappass
|
||||
EOF
|
||||
|
||||
cat <<EOF >$LDAP/configmap.yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: conf
|
||||
data:
|
||||
ldap.conf: |
|
||||
endpoint=ldap://ldap.example.com
|
||||
bindDN=cn=admin,dc=example,dc=com
|
||||
pass=/var/run/secrets/ldap/ldappass.txt
|
||||
EOF
|
||||
```
|
||||
|
||||
Define a `recaptcha` component, that creates a `Secret` for the reCAPTCHA
|
||||
site/secret keys and a new entry in the `ConfigMap`:
|
||||
|
||||
```shell
|
||||
RECAPTCHA=$DEMO_HOME/components/recaptcha
|
||||
mkdir -p $RECAPTCHA
|
||||
|
||||
cat <<EOF >$RECAPTCHA/kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1alpha1
|
||||
kind: Component
|
||||
|
||||
secretGenerator:
|
||||
- name: recaptcha
|
||||
files:
|
||||
- site_key.txt
|
||||
- secret_key.txt
|
||||
|
||||
# Updating the ConfigMap works with generators as well.
|
||||
configMapGenerator:
|
||||
- name: conf
|
||||
behavior: merge
|
||||
literals:
|
||||
- recaptcha.conf=|
|
||||
enabled=true
|
||||
site_key=/var/run/secrets/recaptcha/site_key.txt
|
||||
secret_key=/var/run/secrets/recaptcha/secret_key.txt
|
||||
|
||||
patchesJson6902:
|
||||
- target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: example
|
||||
path: deployment.yaml
|
||||
EOF
|
||||
|
||||
cat <<EOF >$RECAPTCHA/deployment.yaml
|
||||
- op: add
|
||||
path: /spec/template/spec/volumes/0
|
||||
value:
|
||||
name: recaptcha
|
||||
secret:
|
||||
secretName: recaptcha
|
||||
- op: add
|
||||
path: /spec/template/spec/containers/0/volumeMounts/0
|
||||
value:
|
||||
mountPath: /var/run/secrets/recaptcha/
|
||||
name: recaptcha
|
||||
EOF
|
||||
```
|
||||
|
||||
Define a `community` variant, that bundles the external DB and reCAPTCHA
|
||||
components:
|
||||
|
||||
```shell
|
||||
COMMUNITY=$DEMO_HOME/overlays/community
|
||||
mkdir -p $COMMUNITY
|
||||
|
||||
cat <<EOF >$COMMUNITY/kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- ../../base
|
||||
|
||||
components:
|
||||
- ../../components/external_db
|
||||
- ../../components/recaptcha
|
||||
EOF
|
||||
```
|
||||
|
||||
Define an `enterprise` overlay, that bundles the external DB and LDAP
|
||||
components:
|
||||
|
||||
```shell
|
||||
ENTERPRISE=$DEMO_HOME/overlays/enterprise
|
||||
mkdir -p $ENTERPRISE
|
||||
|
||||
cat <<EOF >$ENTERPRISE/kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- ../../base
|
||||
|
||||
components:
|
||||
- ../../components/external_db
|
||||
- ../../components/ldap
|
||||
EOF
|
||||
```
|
||||
|
||||
Define a `dev` overlay, that points to all the components and has LDAP
|
||||
disabled:
|
||||
|
||||
```shell
|
||||
DEV=$DEMO_HOME/overlays/dev
|
||||
mkdir -p $DEV
|
||||
|
||||
cat <<EOF >$DEV/kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- ../../base
|
||||
|
||||
components:
|
||||
- ../../components/external_db
|
||||
#- ../../components/ldap
|
||||
- ../../components/recaptcha
|
||||
EOF
|
||||
```
|
||||
|
||||
Now, the workspace has the following directories:
|
||||
|
||||
```shell
|
||||
├── base
|
||||
│ ├── deployment.yaml
|
||||
│ └── kustomization.yaml
|
||||
├── components
|
||||
│ ├── external_db
|
||||
│ │ ├── configmap.yaml
|
||||
│ │ ├── dbpass.txt
|
||||
│ │ ├── deployment.yaml
|
||||
│ │ └── kustomization.yaml
|
||||
│ ├── ldap
|
||||
│ │ ├── configmap.yaml
|
||||
│ │ ├── deployment.yaml
|
||||
│ │ ├── kustomization.yaml
|
||||
│ │ └── ldappass.txt
|
||||
│ └── recaptcha
|
||||
│ ├── deployment.yaml
|
||||
│ ├── kustomization.yaml
|
||||
│ ├── secret_key.txt
|
||||
│ └── site_key.txt
|
||||
└── overlays
|
||||
├── community
|
||||
│ └── kustomization.yaml
|
||||
├── dev
|
||||
│ └── kustomization.yaml
|
||||
└── enterprise
|
||||
└── kustomization.yaml
|
||||
```
|
||||
|
||||
With this structure, you can generate the YAML manifests for each deployment
|
||||
using `kustomize build`:
|
||||
|
||||
```shell
|
||||
kustomize build overlays/community
|
||||
kustomize build overlays/enterprise
|
||||
kustomize build overlays/dev
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,78 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/config_management/offtheshelf/" />
|
||||
|
||||
|
||||
In this workflow, all files are owned by the user and maintained in a repository under their control, but
|
||||
they are based on an [off-the-shelf] configuration that is periodically consulted for updates.
|
||||
|
||||
![off-the-shelf config workflow image][workflowOts]
|
||||
|
||||
#### 1) find and [fork] an [OTS] config
|
||||
|
||||
#### 2) clone it as your [base]
|
||||
|
||||
The [base] directory is maintained in a repo whose upstream is an [OTS] configuration, in this case
|
||||
some user's `ldap` repo:
|
||||
|
||||
> ```
|
||||
> mkdir ~/ldap
|
||||
> git clone https://github.com/$USER/ldap ~/ldap/base
|
||||
> cd ~/ldap/base
|
||||
> git remote add upstream git@github.com:$USER/ldap
|
||||
> ```
|
||||
|
||||
#### 3) create [overlays]
|
||||
|
||||
As in the bespoke case above, create and populate an _overlays_ directory.
|
||||
|
||||
The [overlays] are siblings to each other and to the [base] they depend on.
|
||||
|
||||
> ```
|
||||
> mkdir -p ~/ldap/overlays/staging
|
||||
> mkdir -p ~/ldap/overlays/production
|
||||
> ```
|
||||
|
||||
The user can maintain the `overlays` directory in a
|
||||
distinct repository.
|
||||
|
||||
#### 4) bring up [variants]
|
||||
|
||||
> ```
|
||||
> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
|
||||
> kustomize build ~/ldap/overlays/production | kubectl apply -f -
|
||||
> ```
|
||||
|
||||
You can also use [kubectl-v1.14.0] to apply your [variants].
|
||||
>
|
||||
> ```
|
||||
> kubectl apply -k ~/ldap/overlays/staging
|
||||
> kubectl apply -k ~/ldap/overlays/production
|
||||
> ```
|
||||
|
||||
#### 5) (optionally) capture changes from upstream
|
||||
|
||||
The user can periodically [rebase] their [base] to
|
||||
capture changes made in the upstream repository.
|
||||
|
||||
> ```
|
||||
> cd ~/ldap/base
|
||||
> git fetch upstream
|
||||
> git rebase upstream/master
|
||||
> ```
|
||||
|
||||
[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration
|
||||
[apply]: /kustomize/api-reference/glossary#apply
|
||||
[applying]: /kustomize/api-reference/glossary#apply
|
||||
[base]: /kustomize/api-reference/glossary#base
|
||||
[fork]: https://guides.github.com/activities/forking/
|
||||
[variants]: /kustomize/api-reference/glossary#variant
|
||||
[kustomization]: /kustomize/api-reference/glossary#kustomization
|
||||
[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration
|
||||
[overlays]: /kustomize/api-reference/glossary#overlay
|
||||
[patch]: /kustomize/api-reference/glossary#patch
|
||||
[patches]: /kustomize/api-reference/glossary#patch
|
||||
[rebase]: https://git-scm.com/docs/git-rebase
|
||||
[resources]: /kustomize/api-reference/glossary#resource
|
||||
[workflowBespoke]: /kustomize/images/workflowBespoke.jpg
|
||||
[workflowOts]: /kustomize/images/workflowOts.jpg
|
||||
[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,372 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/extending_kustomize/plugins" />
|
||||
|
||||
Kustomize offers a plugin framework allowing people to write their own resource _generators_
|
||||
and _transformers_.
|
||||
|
||||
[generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md
|
||||
[transformer configs]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs
|
||||
|
||||
Write a plugin when changing [generator options]
|
||||
or [transformer configs] doesn't meet your needs.
|
||||
|
||||
[12-factor]: https://12factor.net
|
||||
|
||||
* A _generator_ plugin could be a helm chart
|
||||
inflator, or a plugin that emits all the
|
||||
components (deployment, service, scaler,
|
||||
ingress, etc.) needed by someone's [12-factor]
|
||||
application, based on a smaller number of free
|
||||
variables.
|
||||
|
||||
* A _transformer_ plugin might perform special
|
||||
container command line edits, or any other
|
||||
transformation beyond those provided by the
|
||||
builtin (`namePrefix`, `commonLabels`, etc.)
|
||||
transformers.
|
||||
|
||||
## Specification in `kustomization.yaml`
|
||||
|
||||
Start by adding a `generators` and/or `transformers`
|
||||
field to your kustomization.
|
||||
|
||||
Each field accepts a string list:
|
||||
|
||||
> ```
|
||||
> generators:
|
||||
> - relative/path/to/some/file.yaml
|
||||
> - relative/path/to/some/kustomization
|
||||
> - /absolute/path/to/some/kustomization
|
||||
> - https://github.com/org/repo/some/kustomization
|
||||
>
|
||||
> transformers:
|
||||
> - {as above}
|
||||
> ```
|
||||
|
||||
The value of each entry in a `generators` or
|
||||
`transformers` list must be a relative path to a
|
||||
YAML file, or a path or URL to a [kustomization].
|
||||
This is the same format as demanded by the
|
||||
`resources` field.
|
||||
|
||||
[kustomization]: /kustomize/api-reference/glossary#kustomization
|
||||
|
||||
YAML files are read from disk directly. Paths or
|
||||
URLs leading to kustomizations trigger an
|
||||
in-process kustomization run. Each of the
|
||||
resulting objects is now further interpreted by
|
||||
kustomize as a _plugin configuration_ object.
|
||||
|
||||
## Configuration
|
||||
|
||||
A kustomization file could have the following lines:
|
||||
|
||||
```
|
||||
generators:
|
||||
- chartInflator.yaml
|
||||
```
|
||||
|
||||
Given this, the kustomization process would expect
|
||||
to find a file called `chartInflator.yaml` in the
|
||||
kustomization [root](/kustomize/api-reference/glossary#kustomization-root).
|
||||
|
||||
This is the plugin's configuration file;
|
||||
it contains a YAML configuration object.
|
||||
|
||||
The file `chartInflator.yaml` could contain:
|
||||
|
||||
```
|
||||
apiVersion: someteam.example.com/v1
|
||||
kind: ChartInflator
|
||||
metadata:
|
||||
name: notImportantHere
|
||||
chartName: minecraft
|
||||
```
|
||||
|
||||
__The `apiVersion` and `kind` fields are
|
||||
used to locate the plugin.__
|
||||
|
||||
[k8s object]: /kustomize/api-reference/glossary#kubernetes-style-object
|
||||
|
||||
Thus, these fields are required. They are also
|
||||
required because a kustomize plugin configuration
|
||||
object is also a [k8s object].
|
||||
|
||||
To get the plugin ready to generate or transform,
|
||||
it is given the entire contents of the
|
||||
configuration file.
|
||||
|
||||
[NameTransformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go
|
||||
[ChartInflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go
|
||||
[plugins]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin
|
||||
|
||||
For more examples of plugin configuration YAML,
|
||||
browse the unit tests below the [plugins] root,
|
||||
e.g. the tests for [ChartInflator] or
|
||||
[NameTransformer].
|
||||
|
||||
## Placement
|
||||
|
||||
Each plugin gets its own dedicated directory named
|
||||
|
||||
[`XDG_CONFIG_HOME`]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
||||
|
||||
```
|
||||
$XDG_CONFIG_HOME/kustomize/plugin
|
||||
/${apiVersion}/LOWERCASE(${kind})
|
||||
```
|
||||
|
||||
The default value of [`XDG_CONFIG_HOME`] is
|
||||
`$HOME/.config`.
|
||||
|
||||
The one-plugin-per-directory requirement eases
|
||||
creation of a plugin bundle (source, tests, plugin
|
||||
data files, etc.) for sharing.
|
||||
|
||||
In the case of a [Go plugin](#go-plugins), it also
|
||||
allows one to provide a `go.mod` file for the
|
||||
single plugin, easing resolution of package
|
||||
version dependency skew.
|
||||
|
||||
When loading, kustomize will first look for an
|
||||
_executable_ file called
|
||||
|
||||
```
|
||||
$XDG_CONFIG_HOME/kustomize/plugin
|
||||
/${apiVersion}/LOWERCASE(${kind})/${kind}
|
||||
```
|
||||
|
||||
If this file is not found or is not executable,
|
||||
kustomize will look for a file called `${kind}.so`
|
||||
in the same directory and attempt to load it as a
|
||||
[Go plugin](#go-plugins).
|
||||
|
||||
If both checks fail, the plugin load fails the overall
|
||||
`kustomize build`.
|
||||
|
||||
## Execution
|
||||
|
||||
Plugins are only used during a run of the
|
||||
`kustomize build` command.
|
||||
|
||||
Generator plugins are run after processing the
|
||||
`resources` field (which itself can be viewed as a
|
||||
generator, simply reading objects from disk).
|
||||
|
||||
The full set of resources is then passed into the
|
||||
transformation pipeline, wherein builtin
|
||||
transformations like `namePrefix` and
|
||||
`commonLabel` are applied (if they were specified
|
||||
in the kustomization file), followed by the
|
||||
user-specified transformers in the `transformers`
|
||||
field.
|
||||
|
||||
The order specified in the `transformers` field is
|
||||
respected, as transformers cannot be expected to
|
||||
be commutative.
|
||||
|
||||
#### No Security
|
||||
|
||||
Kustomize plugins do not run in any kind of
|
||||
kustomize-provided sandbox. There's no notion
|
||||
of _"plugin security"_.
|
||||
|
||||
A `kustomize build` that tries to use plugins but
|
||||
omits the flag
|
||||
|
||||
> `--enable_alpha_plugins`
|
||||
|
||||
will not load plugins and will fail with a
|
||||
warning about plugin use.
|
||||
|
||||
The use of this flag is an opt-in acknowledging
|
||||
the unstable (alpha) plugin API, the absence of
|
||||
plugin provenance, and the fact that a plugin
|
||||
is not part of kustomize.
|
||||
|
||||
To be clear, some kustomize plugin downloaded
|
||||
from the internet might wonderfully transform
|
||||
k8s config in a desired manner, while also
|
||||
quietly doing anything the user could do to the
|
||||
system running `kustomize build`.
|
||||
|
||||
## Authoring
|
||||
|
||||
There are two kinds of plugins, [exec](#exec-plugins) and [Go](#go-plugins).
|
||||
|
||||
### Exec plugins
|
||||
|
||||
A _exec plugin_ is any executable that accepts a
|
||||
single argument on its command line - the name of
|
||||
a YAML file containing its configuration (the file name
|
||||
provided in the kustomization file).
|
||||
|
||||
> TODO: restrictions on plugin to allow the _same exec
|
||||
> plugin_ to be targeted by both the
|
||||
> `generators` and `transformers` fields.
|
||||
>
|
||||
> - first arg could be the fixed string
|
||||
> `generate` or `transform`,
|
||||
> (the name of the configuration file moves to
|
||||
> the 2nd arg), or
|
||||
> - or by default an exec plugin behaves as a tranformer
|
||||
> unless a flag `-g` is provided, switching the
|
||||
> exec plugin to behave as a generator.
|
||||
|
||||
[helm chart inflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator
|
||||
[bashed config map]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/bashedconfigmap
|
||||
[sed transformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/sedtransformer
|
||||
[hashicorp go-getter]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/gogetter
|
||||
|
||||
#### Examples
|
||||
|
||||
* [helm chart inflator] - A generator that inflates a helm chart.
|
||||
* [bashed config map] - Super simple configMap generation from bash.
|
||||
* [sed transformer] - Define your unstructured edits using a
|
||||
plugin like this one.
|
||||
* [hashicorp go-getter] - Download kustomize layes and build it to generate resources
|
||||
|
||||
A generator plugin accepts nothing on `stdin`, but emits
|
||||
generated resources to `stdout`.
|
||||
|
||||
A transformer plugin accepts resource YAML on `stdin`,
|
||||
and emits those resources, presumably transformed, to
|
||||
`stdout`.
|
||||
|
||||
kustomize uses an exec plugin adapter to provide
|
||||
marshalled resources on `stdin` and capture
|
||||
`stdout` for further processing.
|
||||
|
||||
#### Generator Options
|
||||
|
||||
A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations.
|
||||
|
||||
> NOTE: These annotations are local to kustomize and will not be included in the final output.
|
||||
|
||||
**`kustomize.config.k8s.io/needs-hash`**
|
||||
|
||||
Resources can be marked as needing to be processed by the internal hash transformer by including the `needs-hash` annotation. When set valid values for the annotation are `"true"` and `"false"` which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value `"false"`.
|
||||
|
||||
Hashes are determined as follows:
|
||||
|
||||
* For `ConfigMap` resources, hashes are based on the values of the `name`, `data`, and `binaryData` fields.
|
||||
* For `Secret` resources, hashes are based on the values of the `name`, `type`, `data`, and `stringData` fields.
|
||||
* For any other object type, hashes are based on the entire object content (i.e. all fields).
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: cm-test
|
||||
annotations:
|
||||
kustomize.config.k8s.io/needs-hash: "true"
|
||||
data:
|
||||
foo: bar
|
||||
```
|
||||
|
||||
**`kustomize.config.k8s.io/behavior`**
|
||||
|
||||
The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: cm-test
|
||||
annotations:
|
||||
kustomize.config.k8s.io/behavior: "merge"
|
||||
data:
|
||||
foo: bar
|
||||
```
|
||||
|
||||
### Go plugins
|
||||
|
||||
Be sure to read [Go plugin caveats](goplugincaveats/).
|
||||
|
||||
[Go plugin]: https://golang.org/pkg/plugin/
|
||||
|
||||
A `.go` file can be a [Go plugin] if it declares
|
||||
'main' as it's package, and exports a symbol to
|
||||
which useful functions are attached.
|
||||
|
||||
It can further be used as a _kustomize_ plugin if
|
||||
the symbol is named 'KustomizePlugin' and the
|
||||
attached functions implement the `Configurable`,
|
||||
`Generator` and `Transformer` interfaces.
|
||||
|
||||
A Go plugin for kustomize looks like this:
|
||||
|
||||
> ```
|
||||
> package main
|
||||
>
|
||||
> import (
|
||||
> "sigs.k8s.io/kustomize/api/resmap"
|
||||
> ...
|
||||
> )
|
||||
>
|
||||
> type plugin struct {...}
|
||||
>
|
||||
> var KustomizePlugin plugin
|
||||
>
|
||||
> func (p *plugin) Config(
|
||||
> h *resmap.PluginHelpers,
|
||||
> c []byte) error {...}
|
||||
>
|
||||
> func (p *plugin) Generate() (resmap.ResMap, error) {...}
|
||||
>
|
||||
> func (p *plugin) Transform(m resmap.ResMap) error {...}
|
||||
> ```
|
||||
|
||||
Use of the identifiers `plugin`, `KustomizePlugin`
|
||||
and implementation of the method signature
|
||||
`Config` is required.
|
||||
|
||||
Implementing the `Generator` or `Transformer`
|
||||
method allows (respectively) the plugin's config
|
||||
file to be added to the `generators` or
|
||||
`transformers` field in the kustomization file.
|
||||
Do one or the other or both as desired.
|
||||
|
||||
[secret generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/secretsfromdatabase
|
||||
[service generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/someservicegenerator
|
||||
[string prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/stringprefixer
|
||||
[date prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/dateprefixer
|
||||
[sops encoded secrets]: https://github.com/monopole/sopsencodedsecrets
|
||||
[SOPSGenerator]: https://github.com/omninonsense/kustomize-sopsgenerator
|
||||
|
||||
#### Examples
|
||||
|
||||
* [service generator] - generate a service from a name and port argument.
|
||||
* [string prefixer] - uses the value in `metadata/name` as the prefix.
|
||||
This particular example exists to show how a plugin can
|
||||
transform the behavior of a plugin. See the
|
||||
`TestTransformedTransformers` test in the `target` package.
|
||||
* [date prefixer] - prefix the current date to resource names, a simple
|
||||
example used to modify the string prefixer plugin just mentioned.
|
||||
* [secret generator] - generate secrets from a toy database.
|
||||
* [sops encoded secrets] - a more complex secret generator that converts SOPS files into Kubernetes Secrets
|
||||
* [SOPSGenerator] - another generator that decrypts SOPS files into Secrets
|
||||
* [All the builtin plugins](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin).
|
||||
User authored plugins are
|
||||
on the same footing as builtin operations.
|
||||
|
||||
A Go plugin can be both a generator and a
|
||||
transformer. The `Generate` method will run along
|
||||
with all the other generators before the
|
||||
`Transform` method runs.
|
||||
|
||||
Here's a build command that sensibly assumes the
|
||||
plugin source code sits in the directory where
|
||||
kustomize expects to find `.so` files:
|
||||
|
||||
```
|
||||
d=$XDG_CONFIG_HOME/kustomize/plugin\
|
||||
/${apiVersion}/LOWERCASE(${kind})
|
||||
|
||||
go build -buildmode plugin \
|
||||
-o $d/${kind}.so $d/${kind}.go
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,793 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/extending_kustomize/builtins" />
|
||||
|
||||
|
||||
# Builtin Plugins
|
||||
|
||||
A list of kustomize's builtin plugins - both
|
||||
generators and transformers.
|
||||
|
||||
For each plugin, an example is given for
|
||||
|
||||
- implicitly triggering
|
||||
the plugin via a dedicated kustomization
|
||||
file field (e.g. the `AnnotationsTransformer` is
|
||||
triggered by the `commonAnnotations` field).
|
||||
|
||||
- explicitly triggering the plugin
|
||||
via the `generators` or `transformers` field
|
||||
(by providing a config file specifying the
|
||||
plugin).
|
||||
|
||||
The former method is convenient but limited in
|
||||
power as most of the plugins arguments must
|
||||
be defaulted. The latter method allows for
|
||||
complete plugin argument specification.
|
||||
|
||||
[types.generatoroptions]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/generatoroptions.go
|
||||
[types.secretargs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/secretargs.go
|
||||
[types.configmapargs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/configmapargs.go
|
||||
[config.fieldspec]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/fieldspec.go
|
||||
[types.objectmeta]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/objectmeta.go
|
||||
[types.selector]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/selector.go
|
||||
[types.replica]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/replica.go
|
||||
[types.patchstrategicmerge]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchstrategicmerge.go
|
||||
[types.patchtarget]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchtarget.go
|
||||
[image.image]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/image.go
|
||||
|
||||
## _AnnotationTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `commonAnnotations`
|
||||
|
||||
Adds annotions (non-identifying metadata) to add
|
||||
all resources. Like labels, these are key value
|
||||
pairs.
|
||||
|
||||
```
|
||||
commonAnnotations:
|
||||
oncallPager: 800-555-1212
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Annotations map\[string\]string
|
||||
>
|
||||
> FieldSpecs \[\][config.FieldSpec]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: AnnotationsTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> annotations:
|
||||
> app: myApp
|
||||
> greeting/morning: a string with blanks
|
||||
> fieldSpecs:
|
||||
> - path: metadata/annotations
|
||||
> create: true
|
||||
> ```
|
||||
|
||||
## _ConfigMapGenerator_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `configMapGenerator`
|
||||
|
||||
Each entry in this list results in the creation of
|
||||
one ConfigMap resource (it's a generator of n maps).
|
||||
|
||||
The example below creates three ConfigMaps. One with the names and contents of
|
||||
the given files, one with key/value as data, and a third which sets an
|
||||
annotation and label via `options` for that single ConfigMap.
|
||||
|
||||
Each configMapGenerator item accepts a parameter of
|
||||
`behavior: [create|replace|merge]`.
|
||||
This allows an overlay to modify or
|
||||
replace an existing configMap from the parent.
|
||||
|
||||
Also, each entry has an `options` field, that has the
|
||||
same subfields as the kustomization file's `generatorOptions` field.
|
||||
|
||||
This `options` field allows one to add labels and/or
|
||||
annotations to the generated instance, or to individually
|
||||
disable the name suffix hash for that instance.
|
||||
Labels and annotations added here will not be overwritten
|
||||
by the global options associated with the kustomization
|
||||
file `generatorOptions` field. However, due to how
|
||||
booleans behave, if the global `generatorOptions` field
|
||||
specifies `disableNameSuffixHash: true`, this will
|
||||
trump any attempt to locally override it.
|
||||
|
||||
```
|
||||
# These labels are added to all configmaps and secrets.
|
||||
generatorOptions:
|
||||
labels:
|
||||
fruit: apple
|
||||
|
||||
configMapGenerator:
|
||||
- name: my-java-server-props
|
||||
behavior: merge
|
||||
files:
|
||||
- application.properties
|
||||
- more.properties
|
||||
- name: my-java-server-env-vars
|
||||
literals:
|
||||
- JAVA_HOME=/opt/java/jdk
|
||||
- JAVA_TOOL_OPTIONS=-agentlib:hprof
|
||||
options:
|
||||
disableNameSuffixHash: true
|
||||
labels:
|
||||
pet: dog
|
||||
- name: dashboards
|
||||
files:
|
||||
- mydashboard.json
|
||||
options:
|
||||
annotations:
|
||||
dashboard: "1"
|
||||
labels:
|
||||
app.kubernetes.io/name: "app1"
|
||||
```
|
||||
|
||||
It is also possible to
|
||||
[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file)
|
||||
to set a name different than the filename.
|
||||
|
||||
The example below creates a ConfigMap
|
||||
with the name of file as `myFileName.ini`
|
||||
while the _actual_ filename from which the
|
||||
configmap is created is `whatever.ini`.
|
||||
|
||||
```
|
||||
configMapGenerator:
|
||||
- name: app-whatever
|
||||
files:
|
||||
- myFileName.ini=whatever.ini
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> [types.ConfigMapArgs]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: ConfigMapGenerator
|
||||
> metadata:
|
||||
> name: mymap
|
||||
> envs:
|
||||
> - devops.env
|
||||
> - uxteam.env
|
||||
> literals:
|
||||
> - FRUIT=apple
|
||||
> - VEGETABLE=carrot
|
||||
> ```
|
||||
|
||||
## _ImageTagTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `images`
|
||||
|
||||
Images modify the name, tags and/or digest for images
|
||||
without creating patches. E.g. Given this
|
||||
kubernetes Deployment fragment:
|
||||
|
||||
```
|
||||
containers:
|
||||
- name: mypostgresdb
|
||||
image: postgres:8
|
||||
- name: nginxapp
|
||||
image: nginx:1.7.9
|
||||
- name: myapp
|
||||
image: my-demo-app:latest
|
||||
- name: alpine-app
|
||||
image: alpine:3.7
|
||||
```
|
||||
|
||||
one can change the `image` in the following ways:
|
||||
|
||||
- `postgres:8` to `my-registry/my-postgres:v1`,
|
||||
- nginx tag `1.7.9` to `1.8.0`,
|
||||
- image name `my-demo-app` to `my-app`,
|
||||
- alpine's tag `3.7` to a digest value
|
||||
|
||||
all with the following _kustomization_:
|
||||
|
||||
```
|
||||
images:
|
||||
- name: postgres
|
||||
newName: my-registry/my-postgres
|
||||
newTag: v1
|
||||
- name: nginx
|
||||
newTag: 1.8.0
|
||||
- name: my-demo-app
|
||||
newName: my-app
|
||||
- name: alpine
|
||||
digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> ImageTag [image.Image]
|
||||
>
|
||||
> FieldSpecs \[\][config.FieldSpec]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: ImageTagTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> imageTag:
|
||||
> name: nginx
|
||||
> newTag: v2
|
||||
> ```
|
||||
|
||||
## _LabelTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `commonLabels`
|
||||
|
||||
Adds labels to all resources and selectors
|
||||
|
||||
```
|
||||
commonLabels:
|
||||
someName: someValue
|
||||
owner: alice
|
||||
app: bingo
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Labels map\[string\]string
|
||||
>
|
||||
> FieldSpecs \[\][config.FieldSpec]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: LabelTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> labels:
|
||||
> app: myApp
|
||||
> env: production
|
||||
> fieldSpecs:
|
||||
> - path: metadata/labels
|
||||
> create: true
|
||||
> ```
|
||||
|
||||
## _NamespaceTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `namespace`
|
||||
|
||||
Adds namespace to all resources
|
||||
|
||||
```
|
||||
namespace: my-namespace
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> [types.ObjectMeta]
|
||||
>
|
||||
> FieldSpecs \[\][config.FieldSpec]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: NamespaceTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> namespace: test
|
||||
> fieldSpecs:
|
||||
> - path: metadata/namespace
|
||||
> create: true
|
||||
> - path: subjects
|
||||
> kind: RoleBinding
|
||||
> group: rbac.authorization.k8s.io
|
||||
> - path: subjects
|
||||
> kind: ClusterRoleBinding
|
||||
> group: rbac.authorization.k8s.io
|
||||
> ```
|
||||
|
||||
## _PatchesJson6902_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `patchesJson6902`
|
||||
|
||||
Each entry in this list should resolve to
|
||||
a kubernetes object and a JSON patch that will be applied
|
||||
to the object.
|
||||
The JSON patch is documented at <https://tools.ietf.org/html/rfc6902>
|
||||
|
||||
target field points to a kubernetes object within the same kustomization
|
||||
by the object's group, version, kind, name and namespace.
|
||||
path field is a relative file path of a JSON patch file.
|
||||
The content in this patch file can be either in JSON format as
|
||||
|
||||
```
|
||||
[
|
||||
{"op": "add", "path": "/some/new/path", "value": "value"},
|
||||
{"op": "replace", "path": "/some/existing/path", "value": "new value"}
|
||||
]
|
||||
```
|
||||
|
||||
or in YAML format as
|
||||
|
||||
```
|
||||
- op: add
|
||||
path: /some/new/path
|
||||
value: value
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: new value
|
||||
```
|
||||
|
||||
```
|
||||
patchesJson6902:
|
||||
- target:
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
path: add_init_container.yaml
|
||||
- target:
|
||||
version: v1
|
||||
kind: Service
|
||||
name: my-service
|
||||
path: add_service_annotation.yaml
|
||||
```
|
||||
|
||||
The patch content can be an inline string as well:
|
||||
|
||||
```
|
||||
patchesJson6902:
|
||||
- target:
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: my-deployment
|
||||
patch: |-
|
||||
- op: add
|
||||
path: /some/new/path
|
||||
value: value
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: "new value"
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Target [types.PatchTarget]
|
||||
>
|
||||
> Path string
|
||||
>
|
||||
> JsonOp string
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: PatchJson6902Transformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> target:
|
||||
> group: apps
|
||||
> version: v1
|
||||
> kind: Deployment
|
||||
> name: my-deploy
|
||||
> path: jsonpatch.json
|
||||
> ```
|
||||
|
||||
## _PatchesStrategicMerge_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `patchesStrategicMerge`
|
||||
|
||||
Each entry in this list should be either a relative
|
||||
file path or an inline content
|
||||
resolving to a partial or complete resource
|
||||
definition.
|
||||
|
||||
The names in these (possibly partial) resource
|
||||
files must match names already loaded via the
|
||||
`resources` field. These entries are used to
|
||||
_patch_ (modify) the known resources.
|
||||
|
||||
Small patches that do one thing are best, e.g. modify
|
||||
a memory request/limit, change an env var in a
|
||||
ConfigMap, etc. Small patches are easy to review and
|
||||
easy to mix together in overlays.
|
||||
|
||||
```
|
||||
patchesStrategicMerge:
|
||||
- service_port_8888.yaml
|
||||
- deployment_increase_replicas.yaml
|
||||
- deployment_increase_memory.yaml
|
||||
```
|
||||
|
||||
The patch content can be a inline string as well.
|
||||
|
||||
```
|
||||
patchesStrategicMerge:
|
||||
- |-
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: nginx
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nignx:latest
|
||||
```
|
||||
|
||||
Note that kustomize does not support more than one patch
|
||||
for the same object that contain a _delete_ directive. To remove
|
||||
several fields / slice elements from an object create a single
|
||||
patch that performs all the needed deletions.
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Paths \[\][types.PatchStrategicMerge]
|
||||
>
|
||||
> Patches string
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: PatchStrategicMergeTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> paths:
|
||||
> - patch.yaml
|
||||
> ```
|
||||
|
||||
## _PatchTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `patches`
|
||||
|
||||
Each entry in this list should resolve to an Patch
|
||||
object, which includes a patch and a target selector.
|
||||
The patch can be either a strategic merge patch or a
|
||||
JSON patch. it can be either a patch file or an inline
|
||||
string. The target selects
|
||||
resources by group, version, kind, name, namespace,
|
||||
labelSelector and annotationSelector. A resource
|
||||
which matches all the specified fields is selected
|
||||
to apply the patch.
|
||||
|
||||
```
|
||||
patches:
|
||||
- path: patch.yaml
|
||||
target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
name: deploy.*
|
||||
labelSelector: "env=dev"
|
||||
annotationSelector: "zone=west"
|
||||
- patch: |-
|
||||
- op: replace
|
||||
path: /some/existing/path
|
||||
value: new value
|
||||
target:
|
||||
kind: MyKind
|
||||
labelSelector: "env=dev"
|
||||
```
|
||||
|
||||
The `name` and `namespace` fields of the patch target selector are
|
||||
automatically anchored regular expressions. This means that the value `myapp`
|
||||
is equivalent to `^myapp$`.
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Path string
|
||||
>
|
||||
> Patch string
|
||||
>
|
||||
> Target \*[types.Selector]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: PatchTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> patch: '[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "nginx:latest"}]'
|
||||
> target:
|
||||
> name: .*Deploy
|
||||
> kind: Deployment
|
||||
> ```
|
||||
|
||||
## _PrefixSuffixTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field names: `namePrefix`, `nameSuffix`
|
||||
|
||||
Prepends or postfixes the value to the names
|
||||
of all resources.
|
||||
|
||||
E.g. a deployment named `wordpress` could
|
||||
become `alices-wordpress` or `wordpress-v2`
|
||||
or `alices-wordpress-v2`.
|
||||
|
||||
```
|
||||
namePrefix: alices-
|
||||
nameSuffix: -v2
|
||||
```
|
||||
|
||||
The suffix is appended before the content hash if
|
||||
the resource type is ConfigMap or Secret.
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Prefix string
|
||||
>
|
||||
> Suffix string
|
||||
>
|
||||
> FieldSpecs \[\][config.FieldSpec]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: PrefixSuffixTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> prefix: baked-
|
||||
> suffix: -pie
|
||||
> fieldSpecs:
|
||||
> - path: metadata/name
|
||||
> ```
|
||||
|
||||
## _ReplicaCountTransformer_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `replicas`
|
||||
|
||||
Replicas modified the number of replicas for a resource.
|
||||
|
||||
E.g. Given this kubernetes Deployment fragment:
|
||||
|
||||
```
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: deployment-name
|
||||
spec:
|
||||
replicas: 3
|
||||
```
|
||||
|
||||
one can change the number of replicas to 5
|
||||
by adding the following to your kustomization:
|
||||
|
||||
```
|
||||
replicas:
|
||||
- name: deployment-name
|
||||
count: 5
|
||||
```
|
||||
|
||||
This field accepts a list, so many resources can
|
||||
be modified at the same time.
|
||||
|
||||
As this declaration does not take in a `kind:` nor a `group:`
|
||||
it will match any `group` and `kind` that has a matching name and
|
||||
that is one of:
|
||||
|
||||
- `Deployment`
|
||||
- `ReplicationController`
|
||||
- `ReplicaSet`
|
||||
- `StatefulSet`
|
||||
|
||||
For more complex use cases, revert to using a patch.
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> Replica [types.Replica]
|
||||
>
|
||||
> FieldSpecs \[\][config.FieldSpec]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: ReplicaCountTransformer
|
||||
> metadata:
|
||||
> name: not-important-to-example
|
||||
> replica:
|
||||
> name: myapp
|
||||
> count: 23
|
||||
> fieldSpecs:
|
||||
> - path: spec/replicas
|
||||
> create: true
|
||||
> kind: Deployment
|
||||
> - path: spec/replicas
|
||||
> create: true
|
||||
> kind: ReplicationController
|
||||
> ```
|
||||
|
||||
## _SecretGenerator_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `secretGenerator`
|
||||
|
||||
Each entry in the argument list
|
||||
results in the creation of
|
||||
one Secret resource
|
||||
(it's a generator of n secrets).
|
||||
|
||||
This works like the `configMapGenerator` field
|
||||
described above.
|
||||
|
||||
```
|
||||
secretGenerator:
|
||||
- name: app-tls
|
||||
files:
|
||||
- secret/tls.cert
|
||||
- secret/tls.key
|
||||
type: "kubernetes.io/tls"
|
||||
- name: app-tls-namespaced
|
||||
# you can define a namespace to generate
|
||||
# a secret in, defaults to: "default"
|
||||
namespace: apps
|
||||
files:
|
||||
- tls.crt=catsecret/tls.cert
|
||||
- tls.key=secret/tls.key
|
||||
type: "kubernetes.io/tls"
|
||||
- name: env_file_secret
|
||||
envs:
|
||||
- env.txt
|
||||
type: Opaque
|
||||
- name: secret-with-annotation
|
||||
files:
|
||||
- app-config.yaml
|
||||
type: Opaque
|
||||
options:
|
||||
annotations:
|
||||
app_config: "true"
|
||||
labels:
|
||||
app.kubernetes.io/name: "app2"
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> [types.ObjectMeta]
|
||||
>
|
||||
> [types.SecretArgs]
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: SecretGenerator
|
||||
> metadata:
|
||||
> name: my-secret
|
||||
> namespace: whatever
|
||||
> behavior: merge
|
||||
> envs:
|
||||
> - a.env
|
||||
> - b.env
|
||||
> files:
|
||||
> - obscure=longsecret.txt
|
||||
> literals:
|
||||
> - FRUIT=apple
|
||||
> - VEGETABLE=carrot
|
||||
> ```
|
||||
|
||||
## _HelmChartInflationGenerator_
|
||||
|
||||
### Usage via `kustomization.yaml`
|
||||
|
||||
#### field name: `helmChartInflationGenerator`
|
||||
|
||||
Each entry in the argument list results in the pulling
|
||||
and rendering of a helm chart.
|
||||
|
||||
Each entry can have following fields:
|
||||
|
||||
- `chartName`: The name of the chart that you want to use.
|
||||
- `chartRepoUrl`: [Optional] The URL of the repository which contains the chart. If
|
||||
this is provided, the plugin will try to fetch remote charts. Otherwise it will
|
||||
try to load local chart in `chartHome`.
|
||||
- `chartVersion`: [Optional] Version of the chart. Will use latest version
|
||||
if this is omitted.
|
||||
- `chartHome`: [Optional] Provide the path to the parent directory for local chart.
|
||||
- `chartRelease`: [Optional] The name of the repo where to find the chart.
|
||||
- `values`: [Optional] A path to the values file.
|
||||
- `releaseName`: [Optional] The release name that will be set in the chart.
|
||||
- `releaseNamespace`: [Optional] The namespace which will be used by `--namespace`
|
||||
flag in `helm template` command.
|
||||
- `helmBin`: [Optional] Path to helm binary. Default is `helm`.
|
||||
- `helmHome`: [Optional] Path to helm home directory.
|
||||
|
||||
```
|
||||
helmChartInflationGenerator:
|
||||
- chartName: minecraft
|
||||
chartRepoUrl: https://kubernetes-charts.storage.googleapis.com
|
||||
chartVersion: v1.2.0
|
||||
releaseName: test
|
||||
releaseNamespace: testNamespace
|
||||
```
|
||||
|
||||
### Usage via plugin
|
||||
|
||||
#### Arguments
|
||||
|
||||
> ChartName string
|
||||
>
|
||||
> ChartVersion string
|
||||
>
|
||||
> ChartRepoURL string
|
||||
>
|
||||
> ChartHome string
|
||||
>
|
||||
> ChartRepoName string
|
||||
>
|
||||
> HelmBin string
|
||||
>
|
||||
> HelmHome string
|
||||
>
|
||||
> Values string
|
||||
>
|
||||
> ReleaseName string
|
||||
>
|
||||
> ReleaseNamespace string
|
||||
|
||||
#### Example
|
||||
|
||||
> ```
|
||||
> apiVersion: builtin
|
||||
> kind: HelmChartInflationGenerator
|
||||
> metadata:
|
||||
> name: myMap
|
||||
> chartName: minecraft
|
||||
> chartRepoUrl: https://kubernetes-charts.storage.googleapis.com
|
||||
> chartVersion: v1.2.0
|
||||
> helmBin: /usr/bin/helm
|
||||
> helmHome: /tmp/helmHome
|
||||
> releaseName: test
|
||||
> releaseNamespace: testNamespace
|
||||
> values: values.yaml
|
||||
> ```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,230 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/extending_kustomize/execpluginguidedexample" />
|
||||
|
||||
|
||||
This is a (no reading allowed!) 60 second copy/paste guided
|
||||
example. Full plugin docs [here](..).
|
||||
|
||||
This demo writes and uses a somewhat ridiculous
|
||||
_exec_ plugin (written in bash) that generates a
|
||||
`ConfigMap`.
|
||||
|
||||
This is a guide to try it without damaging your
|
||||
current setup.
|
||||
|
||||
#### requirements
|
||||
|
||||
* linux, git, curl, Go 1.13
|
||||
|
||||
## Make a place to work
|
||||
|
||||
```
|
||||
DEMO=$(mktemp -d)
|
||||
```
|
||||
|
||||
## Create a kustomization
|
||||
|
||||
Make a kustomization directory to
|
||||
hold all your config:
|
||||
|
||||
```
|
||||
MYAPP=$DEMO/myapp
|
||||
mkdir -p $MYAPP
|
||||
```
|
||||
|
||||
Make a deployment config:
|
||||
|
||||
```
|
||||
cat <<'EOF' >$MYAPP/deployment.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: the-deployment
|
||||
spec:
|
||||
replicas: 3
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: the-container
|
||||
image: monopole/hello:1
|
||||
command: ["/hello",
|
||||
"--port=8080",
|
||||
"--date=$(THE_DATE)",
|
||||
"--enableRiskyFeature=$(ENABLE_RISKY)"]
|
||||
ports:
|
||||
- containerPort: 8080
|
||||
env:
|
||||
- name: THE_DATE
|
||||
valueFrom:
|
||||
configMapKeyRef:
|
||||
name: the-map
|
||||
key: today
|
||||
- name: ALT_GREETING
|
||||
valueFrom:
|
||||
configMapKeyRef:
|
||||
name: the-map
|
||||
key: altGreeting
|
||||
- name: ENABLE_RISKY
|
||||
valueFrom:
|
||||
configMapKeyRef:
|
||||
name: the-map
|
||||
key: enableRisky
|
||||
EOF
|
||||
```
|
||||
|
||||
Make a service config:
|
||||
|
||||
```
|
||||
cat <<EOF >$MYAPP/service.yaml
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: the-service
|
||||
spec:
|
||||
type: LoadBalancer
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 8666
|
||||
targetPort: 8080
|
||||
EOF
|
||||
```
|
||||
|
||||
Now make a config file for the plugin
|
||||
you're about to write.
|
||||
|
||||
This config file is just another k8s resource
|
||||
object. The values of its `apiVersion` and `kind`
|
||||
fields are used to _find_ the plugin code on your
|
||||
filesystem (more on this later).
|
||||
|
||||
```
|
||||
cat <<'EOF' >$MYAPP/cmGenerator.yaml
|
||||
apiVersion: myDevOpsTeam
|
||||
kind: SillyConfigMapGenerator
|
||||
metadata:
|
||||
name: whatever
|
||||
argsOneLiner: Bienvenue true
|
||||
EOF
|
||||
```
|
||||
|
||||
Finally, make a kustomization file
|
||||
referencing all of the above:
|
||||
|
||||
```
|
||||
cat <<EOF >$MYAPP/kustomization.yaml
|
||||
commonLabels:
|
||||
app: hello
|
||||
resources:
|
||||
- deployment.yaml
|
||||
- service.yaml
|
||||
generators:
|
||||
- cmGenerator.yaml
|
||||
EOF
|
||||
```
|
||||
|
||||
Review the files
|
||||
|
||||
```
|
||||
ls -C1 $MYAPP
|
||||
```
|
||||
|
||||
## Make a home for plugins
|
||||
|
||||
Plugins must live in a particular place for
|
||||
kustomize to find them.
|
||||
|
||||
This demo will use the ephemeral directory:
|
||||
|
||||
```
|
||||
PLUGIN_ROOT=$DEMO/kustomize/plugin
|
||||
```
|
||||
|
||||
The plugin config defined above in
|
||||
`$MYAPP/cmGenerator.yaml` specifies:
|
||||
|
||||
> ```
|
||||
> apiVersion: myDevOpsTeam
|
||||
> kind: SillyConfigMapGenerator
|
||||
> ```
|
||||
|
||||
This means the plugin must live in a directory
|
||||
named:
|
||||
|
||||
```
|
||||
MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator
|
||||
|
||||
mkdir -p $MY_PLUGIN_DIR
|
||||
```
|
||||
|
||||
The directory name is the plugin config's
|
||||
_apiVersion_ followed by its lower-cased _kind_.
|
||||
|
||||
A plugin gets its own directory to hold itself,
|
||||
its tests and any supplemental data files it
|
||||
might need.
|
||||
|
||||
## Create the plugin
|
||||
|
||||
There are two kinds of plugins, _exec_ and _Go_.
|
||||
|
||||
Make an _exec_ plugin, installing it to the
|
||||
correct directory and file name. The file name
|
||||
must match the plugin's _kind_ (in this case,
|
||||
`SillyConfigMapGenerator`):
|
||||
|
||||
```
|
||||
cat <<'EOF' >$MY_PLUGIN_DIR/SillyConfigMapGenerator
|
||||
#!/bin/bash
|
||||
# Skip the config file name argument.
|
||||
shift
|
||||
today=`date +%F`
|
||||
echo "
|
||||
kind: ConfigMap
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: the-map
|
||||
data:
|
||||
today: $today
|
||||
altGreeting: "$1"
|
||||
enableRisky: "$2"
|
||||
"
|
||||
EOF
|
||||
```
|
||||
|
||||
By definition, an _exec_ plugin must be executable:
|
||||
|
||||
```
|
||||
chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator
|
||||
```
|
||||
|
||||
## Install kustomize
|
||||
|
||||
Per the [instructions](/kustomize/installation):
|
||||
|
||||
```
|
||||
curl -s "https://raw.githubusercontent.com/\
|
||||
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
|
||||
mkdir -p $DEMO/bin
|
||||
mv kustomize $DEMO/bin
|
||||
```
|
||||
|
||||
## Review the layout
|
||||
|
||||
```
|
||||
tree $DEMO
|
||||
```
|
||||
|
||||
## Build your app, using the plugin
|
||||
|
||||
```
|
||||
XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP
|
||||
```
|
||||
|
||||
Above, if you had set
|
||||
|
||||
> ```
|
||||
> PLUGIN_ROOT=$HOME/.config/kustomize/plugin
|
||||
> ```
|
||||
|
||||
there would be no need to use `XDG_CONFIG_HOME` in the
|
||||
_kustomize_ command above.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,120 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/extending_kustomize/goplugincaveats" />
|
||||
|
||||
[plugin package]: https://golang.org/pkg/plugin
|
||||
[Go modules]: https://github.com/golang/go/wiki/Modules
|
||||
[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
|
||||
[tensorflow plugin]: https://www.tensorflow.org/guide/extend/op
|
||||
|
||||
A _Go plugin_ is a compilation artifact described
|
||||
by the Go [plugin package]. It is built with
|
||||
special flags and cannot run on its own.
|
||||
It must be loaded into a running Go program.
|
||||
|
||||
> A normal program written in Go might be usable
|
||||
> as _exec plugin_, but is not a _Go plugin_.
|
||||
|
||||
Go plugins allow kustomize extensions that run
|
||||
without the cost marshalling/unmarshalling all
|
||||
resource data to/from a subprocess for each plugin
|
||||
run. The Go plugin API assures a certain level of
|
||||
consistency to avoid confusing downstream
|
||||
transformers.
|
||||
|
||||
Go plugins work as described in the [plugin
|
||||
package], but fall short of common notions
|
||||
associated with the word _plugin_.
|
||||
|
||||
## The skew problem
|
||||
|
||||
Go plugin compilation creates an [ELF] formatted
|
||||
`.so` file, which by definition has no information
|
||||
about the provenance of the object code.
|
||||
|
||||
Skew between the compilation conditions (versions
|
||||
of package dependencies, `GOOS`, `GOARCH`) of the
|
||||
main program ELF and the plugin ELF will cause
|
||||
plugin load failure, with non-helpful error
|
||||
messages.
|
||||
|
||||
Exec plugins also lack provenance, but won't fail
|
||||
due to compilation skew.
|
||||
|
||||
In either case, the only sensible way to share a
|
||||
plugin is as some kind of _bundle_ (a git repo
|
||||
URL, a git archive file, a tar file, etc.)
|
||||
containing source code, tests and associated data,
|
||||
unpackable under
|
||||
`$XDG_CONFIG_HOME/kustomize/plugin`.
|
||||
|
||||
In the case of a Go plugin, an _end user_
|
||||
accepting a shared plugin _must compile both
|
||||
kustomize and the plugin_.
|
||||
|
||||
This means a one-time run of
|
||||
|
||||
```
|
||||
# Or whatever is appropriate at time of reading
|
||||
GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api
|
||||
```
|
||||
|
||||
and then a normal development cycle using
|
||||
|
||||
```
|
||||
go build -buildmode plugin \
|
||||
-o ${wherever}/${kind}.so ${wherever}/${kind}.go
|
||||
```
|
||||
|
||||
with paths and the release version tag (e.g. `v3.0.0`)
|
||||
adjusted as needed.
|
||||
|
||||
For comparison, consider what one
|
||||
must do to write a [tensorflow plugin].
|
||||
|
||||
## Why support Go plugins
|
||||
|
||||
### Safety
|
||||
|
||||
The Go plugin developer sees the same API offered
|
||||
to native kustomize operations, assuring certain
|
||||
semantics, invariants, checks, etc. An exec
|
||||
plugin sub-process dealing with this via
|
||||
stdin/stdout will have an easier time screwing
|
||||
things up for downstream transformers and
|
||||
consumers.
|
||||
|
||||
Minor point: if the plugin reads files via
|
||||
the kustomize-provided file `Loader` interface, it
|
||||
will be constrained by kustomize file loading
|
||||
restrictions. Of course, nothing but a code audit
|
||||
prevents a Go plugin from importing the `io` package
|
||||
and doing whatever it wants.
|
||||
|
||||
### Debugging
|
||||
|
||||
A Go plugin developer can debug the plugin _in
|
||||
situ_, setting breakpoints inside the plugin and
|
||||
elsewhere while running a plugin in feature tests.
|
||||
|
||||
To get the best of both worlds (shareability and safety),
|
||||
a developer can write an `.go` program that functions
|
||||
as an _exec plugin_, but can be processed by `go generate`
|
||||
to emit a _Go plugin_ (or vice versa).
|
||||
|
||||
### Unit of contribution
|
||||
|
||||
All the builtin generators and transformers
|
||||
are themselves Go plugins. This means that
|
||||
the kustomize maintainers can promote a contributed
|
||||
plugin to a builtin without needing code changes
|
||||
(beyond those mandated by normal code review).
|
||||
|
||||
### Ecosystems grow through use
|
||||
|
||||
Tooling could ease Go plugin _sharing_, but this
|
||||
requires some critical mass of Go plugin
|
||||
_authoring_, which in turn is hampered by
|
||||
confusion around sharing. [Go modules], once they
|
||||
are more widely adopted, will solve the
|
||||
biggest plugin sharing difficulty: ambiguous
|
||||
plugin vs host dependencies.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -8,371 +8,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/extending_kustomize/gopluginguidedexample" />
|
||||
|
||||
|
||||
# Go Plugin Guided Example for Linux
|
||||
|
||||
[SopsEncodedSecrets repository]: https://github.com/monopole/sopsencodedsecrets
|
||||
[Go plugin]: https://golang.org/pkg/plugin
|
||||
[Go plugin caveats]: goPluginCaveats.md
|
||||
|
||||
This is a (no reading allowed!) 60 second copy/paste guided
|
||||
example.
|
||||
|
||||
Full plugin docs [here](README.md).
|
||||
Be sure to read the [Go plugin caveats].
|
||||
|
||||
This demo uses a Go plugin, `SopsEncodedSecrets`,
|
||||
that lives in the [sopsencodedsecrets repository].
|
||||
This is an inprocess [Go plugin], not an
|
||||
sub-process exec plugin that happens to be written
|
||||
in Go (which is another option for Go authors).
|
||||
|
||||
This is a guide to try it without damaging your
|
||||
current setup.
|
||||
|
||||
#### requirements
|
||||
|
||||
* linux, git, curl, Go 1.13
|
||||
|
||||
For encryption
|
||||
|
||||
* gpg
|
||||
|
||||
Or
|
||||
|
||||
* Google cloud (gcloud) install
|
||||
* a Google account with KMS permission
|
||||
|
||||
## Make a place to work
|
||||
|
||||
```shell
|
||||
# Keeping these separate to avoid cluttering the DEMO dir.
|
||||
DEMO=$(mktemp -d)
|
||||
tmpGoPath=$(mktemp -d)
|
||||
```
|
||||
|
||||
## Install kustomize
|
||||
|
||||
Need v3.0.0 for what follows, and you must _compile_
|
||||
it (not download the binary from the release page):
|
||||
|
||||
```shell
|
||||
GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize
|
||||
```
|
||||
|
||||
## Make a home for plugins
|
||||
|
||||
A kustomize plugin is fully determined by
|
||||
its configuration file and source code.
|
||||
|
||||
[required fields]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
|
||||
|
||||
Kustomize plugin configuration files are formatted
|
||||
as kubernetes resource objects, meaning
|
||||
`apiVersion`, `kind` and `metadata` are [required
|
||||
fields] in these config files.
|
||||
|
||||
The kustomize program reads the config file
|
||||
(because the config file name appears in the
|
||||
`generators` or `transformers` field in the
|
||||
kustomization file), then locates the Go plugin's
|
||||
object code at the following location:
|
||||
|
||||
> ```shell
|
||||
> $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so
|
||||
> ```
|
||||
|
||||
where `lKind` holds the lowercased kind. The
|
||||
plugin is then loaded and fed its config, and the
|
||||
plugin's output becomes part of the overall
|
||||
`kustomize build` process.
|
||||
|
||||
The same plugin might be used multiple times in
|
||||
one kustomize build, but with different config
|
||||
files. Also, kustomize might customize config
|
||||
data before sending it to the plugin, for whatever
|
||||
reason. For these reasons, kustomize owns the
|
||||
mapping between plugins and config data; it's not
|
||||
left to plugins to find their own config.
|
||||
|
||||
This demo will house the plugin it uses at the
|
||||
ephemeral directory
|
||||
|
||||
```shell
|
||||
PLUGIN_ROOT=$DEMO/kustomize/plugin
|
||||
```
|
||||
|
||||
and ephemerally set `XDG_CONFIG_HOME` on a command
|
||||
line below.
|
||||
|
||||
### What apiVersion and kind
|
||||
|
||||
At this stage in the development of kustomize
|
||||
plugins, plugin code doesn't know or care what
|
||||
`apiVersion` or `kind` appears in the config file
|
||||
sent to it.
|
||||
|
||||
The plugin could check these fields, but it's the
|
||||
remaining fields that provide actual configuration
|
||||
data, and at this point the successful parsing of
|
||||
these other fields are the only thing that matters
|
||||
to a plugin.
|
||||
|
||||
This demo uses a plugin called _SopsEncodedSecrets_,
|
||||
and it lives in the [SopsEncodedSecrets repository].
|
||||
|
||||
Somewhat arbitrarily, we'll chose to install
|
||||
this plugin with
|
||||
|
||||
```shell
|
||||
apiVersion=mygenerators
|
||||
kind=SopsEncodedSecrets
|
||||
```
|
||||
|
||||
### Define the plugin's home dir
|
||||
|
||||
By convention, the ultimate home of the plugin
|
||||
code and supplemental data, tests, documentation,
|
||||
etc. is the lowercase form of its kind.
|
||||
|
||||
```shell
|
||||
lKind=$(echo $kind | awk '{print tolower($0)}')
|
||||
```
|
||||
|
||||
### Download the SopsEncodedSecrets plugin
|
||||
|
||||
In this case, the repo name matches the lowercase
|
||||
kind already, so we just clone the repo and get
|
||||
the proper directory name automatically:
|
||||
|
||||
```shell
|
||||
mkdir -p $PLUGIN_ROOT/${apiVersion}
|
||||
cd $PLUGIN_ROOT/${apiVersion}
|
||||
git clone git@github.com:monopole/sopsencodedsecrets.git
|
||||
```
|
||||
|
||||
Remember this directory:
|
||||
|
||||
```shell
|
||||
MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind}
|
||||
```
|
||||
|
||||
### Try the plugin's own test
|
||||
|
||||
Plugins may come with their own tests.
|
||||
This one does, and it hopefully passes:
|
||||
|
||||
```shell
|
||||
cd $MY_PLUGIN_DIR
|
||||
go test SopsEncodedSecrets_test.go
|
||||
```
|
||||
|
||||
Build the object code for use by kustomize:
|
||||
|
||||
```shell
|
||||
cd $MY_PLUGIN_DIR
|
||||
GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go
|
||||
```
|
||||
|
||||
This step may succeed, but kustomize might
|
||||
ultimately fail to load the plugin because of
|
||||
dependency [skew].
|
||||
|
||||
[skew]: /docs/plugins/README.md#caveats
|
||||
[used in this demo]: #install-kustomize
|
||||
|
||||
On load failure
|
||||
|
||||
* be sure to build the plugin with the same
|
||||
version of Go (_go1.13_) on the same `$GOOS`
|
||||
(_linux_) and `$GOARCH` (_amd64_) used to build
|
||||
the kustomize being [used in this demo].
|
||||
|
||||
* change the plugin's dependencies in its `go.mod`
|
||||
to match the versions used by kustomize (check
|
||||
kustomize's `go.mod` used in its tagged commit).
|
||||
|
||||
Lacking tools and metadata to allow this to be
|
||||
automated, there won't be a Go plugin ecosystem.
|
||||
|
||||
Kustomize has adopted a Go plugin architecture as
|
||||
to ease accept new generators and transformers
|
||||
(just write a plugin), and to be sure that native
|
||||
operations (also constructed and tested as
|
||||
plugins) are compartmentalized, orderable and
|
||||
reusable instead of bizarrely woven throughout the
|
||||
code as a individual special cases.
|
||||
|
||||
## Create a kustomization
|
||||
|
||||
Make a kustomization directory to
|
||||
hold all your config:
|
||||
|
||||
```shell
|
||||
MYAPP=$DEMO/myapp
|
||||
mkdir -p $MYAPP
|
||||
```
|
||||
|
||||
Make a config file for the SopsEncodedSecrets plugin.
|
||||
|
||||
Its `apiVersion` and `kind` allow the plugin to be
|
||||
found:
|
||||
|
||||
```shell
|
||||
cat <<EOF >$MYAPP/secGenerator.yaml
|
||||
apiVersion: ${apiVersion}
|
||||
kind: ${kind}
|
||||
metadata:
|
||||
name: mySecretGenerator
|
||||
name: forbiddenValues
|
||||
namespace: production
|
||||
file: myEncryptedData.yaml
|
||||
keys:
|
||||
- ROCKET
|
||||
- CAR
|
||||
EOF
|
||||
```
|
||||
|
||||
This plugin expects to find more data in
|
||||
`myEncryptedData.yaml`; we'll get to that shortly.
|
||||
|
||||
Make a kustomization file referencing the plugin
|
||||
config:
|
||||
|
||||
```shell
|
||||
cat <<EOF >$MYAPP/kustomization.yaml
|
||||
commonLabels:
|
||||
app: hello
|
||||
generators:
|
||||
- secGenerator.yaml
|
||||
EOF
|
||||
```
|
||||
|
||||
Now generate the real encrypted data.
|
||||
|
||||
### Assure you have an encryption tool installed
|
||||
|
||||
We're going to use [sops](https://github.com/mozilla/sops) to encode a file. Choose either GPG or Google Cloud KMS as the secret provider to continue.
|
||||
|
||||
#### GPG
|
||||
|
||||
Try this:
|
||||
|
||||
```shell
|
||||
gpg --list-keys
|
||||
```
|
||||
|
||||
If it returns a list, presumably you've already created keys. If not, try import test keys from sops for dev.
|
||||
|
||||
```shell
|
||||
curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import
|
||||
SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A"
|
||||
```
|
||||
|
||||
#### Google Cloude KMS
|
||||
|
||||
Try this:
|
||||
|
||||
```shell
|
||||
gcloud kms keys list --location global --keyring sops
|
||||
```
|
||||
|
||||
If it succeeds, presumably you've already created keys and placed them in a keyring called sops. If not, do this:
|
||||
|
||||
```shell
|
||||
gcloud kms keyrings create sops --location global
|
||||
gcloud kms keys create sops-key --location global \
|
||||
--keyring sops --purpose encryption
|
||||
```
|
||||
|
||||
Extract your keyLocation for use below:
|
||||
|
||||
```shell
|
||||
keyLocation=$(\
|
||||
gcloud kms keys list --location global --keyring sops |\
|
||||
grep GOOGLE | cut -d " " -f1)
|
||||
echo $keyLocation
|
||||
```
|
||||
|
||||
### Install `sops`
|
||||
|
||||
```shell
|
||||
GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops
|
||||
```
|
||||
|
||||
### Create data encrypted with your private key
|
||||
|
||||
Create raw data to encrypt:
|
||||
|
||||
```shell
|
||||
cat <<EOF >$MYAPP/myClearData.yaml
|
||||
VEGETABLE: carrot
|
||||
ROCKET: saturn-v
|
||||
FRUIT: apple
|
||||
CAR: dymaxion
|
||||
EOF
|
||||
```
|
||||
|
||||
Encrypt the data into file the plugin wants to read:
|
||||
|
||||
With PGP
|
||||
|
||||
```shell
|
||||
$tmpGoPath/bin/sops --encrypt \
|
||||
--pgp $SOPS_PGP_FP \
|
||||
$MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
|
||||
```
|
||||
|
||||
Or GCP KMS
|
||||
|
||||
```shell
|
||||
$tmpGoPath/bin/sops --encrypt \
|
||||
--gcp-kms $keyLocation \
|
||||
$MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
|
||||
```
|
||||
|
||||
Review the files
|
||||
|
||||
```shell
|
||||
tree $DEMO
|
||||
```
|
||||
|
||||
This should look something like:
|
||||
|
||||
> ```shell
|
||||
> /tmp/tmp.0kIE9VclPt
|
||||
> ├── kustomize
|
||||
> │ └── plugin
|
||||
> │ └── mygenerators
|
||||
> │ └── sopsencodedsecrets
|
||||
> │ ├── go.mod
|
||||
> │ ├── go.sum
|
||||
> │ ├── LICENSE
|
||||
> │ ├── README.md
|
||||
> │ ├── SopsEncodedSecrets.go
|
||||
> │ ├── SopsEncodedSecrets.so
|
||||
> │ └── SopsEncodedSecrets_test.go
|
||||
> └── myapp
|
||||
> ├── kustomization.yaml
|
||||
> ├── myClearData.yaml
|
||||
> ├── myEncryptedData.yaml
|
||||
> └── secGenerator.yaml
|
||||
> ```
|
||||
|
||||
## Build your app, using the plugin
|
||||
|
||||
```shell
|
||||
XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP
|
||||
```
|
||||
|
||||
This should emit a kubernetes secret, with
|
||||
encrypted data for the names `ROCKET` and `CAR`.
|
||||
|
||||
Above, if you had set
|
||||
|
||||
> ```shell
|
||||
> PLUGIN_ROOT=$HOME/.config/kustomize/plugin
|
||||
> ```
|
||||
|
||||
there would be no need to use `XDG_CONFIG_HOME` in the
|
||||
_kustomize_ command above.
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,3 +9,5 @@ menu:
|
||||
---
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/installation/kustomize/" />
|
||||
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,15 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/installation/kustomize/binaries/" />
|
||||
|
||||
Binaries at various versions for linux, MacOs and Windows are published on the [releases page].
|
||||
|
||||
The following [script] detects your OS and downloads the appropriate kustomize binary to your
|
||||
current working directory.
|
||||
|
||||
```
|
||||
curl -s "https://raw.githubusercontent.com/\
|
||||
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
|
||||
```
|
||||
|
||||
[releases page]: https://github.com/kubernetes-sigs/kustomize/releases
|
||||
[script]: https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -10,12 +10,4 @@ description: >
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/installation/kustomize/chocolatey/" />
|
||||
|
||||
|
||||
```
|
||||
choco install kustomize
|
||||
```
|
||||
|
||||
For support on the chocolatey package
|
||||
and prior releases, see:
|
||||
|
||||
- [Choco Package](https://chocolatey.org/packages/kustomize)
|
||||
- [Package Source](https://github.com/kenmaglio/choco-kustomize)
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,15 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/installation/kustomize/homebrew/" />
|
||||
|
||||
|
||||
For [Homebrew](https://brew.sh) users:
|
||||
|
||||
```
|
||||
brew install kustomize
|
||||
```
|
||||
|
||||
For [MacPorts](https://www.macports.org) users:
|
||||
|
||||
```
|
||||
sudo port install kustomize
|
||||
```
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
@@ -9,36 +9,4 @@ description: >
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/installation/kustomize/source/" />
|
||||
|
||||
Requires [Go] to be installed.
|
||||
|
||||
## Install the kustomize CLI from source without cloning the repo
|
||||
|
||||
```
|
||||
GOBIN=$(pwd)/ GO111MODULE=on go get sigs.k8s.io/kustomize/kustomize/v3
|
||||
```
|
||||
|
||||
## Install the kustomize CLI from local source with cloning the repo
|
||||
|
||||
```
|
||||
# Need go 1.13 or higher
|
||||
unset GOPATH
|
||||
# see https://golang.org/doc/go1.13#modules
|
||||
unset GO111MODULES
|
||||
|
||||
# clone the repo
|
||||
git clone git@github.com:kubernetes-sigs/kustomize.git
|
||||
# get into the repo root
|
||||
cd kustomize
|
||||
|
||||
# Optionally checkout a particular tag if you don't
|
||||
# want to build at head
|
||||
git checkout kustomize/v3.2.3
|
||||
|
||||
# build the binary
|
||||
(cd kustomize; go install .)
|
||||
|
||||
# run it
|
||||
~/go/bin/kustomize version
|
||||
```
|
||||
|
||||
[Go]: https://golang.org
|
||||
Moved to https://github.com/kubernetes-sigs/cli-experimental
|
||||
Reference in New Issue
Block a user