mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-07-01 10:20:35 +00:00
0b555e1b2c
Modify all `build` tests to use the raw, non-sorted output of build. This makes every test provide coverage for how kustomize re-orders (or doesn't reorder) resources during processing. Going forward, the ordering of resources in _expected_ output should match the depth-first ordering specified in the `resources:` field used in the test's kustomization file. The only exception to this rule would be tests that actually confirmed some other output ordering, e.g. the test of the `LegacyOrderTransformer` plugin. Fixes #756 Related #821
228 lines
6.9 KiB
Markdown
228 lines
6.9 KiB
Markdown
# 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
|
|
[imgSorted]: images/sorted.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).
|
|
|
|
## Resource ordering
|
|
|
|
![sort order retained][imgSorted]
|
|
|
|
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
|
|
|
|
![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 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](../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.
|
|
|
|
## Inventory generation for pruning
|
|
|
|
![pruning dead branches][imgPruning]
|
|
|
|
_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](#resource-ordering).
|
|
|
|
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).
|