| title | linkTitle | type | description |
|---|---|---|---|
Builtin Plugins |
Builtin Plugins |
docs |
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
AnnotationsTransformeris triggered by thecommonAnnotationsfield). -
explicitly triggering the plugin via the
generatorsortransformersfield (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.
Adds annotions (non-identifying metadata) to add all resources. Like labels, these are key value pairs.
commonAnnotations:
oncallPager: 800-555-1212
Annotations map[string]string
FieldSpecs []config.FieldSpec
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
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 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
apiVersion: builtin kind: ConfigMapGenerator metadata: name: mymap envs: - devops.env - uxteam.env literals: - FRUIT=apple - VEGETABLE=carrot
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:8tomy-registry/my-postgres:v1,- nginx tag
1.7.9to1.8.0, - image name
my-demo-apptomy-app, - alpine's tag
3.7to 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
ImageTag image.Image
FieldSpecs []config.FieldSpec
apiVersion: builtin kind: ImageTagTransformer metadata: name: not-important-to-example imageTag: name: nginx newTag: v2
Adds labels to all resources and selectors
commonLabels:
someName: someValue
owner: alice
app: bingo
Labels map[string]string
FieldSpecs []config.FieldSpec
apiVersion: builtin kind: LabelTransformer metadata: name: not-important-to-example labels: app: myApp env: production fieldSpecs: - path: metadata/labels create: true
Adds namespace to all resources
namespace: my-namespace
FieldSpecs []config.FieldSpec
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
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"
Target types.PatchTarget
Path string
JsonOp string
apiVersion: builtin kind: PatchJson6902Transformer metadata: name: not-important-to-example target: group: apps version: v1 kind: Deployment name: my-deploy path: jsonpatch.json
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.
Paths []types.PatchStrategicMerge
Patches string
apiVersion: builtin kind: PatchStrategicMergeTransformer metadata: name: not-important-to-example paths: - patch.yaml
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$.
Path string
Patch string
Target *types.Selector
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
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.
Prefix string
Suffix string
FieldSpecs []config.FieldSpec
apiVersion: builtin kind: PrefixSuffixTransformer metadata: name: not-important-to-example prefix: baked- suffix: -pie fieldSpecs: - path: metadata/name
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:
DeploymentReplicationControllerReplicaSetStatefulSet
For more complex use cases, revert to using a patch.
Replica types.Replica
FieldSpecs []config.FieldSpec
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
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"
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