Configure Kubernetes with Kustomize
The purpose of this document is to help you get started with Kustomize, understand its intended use cases, and find resources for using it with other Google Cloud tools.
Kustomize is a Kubernetes configuration transformation tool that enables you to customize untemplated YAML files, leaving the original files untouched. Kustomize can also generate resources such as ConfigMaps and Secrets from other representations. Kustomize is built for the Kubernetes API, so it can understand and modify Kubernetes-style objects.
Built by Google and the Kubernetes community, Kustomize aligns itself with the
Kubernetes principles of using
to define configuration files and managing these configurations
The Kustomize configuration object is called a
which describes how to generate or transform other Kubernetes objects. A
Kustomization is defined declaratively in a file named
which can be generated and edited by Kustomize itself.
In Kustomize, you can define a common, reusable kustomization (called a base), and patch it with multiple other kustomizations (called overlays), that can selectively overwrite the settings defined in the base in order to produce variants. Kustomize then transforms and generates resources, a process called hydration or rendering, according to the configuration defined in the kustomization bases and overlays. These rendered resources are then written to standard output or to files, leaving the original YAML files untouched, so that a base can be reused by many different overlays.
This template-free approach is powerful when it comes to ease of use and reusability of kustomization bases. It lets you customize your Kubernetes configuration in almost any way you want, without requiring you to provide a large set of values for each individual use case.
The benefits of managing Kubernetes configurations with Kustomize include the following:
Kustomize is template-free. When using templates and value files, almost every specification in a YAML file can become a parameter that needs a value, and the values files can become very large. Rather than templating configuration as text, or expressing configuration as code, Kustomize manipulates configuration data. The raw YAML is readable and reusable whether it is rendered by Kustomize or not. The Kustomize model is different; there is no need to parameterize everything, which makes it easier to reuse common configurations.
Kustomize can be run natively from the Kubernetes command line interface. Kustomize is built into
kubectl, from version 1.14. So, as long as you're using
kubectl, there's no need to install or manage Kustomize as a separate dependency.
Kustomize is purely declarative. Being a Kubernetes-native tool, Kustomize aligns with the Kubernetes approach to declarative configuration. Rather than imperatively describing step by step how the tool should customize your resources, you declare what you want, and Kustomize provides it.
Kustomize lets you reuse the same base configuration to manage multiple different configurations. You can use one base file across several different environments (for example, development, staging, production), and have minimal, unique overlays to customize the base for each environment.
Kustomize is easy to use. There is a shallow learning curve; you can get started with a very simple configuration and gradually build more complex features on top, one layer at a time.
Kustomize is extensible and customizable. Kustomize supports a plugin framework for you to write your own generators and transformers in the style of containerized and executable Kubernetes Resource Model (KRM) functions. To learn more about how to create your own plugins, you can read the official Kustomize Plugins Guide.
To install Kustomize in your local environment, run the following command:
gcloud components install kustomize
Kustomize support in Google Cloud
Config Sync automatically uses Kustomize to render the resources in a repository if it contains a kustomization file. You can learn more about this feature in Use a repo with Kustomize configurations and Helm charts.
Bases and overlays
Kustomize's configuration transformation approach leverages the use of kustomization layers so that the same base configuration files can be reused across multiple kustomization configurations. It achieves this with the concepts of bases and overlays.
- A base is a directory containing a file called
kustomization.yaml, which can enumerate some set of resources with some customizations that will be applied to them. A base should be declared in the
resourcesfield of a kustomization file.
- An overlay is a directory that refers to another kustomization directory as its, or one of its, bases.
A base can be thought of as a preliminary step in a pipeline, having no knowledge of the overlays that it is referenced by. After a base is finished processing, it sends its resources as input to the overlay to transform according to the overlay's specification.
The following is an example of a kustomization base:
# base/kustomization.yaml resources: - deployment.yaml namePrefix: bar-
#base/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx spec: template: metadata: spec: containers: - image: nginx name: nginx
This base could be reused by multiple kustomization overlays. The following is an example of an overlay that could refer to this base:
# overlay/kustomization.yaml resources: - ../base - configmap.yaml namePrefix: foo-
#overlay/configmap.yaml apiVersion: v1 kind: ConfigMap metadata: name: cm data: red: blue
Running the command
kustomize build overlay produces the following output:
apiVersion: apps/v1 kind: Deployment metadata: name: foo-bar-nginx spec: template: metadata: spec: containers: - image: nginx name: nginx --- apiVersion: v1 kind: ConfigMap metadata: name: foo-cm data: red: blue
The Deployment received the name prefix
bar-from the base
kustomization, and then another name prefix
foo- from the overlay
kustomization. The ConfigMap only received the name prefix
foo- because it was
declared in the overlay, and thus was processed only by the overlay.
Generate Secrets and ConfigMaps
You can generate Secrets and ConfigMaps from a file by using the
configMapGenerator fields in your kustomization file. For
# kustomization.yaml configMapGenerator: - name: my-app files: -.properties
generates the following YAML output:
apiVersion: v1 kind: ConfigMap metadata: name: my-app-g82klmn92h data: .properties: |- red=blue
Edit the kustomization file
Kustomize provides several imperative commands that help you manage your kustomization file.
To add all the YAML files in your current directory to the kustomization's
resourcesfield, run the following command:
kustomize edit add resource *.yaml
To view the kustomize edit help page and see all the subcommands it offers, run the following command:
kustomize edit -h
To get specific help for subcommands, add the subcommand as an argument. For example:
kustomize edit add -h
For more information about the fields supported in the
you can visit
the official kustomize docs,
which provide descriptions and examples of the various fields you can use.
For a list of features that are intentionally not supported by Kustomize, you can read about Kustomize's eschewed features.