Kustomize – kustomization.yaml

Api-Reference: bases

Mon, 01 Jan 0001 00:00:00 +0000

The bases field was deprecated in v2.1.0

Move entries into the resources field. This allows bases - which are still a central concept - to be ordered relative to other input resources.

Api-Reference: commonAnnotations

Mon, 01 Jan 0001 00:00:00 +0000

Add annotations to all resources. If the annotation key already is present on the resource, the value will be overridden.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

commonAnnotations:
  oncallPager: 800-555-1212

Example

File Input

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

commonAnnotations:
  oncallPager: 800-555-1212

resources:
- deploy.yaml

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example
spec:
  ...

Build Output

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example
  annotations:
    oncallPager: 800-555-1212
spec:
  ...

Api-Reference: commonLabels

Mon, 01 Jan 0001 00:00:00 +0000

Add labels and selectors to all resources. If the label key already is present on the resource, the value will be overridden.

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.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

commonLabels:
  someName: someValue
  owner: alice
  app: bingo

Example

File Input

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

commonLabels:
  someName: someValue
  owner: alice
  app: bingo

resources:
- deploy.yaml
- service.yaml

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: example

Build Output

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

Api-Reference: components

Mon, 01 Jan 0001 00:00:00 +0000

Coming soon

Api-Reference: configMapGenerator

Mon, 01 Jan 0001 00:00:00 +0000

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.

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 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.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

configMapGenerator:
- name: app-whatever
  files:
  - myFileName.ini=whatever.ini

Api-Reference: crds

Mon, 01 Jan 0001 00:00:00 +0000

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”,

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

crds:
- crds/typeA.yaml
- crds/typeB.yaml

Api-Reference: generatorOptions

Mon, 01 Jan 0001 00:00:00 +0000

Additionally, generatorOptions can be set on a per resource level within each generator. For details on per-resource generatorOptions usage see field-name-configMapGenerator and See field-name-secretGenerator.

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

Api-Reference: images

Mon, 01 Jan 0001 00:00:00 +0000

Images modify the name, tags and/or digest for images without creating patches. E.g. Given this kubernetes Deployment fragment:

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:

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

Api-Reference: namePrefix

Mon, 01 Jan 0001 00:00:00 +0000

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namePrefix: alices-

A deployment named wordpress would become alices-wordpress.

Api-Reference: namespace

Mon, 01 Jan 0001 00:00:00 +0000

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.

Api-Reference: nameSuffix

Mon, 01 Jan 0001 00:00:00 +0000

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.

Api-Reference: patches

Mon, 01 Jan 0001 00:00:00 +0000

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).

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$.

Api-Reference: patchesJson6902

Mon, 01 Jan 0001 00:00:00 +0000

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

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:

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"

Api-Reference: patchesStrategicMerge

Mon, 01 Jan 0001 00:00:00 +0000

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.

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.

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.

Api-Reference: replicas

Mon, 01 Jan 0001 00:00:00 +0000

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.

Api-Reference: resources

Mon, 01 Jan 0001 00:00:00 +0000

Each entry in this list must be a path to a file, or a path (or URL) referring to another kustomization directory, e.g.

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.

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.

Api-Reference: secretGenerator

Mon, 01 Jan 0001 00:00:00 +0000

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.

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"

Api-Reference: vars

Mon, 01 Jan 0001 00:00:00 +0000

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:


containers:
  - image: myimage
    command: ["start", "--host", "$(MY_SERVICE_NAME)"]
    env:
    - name: SECRET_TOKEN
      value: $(SOME_SECRET_NAME)

To do so, add an entry to vars: as follows:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

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

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 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.