# Kustomization File Fields An explanation of the fields in a [kustomization.yaml](glossary.md#kustomization) file. ## Resources What existing things should be customized. | Field | Type | Explanation | |---|---|---| |[resources](#resources) | list |completely specified k8s API objects, e.g. deployment.yaml, configmap.yaml, etc| |[bases](#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](#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](#configmapgenerator)| list |Each entry in this list results in the creation of one ConfigMap resource (it's a generator of n maps).| |[secretGenerator](#secretgenerator)| list |Each entry in this list results in the creation of one Secret resource (it's a generator of n secrets)| |[generatorOptions](#generatoroptions)|string|generatorOptions modify behavior of all ConfigMap and Secret generators| |[generators](#generators)|list|[plugin](plugins.md) configuration files| ## Transformers What transformations (customizations) should be applied? | Field | Type | Explanation | |---|---|---| | [commonLabels](#commonlabels) | string | Adds labels and some corresponding label selectors to all resources. | | [commonAnnotations](#commonannotations) | string | Adds annotions (non-identifying metadata) to add all resources. | | [images](#images) | list | Images modify the name, tags and/or digest for images without creating patches. | | [inventory](#inventory) | struct | Specify an object who's annotations will contain a build result summary. | | [namespace](#namespace) | string | Adds namespace to all resources | | [namePrefix](#nameprefix) | string | Prepends value to the names of all resources | | [nameSuffix](#namesuffix) | string | The value is appended to the names of all resources. | | [replicas](#replicas) | list | Replicas modifies the number of replicas of a resource. | |[patchesStrategicMerge](#patchesstrategicmerge)| list |Each entry in this list should resolve to a partial or complete resource definition file.| |[patchesJson6902](#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](#transformers)|list|[plugin](plugins.md) configuration files| ## Meta [k8s metadata]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields |Field|Type|Explanation| |---|---|---| | [vars](#vars) | string | Vars capture text from one resource's field and insert that text elsewhere. | | [apiVersion](#apiversion) | string | [k8s metadata] field. | | [kind](#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](#configmapgenerator) and [Secret](#secretgenerator) 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](plugins.md) 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](inventory_object.md). ### 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.