A brief introduction to Kustomize
Note perev. : The article was written by Scott Lowe, a senior IT engineer who authored / co-authored seven printed books (primarily for VMware vSphere). He currently works at its VMware subsidiary, Heptio (acquired in 2016), specializing in cloud computing and Kubernetes. The text itself serves as a capacious and easy-to-understand introduction to configuration management for Kubernetes using Kustomize technology, recently included with K8s.
Kustomize is a tool that allows users to "customize simple and template-free YAML files for various purposes, leaving the original YAML intact and usable" (the description is borrowed directly from the kustomize repository on GitHub ). Kustomize can be run directly or, starting with Kubernetes 1.14, use
to access its functions (although as of Kubernetes 1.15, a separate binary is newer than the features built into kubectl). ( Note : And with the recent Kubernetes 1.16 release, kustomize is also supported in the kubeadm utility.) In this post, I want to introduce readers to the basics of kustomize.
In its simplest form / application, kustomize is simply a collection of resources (YAML files that define Kubernetes objects: Deployments, Services, etc.) plus a list of instructions on the changes that need to be made to these resources. Just as make uses the instruction set contained in the
, and Docker
container based on instructions from the
, kustomize uses
to store instructions about what changes the user wants to make to the resource set.
Here is an example
file:
I will not try to talk about all the possible fields in the
file (this is well written here ), but I will give a brief explanation of a specific example:
If the user runs
in the directory with the
file and the necessary resources (i.e.
and
files), then at the output it will receive the text with the changes prescribed in
.
Note perev. : Illustration from the project documentation for the “simple” use of kustomize
The output can be redirected if you need to commit the changes:
The output is deterministic (with the same input, the same output will be obtained), so you can not save the result to a file. Instead, you can immediately pass it to another command:
Access to kustomize functions can also be accessed through
(since version 1.14 of Kubernetes). However, keep in mind that a separate kustomize package is updated faster than integrated into kubectl (at least this is the case with the release of Kubernetes 1.15).
Readers may ask, “Why do we need all these difficulties if you can edit files directly?” Great question. In our example, it is really possible to modify the
and
files directly, but what if they are a fork of someone else's project? Direct file modification makes it difficult (if not impossible at all) to rebase fork when changes are made to the source / source. Using kustomize allows you to centralize these changes in the
file, leaving the original files intact and thus making it easier to rebase the source files if necessary.
The benefits of kustomize become apparent in more complex use cases. In the above example,
and resources are in the same directory. However, kustomize does support use cases when there is a basic configuration and many of its variants, also known as overlays . For example, the user wanted to take Deployment and Service for nginx, which I used as an example, and create development-, staging- and production-versions (or variants) of those files. To do this, he will need the overlays mentioned above and, in fact, the basic resources themselves.
To illustrate the idea of overlays and base resources , suppose directories have the following structure:
In the
users simply use the
field to declare the resources that kustomize should enable.
In each of the
users refer to the basic configuration in the
field and then indicate the specific changes for this environment . For example, the
might look like the example shown earlier:
At the same time, the
may be completely different:
When the user starts
in the
, kustomize will generate a development option. If you run
in the
directory - you get the production option. And all this - without making any changes to the original (base) files, and all this - in a declarative and deterministic way. You can commit the basic configuration and overlay directories directly to the version control system, knowing that on the basis of these files you can reproduce the desired configuration at any time.
Note perev. : Illustration from project documentation for using overlays in kustomize
Kustomize can do much more than is described in this article. However, I hope it will serve as a good introduction.
There are many good articles and publications about kustomize. Here are a few that I found particularly useful:
Note perev. : You can also advise a block of links published as Resources on the utility website, and a subsequent collection of videos with the latest reports about kustomize.
If you have questions or suggestions for improving this material, I am always open to feedback. You can contact me on Twitter or on the Kubernetes Slack channel . Have fun modifying your manifests with kustomize!
Read also in our blog:
Kustomize is a tool that allows users to "customize simple and template-free YAML files for various purposes, leaving the original YAML intact and usable" (the description is borrowed directly from the kustomize repository on GitHub ). Kustomize can be run directly or, starting with Kubernetes 1.14, use
kubectl -k
to access its functions (although as of Kubernetes 1.15, a separate binary is newer than the features built into kubectl). ( Note : And with the recent Kubernetes 1.16 release, kustomize is also supported in the kubeadm utility.) In this post, I want to introduce readers to the basics of kustomize.
In its simplest form / application, kustomize is simply a collection of resources (YAML files that define Kubernetes objects: Deployments, Services, etc.) plus a list of instructions on the changes that need to be made to these resources. Just as make uses the instruction set contained in the
Makefile
, and Docker
Dockerfile
container based on instructions from the
Dockerfile
, kustomize uses
kustomization.yaml
to store instructions about what changes the user wants to make to the resource set.
Here is an example
kustomization.yaml
file:
resources: - deployment.yaml - service.yaml namePrefix: dev- namespace: development commonLabels: environment: development
I will not try to talk about all the possible fields in the
kustomization.yaml
file (this is well written here ), but I will give a brief explanation of a specific example:
- The
resources
field indicates what (which resources) kustomize will change. In this case, it will look for resources in thedeployment.yaml
andservice.yaml
files in its directory (if necessary, full or relative paths can be specified). - The
namePrefix
field instructs kustomize to add a specific prefix (in this case,dev-
) to thename
attribute of all resources defined in theresources
field. Thus, if there is aname
in Deployment with a value ofnginx-deployment
, kustomize will makedev-nginx-deployment
. - The
namespace
field instructs kustomize to add the specified namespace to all resources. In this case, Deployment and Service will fall into thedevelopment
namespace. - Finally, the
commonLabels
field contains a set of labels that will be added to all resources. In our example, kustomize will assign a label to the resources with the nameenvironment
and the valuedevelopment
.
If the user runs
kustomize build .
in the directory with the
kustomization.yaml
file and the necessary resources (i.e.
deployment.yaml
and
service.yaml
files), then at the output it will receive the text with the changes prescribed in
kustomization.yaml
.
Note perev. : Illustration from the project documentation for the “simple” use of kustomize
The output can be redirected if you need to commit the changes:
kustomize build . > custom-config.yaml
The output is deterministic (with the same input, the same output will be obtained), so you can not save the result to a file. Instead, you can immediately pass it to another command:
kustomize build . | kubectl apply -f -
Access to kustomize functions can also be accessed through
kubectl -k
(since version 1.14 of Kubernetes). However, keep in mind that a separate kustomize package is updated faster than integrated into kubectl (at least this is the case with the release of Kubernetes 1.15).
Readers may ask, “Why do we need all these difficulties if you can edit files directly?” Great question. In our example, it is really possible to modify the
deployment.yaml
and
service.yaml
files directly, but what if they are a fork of someone else's project? Direct file modification makes it difficult (if not impossible at all) to rebase fork when changes are made to the source / source. Using kustomize allows you to centralize these changes in the
kustomization.yaml
file, leaving the original files intact and thus making it easier to rebase the source files if necessary.
The benefits of kustomize become apparent in more complex use cases. In the above example,
kustomization.yaml
and resources are in the same directory. However, kustomize does support use cases when there is a basic configuration and many of its variants, also known as overlays . For example, the user wanted to take Deployment and Service for nginx, which I used as an example, and create development-, staging- and production-versions (or variants) of those files. To do this, he will need the overlays mentioned above and, in fact, the basic resources themselves.
To illustrate the idea of overlays and base resources , suppose directories have the following structure:
- base - deployment.yaml - service.yaml - kustomization.yaml - overlays - dev - kustomization.yaml - staging - kustomization.yaml - prod - kustomization.yaml
In the
base/kustomization.yaml
users simply use the
resources
field to declare the resources that kustomize should enable.
In each of the
overlays/{dev,staging,prod}/kustomization.yaml
users refer to the basic configuration in the
resources
field and then indicate the specific changes for this environment . For example, the
overlays/dev/kustomization.yaml
might look like the example shown earlier:
resources: - ../../base namePrefix: dev- namespace: development commonLabels: environment: development
At the same time, the
overlays/prod/kustomization.yaml
may be completely different:
resources: - ../../base namePrefix: prod- namespace: production commonLabels: environment: production sre-team: blue
When the user starts
kustomize build .
in the
overlays/dev
, kustomize will generate a development option. If you run
kustomize build .
in the
overlays/prod
directory - you get the production option. And all this - without making any changes to the original (base) files, and all this - in a declarative and deterministic way. You can commit the basic configuration and overlay directories directly to the version control system, knowing that on the basis of these files you can reproduce the desired configuration at any time.
Note perev. : Illustration from project documentation for using overlays in kustomize
Kustomize can do much more than is described in this article. However, I hope it will serve as a good introduction.
Additional resources
There are many good articles and publications about kustomize. Here are a few that I found particularly useful:
- Change base YAML config for different environments prod / test using Kustomize ;
- Kustomize - The right way to do templating in Kubernetes ;
- Declarative Management of Kubernetes Objects Using Kustomize ;
- Customizing Upstream Helm Charts with Kustomize .
Note perev. : You can also advise a block of links published as Resources on the utility website, and a subsequent collection of videos with the latest reports about kustomize.
If you have questions or suggestions for improving this material, I am always open to feedback. You can contact me on Twitter or on the Kubernetes Slack channel . Have fun modifying your manifests with kustomize!
PS from the translator
Read also in our blog:
All Articles