kustomize/docs/v_2.1.0.md

# kustomize 2.1.0


[Go modules]: https://github.com/golang/go/wiki/Modules
[generator options]: ../examples/generatorOptions.md
[imgModules]: images/goModules.png
[imgPlugins]: images/plugins.png
[imgPruning]: images/pruning.png
[imgWheels]: images/abandonedTrainingWheels.png
[kustomization]: glossary.md#kustomization
[_kustomization_]: glossary.md#kustomization
[base]: glossary.md#base
[bases]: glossary.md#base
[_base_]: glossary.md#base
[kustomize inventory object documentation]: inventory_object.md
[kustomize plugin documentation]: plugins.md
[root]: glossary.md#kustomization-root
[transformer configs]: ../examples/transformerconfigs
[v1.0.9]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9
[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
[v2.1.0]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.1.0
[versioning policy]: versioningPolicy.md

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



## Go modules

![gopher with boxes][imgModules]

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).


## Inventory generation for pruning

![pruning dead branches][imgPruning]

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].


## Generator and transformer plugins

![kid putting knife in electrical outlet][imgPlugins]

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 a _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 a few 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](../plugin/builtin).

For more information, see the
[kustomize plugin documentation].

## Remove load restrictions

![removed training wheels][imgWheels]

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.


## Field changes / deprecations

* Generalized `resources` field.

  The `resources` field has been generalized, and
  can now accept 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 no longer
  necessary, and will likely be deprecated in the
  next release.  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]).

[TestTransformerTransformers]: ../pkg/target/transformerplugin_test.go

* 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).