Kustomization File Fields

An explanation of the fields in a kustomization.yaml file.

Resources

What existing things should be customized.

Field	Type	Explanation
resources	list	completely specified k8s API objects, e.g. deployment.yaml, configmap.yaml, etc
bases	list	paths or github URLs specifying directories containing a kustomization. These bases may be subjected to more customization, or merely included in the output.
CRDs	list	custom resource definition files, to allow specification of the custom resources in the resources list.

Generators

What things should be created (and optionally subsequently customized)?

Field	Type	Explanation
configMapGenerator	list	Each entry in this list results in the creation of one ConfigMap resource (it's a generator of n maps).
secretGenerator	list	Each entry in this list results in the creation of one Secret resource (it's a generator of n secrets)
generatorOptions	string	generatorOptions modify behavior of all ConfigMap and Secret generators
generators	list	plugin configuration files

Transformers

What transformations (customizations) should be applied?

Field	Type	Explanation
commonLabels	string	Adds labels and some corresponding label selectors to all resources.
commonAnnotations	string	Adds annotions (non-identifying metadata) to add all resources.
images	list	Images modify the name, tags and/or digest for images without creating patches.
inventory	struct	Specify an object who's annotations will contain a build result summary.
namespace	string	Adds namespace to all resources
namePrefix	string	Prepends value to the names of all resources
nameSuffix	string	The value is appended to the names of all resources.
replicas	list	Replicas modifies the number of replicas of a resource.
patchesStrategicMerge	list	Each entry in this list should resolve to a partial or complete resource definition file.
patchesJson6902	list	Each entry in this list should resolve to a kubernetes object and a JSON patch that will be applied to the object.
transformers	list	plugin configuration files

Meta

Field	Type	Explanation
vars	string	Vars capture text from one resource's field and insert that text elsewhere.
apiVersion	string	k8s metadata field.
kind	string	k8s metadata field.

apiVersion

If missing, this field's value defaults to

apiVersion: kustomize.config.k8s.io/v1beta1

bases

Each entry in this list should resolve to a directory containing a kustomization file, else the customization fails.

The entry could be a relative path pointing to a local directory or a url pointing to a directory in a remote repo. The url should follow hashicorp/go-getter URL format https://github.com/hashicorp/go-getter#url-format

The presence of this field means this file (the file you a reading) is an overlay that further customizes information coming from these bases.

Typical use case: a dev, staging and production environment that are mostly identical but differing crucial ways (image tags, a few server arguments, etc. that differ from the common base).

bases:
- ../../base
- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
- github.com/kubernets-sigs/kustomize//examples/helloWorld?ref=test-branch

commonLabels

Adds labels to all resources and selectors

commonLabels:
  someName: someValue
  owner: alice
  app: bingo

commonAnnotations

Adds annotions (non-identifying metadata) to add all resources. Like labels, these are key value pairs.

commonAnnotations:
  oncallPager: 800-555-1212

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: myJavaServerProps
  files:
  - application.properties
  - more.properties
- name: myJavaServerEnvVars
  literals:	
  - JAVA_HOME=/opt/java/jdk
  - JAVA_TOOL_OPTIONS=-agentlib:hprof

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


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

generatorOptions

Modifies behavior of all ConfigMap and Secret generators.

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

generators

A list of generator plugin configuration files.

generators:
- mySecretGeneratorPlugin.yaml
- myAppGeneratorPlugin.yaml

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

inventory

See inventory object.

kind

If missing, this field's value defaults to

kind: Kustomization

namespace

Adds namespace to all resources

namespace: my-namespace

namePrefix

Prepends value to the names of all resources Ex. a deployment named wordpress would become alices-wordpress

namePrefix: alices-

nameSuffix

The value is appended to the names of all resources. Ex. A deployment named wordpress would become wordpress-v2.

The suffix is appended before content has if resource type is ConfigMap or Secret.

nameSuffix: -v2

patchesStrategicMerge

Each entry in this list should be a relative path resolving to a partial or complete resource definition file.

The names in these (possibly partial) resource files must match names already loaded via the resources field or via resources loaded transitively via the bases entries. 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

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

replicas

Replicas modified the number of replicas for a resource.

E.g. Given this kubernetes Deployment fragment:

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.

resources

Each entry in this list must resolve to an existing resource definition in YAML. These are the resource files that kustomize reads, modifies and emits as a YAML string, with resources separated by document markers ("---").

resource:
- some-service.yaml
- sub-dir/some-deployment.yaml

secretGenerator

Each entry in this 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 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

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:

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:

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 https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fields.md

fields.md

Kustomization File Fields

Resources

Generators

Transformers

Meta

apiVersion

bases

commonLabels

commonAnnotations

configMapGenerator

crds

generatorOptions

generators

images

inventory

kind

namespace

namePrefix

nameSuffix

patchesStrategicMerge

patchesJson6902

replicas

resources

secretGenerator

vars

Files

fields.md

Latest commit

History

fields.md

File metadata and controls

Kustomization File Fields

Resources

Generators

Transformers

Meta

apiVersion

bases

commonLabels

commonAnnotations

configMapGenerator

crds

generatorOptions

generators

images

inventory

kind

namespace

namePrefix

nameSuffix

patchesStrategicMerge

patchesJson6902

replicas

resources

secretGenerator

vars