kustomize/docs/v_2.1.0.md

kustomize 2.1.0

Summary: Go modules, inventory, plugins, eased loading restrictions, and about ~80 issues closed since v2.0.3 (over 300 commits).

Go modules

Kustomize now defines its dependencies in a top level go.mod file. This is the first step towards a package structure intentially exported as one or more Go modules for use in other programs (kubectl, kubebuilder, etc.) and in kustomize plugins (see below).

Resource ordering

Kustomize now retains the depth-first order of resources as read.

The build command now accepts a --reorder flag with values legacy and none, with a default value of legacy.

legacy means apply an ordering based on GVK, that currently emits Namespace objects first, and ValidatingWebhookConfiguration objects last.

none means do not reorder the resources before output. This means kustomize respects the input order of the data, giving the user a means to control output order. Generated resources always come last.

Generator and transformer plugins

Since the beginning (as kinflate back in Sep 2017), kustomize has read or generated resources, applied a series of pipelined transformation to them, and emitted the result to stdout.

At that time, the only way to change the behavior of a generator (e.g. a secret generator), or change the behavior of a transformer (e.g. a name changer, or json patcher), was to modify source code and put out a release.

v1.0.9 introduced generator options as a means to change the behavior of the only two generators available at the time - Secret and ConfigMap generators. It also introduced transformer configs as a way to fine tune the targets of transformations (e.g. to which fields selectors should be added). Most of the feature requests for kustomize revolve around changing the behavior of the builtin generators and transformers.

v2.1.0 adds an alpha plugin framework, that encourages users to write their own generators or transformers, declaring them as kubernetes objects just like everything else, and apply them as part of the kustomize build process.

To inform the API exposed to plugins, and to confirm that the plugin framework can offer plugin authors the same capabilities as builtin operations, all the builtin generators and tranformers have been converted to plugin form (with one exceptions awaiting Go module refinements). This means that adding, say, a secretGenerator or commonAnnotations directive to your kustomization will (in v2.1.0) trigger execution of code committed as a plugin.

For more information, see the kustomize plugin documentation.

Remove load restrictions

The following usage:

kustomize build --load_restrictions none $target

allows a kustomization.yaml file used in this build to refer to files outside its own directory (i.e. outside its root).

This is an opt-in to suppress a security feature that denies this precise behavior.

This feature should only be used to allow multiple overlays (e.g. prod, staging and dev) to share a patch file. To share resources, use a relative path or URL to a kustomization directory in the resources directive.

Inventory generation for pruning

Alpha

Users can add an inventory stanza to their kustomization file, to add a special inventory object to the build result.

This object applies to the cluster along with everything else in the build result and can be used by other clients to intelligently prune orphaned cluster resources.

For more information see the kustomize inventory object documentation.

Field changes / deprecations

• Generalized resources field.

  The resources field has been generalized; it now accepts what formerly could only be specified in the bases field.

  This change was made so that the resources, generators and transformers fields all accept the same argument format.

  Each field's argument is a string list, where each entry is either a resource (a relative path to a YAML file) or a kustomization (a relative path or URL pointing to a directory with a kustomization file). A kustomization directory used in this context is called a base.

  The bases field still works, but is deprecated. Deal with this by simply moving the arguments of the bases field to the resources field in the desired order, e.g.

  resources:
  - someResouceFile.yaml
  - someOtherResourceFile.yaml
  bases:
  - ../../someBaseDir
  

  could become

  resources:
  - someResouceFile.yaml
  - ../../someBaseDir
  - someOtherResourceFile.yaml
  

  The depth-first traversal order of items in the resources: field is respected by kustomize, allowing one to, say, process someBaseDir between the two resource files. See this discussion of the build --reorder flag.

  The base as a concept is as important as ever, it's just that two new fields (generators and tranformers) and one existing field (resources) now accept arguments that were once accepted only by bases.

  The fact that the generators and transformers field accept bases (i.e. kustomization directories) and the fact that generator and transformer configuration objects are normal k8s resources means that one can generate or transform a generator or a transformer (see TestTransformerTransformers).

• Consistent envs field for Secret and ConfigMap generators.

  An envs sub-field has been added to both configMapGenerator and secretGenerator, replacing the now deprecated (and singular) env field. The new field accepts lists, just like its sibling fields files and literals.

Optionally kustomize edit fix to edit your kustomization file (e.g. merge singular env field into a plural field).