Stay organized with collections Save and categorize content based on your preferences.

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.

About Kustomize

Built by Google and the Kubernetes community, Kustomize aligns itself with the Kubernetes principles of using Kubernetes objects to define configuration files and managing these configurations declaratively. The Kustomize configuration object is called a Kustomization, which describes how to generate or transform other Kubernetes objects. A Kustomization is defined declaratively in a file named kustomization.yaml, 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.

image

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.

Kustomize benefits

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.

Local installation

To install Kustomize in your local environment, run the following command:

gcloud components install kustomize

Kustomize support in Google Cloud

Kustomize is pre-installed in Cloud Shell and is supported in Skaffold. It is also supported as a builder for Cloud Build.

Starting in Anthos Config Management version 1.9.0, 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.

Understanding Kustomize

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 resources field 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 secretGenerator or configMapGenerator fields in your kustomization file. For example:

# 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 resources field, 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
    

What's next

Official documentation

For more information about the fields supported in the kustomization.yaml file, you can visit the official kustomize docs, which provide descriptions and examples of the various fields you can use.

Unsupported features

For a list of features that are intentionally not supported by Kustomize, you can read about Kustomize's eschewed features.