kustomize means one is running a
particular version of a program (a CLI), using a
particular version of underlying packages (a Go
API), and reading a particular version of a
If you’re having trouble with
go get, please read Go API Versioning and be patient.
CLI Program Versioning
kustomize version prints a three
field version tag (e.g.
v3.0.0) that aspires to
This notion of semver applies only to the CLI; the command names, their arguments and their flags.
The major version changes when some backward incompatibility appears in how the commands behave.
See the installation docs.
Go API Versioning
The public methods in the public packages
the kustomize Go API.
Version sigs.k8s.io/kustomize/v3 and earlier
kustomize/v3 (and preceding major versions), the
kustomize program and the API live the same Go
sigs.k8s.io/kustomize, at import path
This has been fine for the CLI, but it presents a problem for the Go API.
The process around Go modules, in particular the notion of minimal version selection, demands that the module respect semver.
Almost all the code in module
sigs.k8s.io/kustomize/v3 is exposed (not in a
internal). Even a minor
refactor changing a method name or argument type
in some deeply buried (but still public) method is
a backward incompatible change. As a result, Go
API semver hasn’t been followed. This was a mistake.
Some options are
continue to ignore Go API semver and stick to CLI semver (eliminating the usefullness of minimal version selection),
obey semver, and increment the module’s major version number with every release (drastically reducing the usefullness of minimal version selection - since virtually all releases will be major),
slow down change in the huge API in favor of stability, yet somehow continue to deliver features,
drastically reduce the API surface, stabilize on semver there, and refactor as needed inside
The last option seems the most appealing.
The first stable API version is coming
The first stable API version will launch as the Go module
The kustomize program itself (
and CLI specific code) will have moved out of
sigs.k8s.io/kustomize and into the new module
sigs.k8s.io/kustomize/kustomize. This is a
submodule in the same repo, and it will retain its
current notion of semver (e.g. a backward
incompatible change in command behavior will
trigger a major version bump). This module will
not export packages; it’s just home to a
sigs.k8s.io/kustomize/api module will
obey semver with a sustainable public
surface, informed by current usage. Clients
should import packages from this module, i.e.
from import paths prefixed by
sigs.k8s.io/kustomize/api/ at first,
and later by
The kustomize binary
itself is an API client requiring this module.
The clients and API will evolve independently.
Kustomization File Versioning
The kustomization file is a struct that is part of
the kustomize Go API (the
module), but it also evolves as a k8s API object -
it has an
apiVersion field containing its
own version number.
Field Change Policy
- A field’s meaning cannot be changed.
- A field may be deprecated, then removed.
- Deprecation means triggering a minor (semver) version bump in the kustomize Go API, and defining a migration path in a non-fatal error message.
- Removal means triggering a major (semver)
version bump in the kustomize Go API, and fatal
error if field encountered (as with any unknown
field). Likewise a change in
edit fix Command
kustomize command reads a Kustomization
file, converts deprecated fields to new
fields, and writes it out again in the latest
This is a type version upgrade mechanism that works within major API revisions. There is no downgrade capability, as there’s no use case for it (see discussion below).
With the 2.0.0 release, there were three field removals:
imageTagwas deprecated when
imageswas introduced, because the latter offers more general features for image data manipulation.
imageTagwas removed in v2.0.0.
patcheswas deprecated and replaced by
patchesJson6902was introduced, to make a clearer distinction between patch specification formats.
patcheswas removed in v2.0.0.
secretGenerator/commandswas removed due to security concerns in v2.0.0 with no deprecation period.
edit fix command in a v2.0.x binary
will no longer recognize these fields.
Relationship to the k8s API
Review of k8s API versioning
The presence of an
apiVersion field in a k8s
native type signals:
- its reliability level (alpha vs beta vs generally available),
- the existence of code to provide default values to fields not present in a serialization,
- the existence of code to provide both forward and backward conversion between different versions of types.
The k8s API promises a lossless conversion between versions over a specific range. This means that a recent client can write an object bearing the newest possible value for its version, the server will accept it and store it in “versionless” JSON form in storage, and can convert it to a range of older versions should an older client request data.
For native k8s types, this all requires writing Go code in the kubernetes core repo, to provide defaulting and conversions.
For CRDs, there’s a proposal on how to manage versioning (e.g. a remote service can offer type defaulting and conversions).
- A k8s API server is able to go forward and backward in versioning, to work with older clients, over some range.
kustomize edit fixcommand only moves forward within a major API version.
At the time of writing, the YAML in a kustomization file does not represent a k8s API object, and the kustomize command and associated library is neither a server of, nor a client to, the k8s API.
Additional Kustomization file rules
In addition to the field change policy described above, kustomization files conform to the following rules.
Eschew classic k8s fields
Field names with dedicated meaning in k8s
status, etc.) aren’t used.
This is enforced via code review.
Default values for k8s
If either field is present, they both must be.
If present, the value of
kind must be:
If missing, the value of
apiVersion defaults to
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.