mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-05-18 12:42:19 +00:00
684 lines
13 KiB
Markdown
684 lines
13 KiB
Markdown
<!--
|
|
TODO: Generate this file (or files) from
|
|
data in directories under plugin/builtin.
|
|
|
|
This file too hard to maintain distinctly
|
|
from what's going on in those directories.
|
|
We could expand pluginator to do this, since
|
|
it already scans the relevant files in the
|
|
relevant directory to generate the static
|
|
factory methods for plugins.
|
|
-->
|
|
|
|
# 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]: ../../api/types/generatoroptions.go
|
|
[types.SecretArgs]: ../../api/types/secretargs.go
|
|
[types.ConfigMapArgs]: ../../api/types/configmapargs.go
|
|
[config.FieldSpec]: ../../api/types/fieldspec.go
|
|
[types.ObjectMeta]: ../../api/types/objectmeta.go
|
|
[types.Selector]: ../../api/types/selector.go
|
|
[types.Replica]: ../../api/types/replica.go
|
|
[types.PatchStrategicMerge]: ../../api/types/patchstrategicmerge.go
|
|
[types.PatchTarget]: ../../api/types/patchtarget.go
|
|
[image.Image]: ../../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 two ConfigMaps. One with the
|
|
names and contents of the given files, the other with
|
|
key/value as data.
|
|
|
|
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.
|
|
|
|
```
|
|
configMapGenerator:
|
|
- name: my-java-server-props
|
|
files:
|
|
- application.properties
|
|
- more.properties
|
|
- name: my-java-server-env-vars
|
|
literals:
|
|
- JAVA_HOME=/opt/java/jdk
|
|
- JAVA_TOOL_OPTIONS=-agentlib:hprof
|
|
```
|
|
|
|
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.GeneratorOptions]
|
|
>
|
|
> [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: `image`
|
|
|
|
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).
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
### Usage via plugin
|
|
|
|
#### Arguments
|
|
|
|
> [types.ObjectMeta]
|
|
>
|
|
> [types.GeneratorOptions]
|
|
>
|
|
> [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
|
|
> ```
|