eschewedFeatures.md

Eschewed Features

The maintainers established this list to place bounds on the kustomize feature set. The bounds can be changed with a consensus on the risks.

For a bigger picture about why kustomize does some things and not others, see the glossary entry for DAM.

Removal directives

kustomize supports configurations that can be reasoned about as compositions or mixins - concepts that are widely accepted as a best practice in various programming languages.

To this end, kustomize offers various addition directives. One may add labels, annotations, patches, resources, bases, etc. Corresponding removal directives are not offered.

Removal semantics would introduce many possibilities for inconsistency, and the need to add code to detect, report and reject it. It would also allow, and possibly encourage, unnecessarily complex configuration layouts.

When faced with a situation where removal is desirable, it's always possible to remove things from a base like labels and annotations, and/or split multi-resource manifests into individual resource files - then add things back as desired via the kustomization.

If the underlying base is outside of one's control, an OTS workflow is the recommended best practice. Fork the base, remove what you don't want and commit it to your private fork, then use kustomize on your fork. As often as desired, use git rebase to capture improvements from the upstream base.

Unstructured edits

Structured edits are changes controlled by knowledge of the k8s API, and YAML or JSON syntax.

Most edits performed by kustomize can be expressed as JSON patches or SMP patches. Those can be verbose, so common patches, like adding labels or annotatations, get dedicated transformer plugins - LabelTransformer, AnnotationsTransformer, etc. These accept relatively simple YAML configuration allowing easy targetting of any number of resources.

Another class of edits take data from one specific object's field and use it in another (e.g. a service object's name found and copied into a container's command line). These reflection-style edits are called replacements.

The above edits create valid output given valid input, and can provide syntactically and semantically informed error messages if inputs are invalid.

Unstructured edits, edits that don't limit themselves to a syntax or object structure, come in many forms. A common one in the configuration domain is the template or parameterization approach.

In this technique, the source material is sprinkled with strings of the form ${VAR}. A scanner replaces them with a value taken from a map using VAR as the map key. It's trivial to implement.

kustomize eschews parameterization, because

• The source yaml gets polluted with $VARs and can no longed be applied as is to the cluster (it must be processed).
• The source material is no longer structured, making it unusable with any YAML processor. It's no longer data, it's now logic that must be compiled.
• Errors in the output are disconnected from the edit that caused it.
• The input becomes unintelligible as the project scales in any number of dimensions (resource count, cluster count, environment count, etc.)

Kustomizations are meant to be sharable and stackable. Imagine tracing down a problem rooted in a clever set of stacked regexp replacements performed by various overlays on some remote base. We've used such systems, and never want to again.

Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet, etc.) provide varying degrees of unstructured editting and/or embedded languages, and can be used instead of, or in a pipe with, kustomize. If you want to go all-in on configuration as a language, consider cue.

kustomize is going to stick to YAML in / YAML out.

Build-time side effects from CLI args or env variables

kustomize supports the best practice of storing one's entire configuration in a version control system.

Changing kustomize build configuration output as a result of additional arguments or flags to build, or by consulting shell environment variable values in build code, would frustrate that goal.

kustomize insteads offers kustomization file edit commands. Like any shell command, they can accept environment variable arguments.

For example, to set the tag used on an image to match an environment variable, run

kustomize edit set image nginx:$MY_NGINX_VERSION

as part of some encapsulating work flow executed before kustomize build.

Globs in kustomization files

kustomize supports the best practice of storing one's entire configuration in a version control system.

Globbing the local file system for files not explicitly declared in the kustomization file at kustomize build time would violate that goal.

Allowing globbing in a kustomization file would also introduce the same problems as allowing globbing in java import declarations or BUILD/Makefile dependency rules.

kustomize will instead provide kustomization file editting commands that accept globbed arguments, expand them at edit time relative to the local file system, and store the resulting explicit names into the kustomization file.