A Brief Introduction to Customize

Note. transl.: Written by Scott Lowe, a longtime IT engineer who has authored/co-authored seven printed books (mostly on VMware vSphere). He now works at its VMware subsidiary Heptio (acquired in 2016), specializing in cloud computing and Kubernetes. The text itself serves as a concise and easy-to-understand introduction to configuration management for Kubernetes using technology. Customize, recently included in the K8s.

Kustomize is a tool that allows users to "customize simple and template-free YAML files for various purposes while leaving the original YAML intact and usable" (description borrowed directly from kustomize repository on GitHub). Kustomize can be run directly or, starting with Kubernetes 1.14, use kubectl -k to access its features (although as of Kubernetes 1.15 the standalone binary is newer than the features built into kubectl). (Note. transl.: And with the recent release Kubernetes 1.16 customize supported by also in the kubeadm utility.) In this post, I want to introduce readers to the basics of kustomize.

In its simplest form/usage, kustomize is simply a collection of resources (YAML files that define Kubernetes objects: Deployments, Services, etc.) plus a list of instructions for the changes to be made to those resources. Just as make uses the set of instructions contained in Makefile, and Docker builds the container based on instructions from Dockerfile, customize uses kustomization.yaml to store prescriptions for what changes the user wants to make to the resource set.

Here is an example file kustomization.yaml:

resources:
- deployment.yaml
- service.yaml
namePrefix: dev-
namespace: development
commonLabels:
  environment: development

I will not try to tell you about all the possible fields in the file kustomization.yaml (This is well written. here), but I will give a brief explanation of a specific example:

• Field resources specifies what (what resources) kustomize will change. In this case, it will look for resources in files deployment.yaml и service.yaml in your directory (if necessary, you can specify full or relative paths).
• Field namePrefix instructs kustomize to add a specific prefix (in this case, dev-) to attribute name all resources defined in the field resources. Thus, if Deployment has name with the value of nginx-deployment, customize will make of it dev-nginx-deployment.
• Field namespace tells kustomize to add the given namespace to all resources. In this case, Deployment and Service will fall into the namespace development.
• Finally, the field commonLabels contains a set of labels that will be added to all resources. In our example, kustomize will label the resources with the name environment and the value development.

If the user does kustomize build . in the file directory kustomization.yaml and the necessary resources (i.e. files deployment.yaml и service.yaml), then at the output it will receive the text with the changes specified in kustomization.yaml.

Note. transl.: Illustration from the project documentation on the "simple" use of kustomize

Output can be redirected if changes need to be committed:

kustomize build . > custom-config.yaml

The output is deterministic (the same input will produce the same output), so you don't have to save the result to a file. Instead, it can be passed directly to another command:

kustomize build . | kubectl apply -f -

The kustomize functions can also be accessed via kubectl -k (since version 1.14 Kubernetes). However, keep in mind that the standalone kustomize package updates faster than the one integrated into kubectl (at least this is the case with the Kubernetes 1.15 release).

Readers may ask: "Why all this complexity, if you can edit the files directly?". Great question. In our example, indeed can modify files deployment.yaml и service.yaml directly, but what if they are a fork of someone else's project? Modifying the files directly makes it difficult (if not impossible) to rebase the fork when changes are made to the origin/origin. Using kustomize allows you to centralize these changes in a file kustomization.yaml, leaving the original files intact and thus making it easy to rebase the original files if necessary.

The benefits of customize become apparent in more complex use cases. In the example above kustomization.yaml and resources are in the same directory. However, kustomize supports use cases where there is a base configuration and many variations of it, also known as overlays. For example, a user wanted to take the nginx Deployment and Service that 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 (base resources), suppose the directories have the following structure:

- base
  - deployment.yaml
  - service.yaml
  - kustomization.yaml
- overlays
  - dev
    - kustomization.yaml
  - staging
    - kustomization.yaml
  - prod
    - kustomization.yaml

In file base/kustomization.yaml users using the field resources simply declare the resources that kustomize should include.

In each of the files overlays/{dev,staging,prod}/kustomization.yaml users refer to the base configuration in the field resourcesand then specify specific changes for given environment. For example file overlays/dev/kustomization.yaml might look like the example given earlier:

resources:
- ../../base
namePrefix: dev-
namespace: development
commonLabels:
  environment: development

At the same time, the file overlays/prod/kustomization.yaml could be quite different:

resources:
- ../../base
namePrefix: prod-
namespace: production
commonLabels:
  environment: production
  sre-team: blue

When the user starts kustomize build . in the catalog overlays/dev, customize will generate a development. If you run kustomize build . in the catalog overlays/prod - you get the production option. And all this - without making any changes to the original (basic) files, all in a declarative and deterministic way. You can commit the base configuration and overlay directories directly to the version control system, knowing that based on these files, you can reproduce the desired configuration at any time.

Note. transl.: Illustration from the project documentation on using overlays in kustomize

Customize can much more than what is covered 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 Customize;
• Kustomize - The right way to do templating in Kubernetes;
• Declarative Management of Kubernetes Objects Using Customize;
• Customizing Upstream Helm Charts with Customize.

Note. transl.: You can also advise the block of links published as Resources on the utility website, followed by a collection of videos with the latest talks about kustomize.

If you have questions or suggestions for improving this material, I'm always open to feedback. You can contact me at Twitter or Kubernetes Slack Channel. Have fun customizing your manifests with kustomize!

PS from translator

Read also on our blog:

• «Tools for developers of applications that run on Kubernetes";
• «Kubernetes 1.14: Highlights of what's new";
• «Five main outcomes of Helm Summit 2019 in Amsterdam";
• «Hands-On with the Kubernetes Package Manager - Helm».

Source: habr.com