kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-13 10:00:56 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Add FAQ from kubectl.docs.kubernetes.io (#6052)

Browse Source 
* Add FAQ from kubectl.docs.kubernetes.io

* Add title to Contributing Features

* Set sidebar_menu_compact to true

* Add glossary, fix broken links

* Update site/content/en/contribute/features/eschewedfeatures.md

Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com>

* Update site/content/en/contribute/features/eschewedfeatures.md

Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com>

* Update site/content/en/contribute/features/eschewedfeatures.md

Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com>

---------

Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com>
This commit is contained in:
Aashish Nehete
2026-02-19 06:43:39 -08:00
committed by GitHub
parent b7ee1340a9
commit 78ce39820d
8 changed files with 986 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
site/content/en/contribute/features/_index.md
View File

@@ -7,4 +7,6 @@ description: >
How to contribute features
---
### Kustomize Enhancement Proposal
For feature proposals, please refer to [Kustomize Enhancement Proposal Processes](https://github.com/kubernetes-sigs/kustomize/tree/master/proposals) documentation

161
site/content/en/contribute/features/eschewedfeatures.md Normal file
View File

@@ -0,0 +1,161 @@
---
title: "Eschewed Features"
linkTitle: "Eschewed Features"
type: docs
weight: 99
description: >
List of non-goal 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 targeting 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 editing
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.
[DAM]: /docs/reference/glossary/#declarative-application-management
[Java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards
[JSON patches]: /docs/reference/glossary/#patchjson6902
[kustomization]: /docs/reference/glossary/#kustomization
[OTS workflow]: /docs/reference/glossary/#off-the-shelf-configuration
[SMP patches]: /docs/reference/glossary/#patchstrategicmerge
[parameterization pitfall discussion]: https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/declarative-application-management.md#parameterization-pitfalls
[unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml
[cue]: https://cuelang.org/

472
site/content/en/docs/Reference/glossary.md
View File

@@ -3,6 +3,474 @@ title: "Glossary"
linkTitle: "Glossary"
weight: 1
date: 2023-07-28
type: docs
description: >
Glossary defines terminology used to interact with Kustomize.
---
Terminology used to interact with Kustomize.
---
[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
[CRD]: #custom-resource-definition
[DAM]: #declarative-application-management
[Declarative Application Management]: https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/declarative-application-management.md
[JSON]: https://www.json.org/
[JSONPatch]: https://tools.ietf.org/html/rfc6902
[JSONMergePatch]: https://tools.ietf.org/html/rfc7386
[Resource]: #resource
[YAML]: https://www.yaml.org/
[application]: #application
[apply]: #apply
[apt]: https://en.wikipedia.org/wiki/APT_(Debian)
[base]: #base
[bases]: #base
[bespoke]: #bespoke-configuration
[gitops]: #gitops
[k8s]: #kubernetes
[kubernetes]: #kubernetes
[kustomize]: #kustomize
[kustomization]: #kustomization
[kustomizations]: #kustomization
[off-the-shelf]: #off-the-shelf-configuration
[overlay]: #overlay
[overlays]: #overlay
[patch]: #patch
[patches]: #patch
[patchJson6902]: #patchjson6902
[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/jsonpatch.md
[patchesJson6902]: #patchjson6902
[proposal]: https://github.com/kubernetes/community/pull/1629
[rebase]: https://git-scm.com/docs/git-rebase
[resource]: #resource
[resources]: #resource
[root]: #kustomization-root
[rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md
[target]: #target
[transformer]: #transformer
[variant]: #variant
[variants]: #variant
## application
An _application_ is a group of k8s resources related by
some common purpose, e.g. a load balancer in front of a
webserver backed by a database.
[Resource] labelling, naming and metadata schemes have
historically served to group resources together for
collective operations like _list_ and _remove_.
This [proposal] describes a new k8s resource called
_application_ to more formally describe this idea and
provide support for application-level operations and
dashboards.
[kustomize] configures k8s resources, and the proposed
application resource is just another resource.
## apply
The verb _apply_ in the context of k8s refers to a
kubectl command and an in-progress [API
endpoint](https://goo.gl/UbCRuf) for mutating a
cluster.
One _applies_ a statement of what one wants to a
cluster in the form of a complete resource list.
The cluster merges this with the previously applied
state and the actual state to arrive at a new desired
state, which the cluster's reconciliation loop attempts
to create. This is the foundation of level-based state
management in k8s.
## base
A _base_ is a [kustomization] referred to
by some other [kustomization].
Any kustomization, including an [overlay], can be a base to
another kustomization.
A base has no knowledge of the overlays that refer to it.
For simple [gitops] management, a base configuration
could be the _sole content of a git repository
dedicated to that purpose_. Same with [overlays].
Changes in a repo could generate a build, test and
deploy cycle.
## bespoke configuration
A _bespoke_ configuration is a [kustomization] and some
[resources] created and maintained internally by some
organization for their own purposes.
The workflow associated with a _bespoke_ config is
simpler than the workflow associated with an
[off-the-shelf] config, because there's no notion of
periodically capturing someone else's upgrades to the
[off-the-shelf] config.
## custom resource definition
One can extend the k8s API by making a
Custom Resource Definition ([CRD spec]).
This defines a custom [resource] (CD), an entirely
new resource that can be used alongside _native_
resources like ConfigMaps, Deployments, etc.
Kustomize can customize a CD, but to do so
kustomize must also be given the corresponding CRD
so that it can interpret the structure correctly.
## declarative application management
Kustomize aspires to support [Declarative Application Management],
a set of best practices around managing k8s clusters.
In brief, kustomize should
* Work with any configuration, be it bespoke,
off-the-shelf, stateless, stateful, etc.
* Support common customizations, and creation of
[variants] (e.g. _development_ vs.
_staging_ vs. _production_).
* Expose and teach native k8s APIs, rather than
hide them.
* Add no friction to version control integration to
support reviews and audit trails.
* Compose with other tools in a unix sense.
* Eschew crossing the line into templating, domain
specific languages, etc., frustrating the other
goals.
## generator
A generator makes resources that can be used as is,
or fed into a [transformer].
## gitops
Devops or CICD workflows that use a git repository as a
single source of truth and take action (e.g., build,
test or deploy) when that truth changes.
## kustomization
The term _kustomization_ refers to a
`kustomization.yaml` file, or more generally to a
directory (the [root]) containing the
`kustomization.yaml` file and all the relative file
paths that it immediately references (all the local
data that doesn't require a URL specification).
I.e. if someone gives you a _kustomization_ for use
with [kustomize], it could be in the form of
* one file called `kustomization.yaml`,
* a tarball (containing that YAML file plus what it references),
* a git archive (ditto),
* a URL to a git repo (ditto), etc.
A kustomization file contains fields
falling into four categories:
* _resources_ - what existing [resources] are to be customized.
Example fields: _resources_, _crds_.
* _generators_ - what _new_ resources should be created.
Example fields: _configMapGenerator_ (legacy),
_secretGenerator_ (legacy), _generators_ (v2.1).
* _transformers_ - what to _do_ to the aforementioned resources.
Example fields: _namePrefix_, _nameSuffix_, _images_,
_commonLabels_, _patchesJson6902_, etc. and the more
general _transformers_ (v2.1) field.
* _meta_ - fields which may influence all or some of
the above. Example fields: _vars_, _namespace_,
_apiVersion_, _kind_, etc.
## kustomization root
The directory that immediately contains a
`kustomization.yaml` file.
When a kustomization file is processed, it may or may
not be able to access files outside its root.
Data files like resource YAML files, or text files
containing _name=value_ pairs intended for a ConfigMap
or Secret, or files representing a patch to be used in
a patch transformation, must live _within or below_ the
root, and as such are specified via _relative
paths_ exclusively.
A special flag (in v2.1), `--load_restrictions none`,
is provided to relax this security feature, to, say,
allow a patch file to be shared by more than one
kustomization.
Other kustomizations (other directories containing a
`kustomization.yaml` file) may be referred to by URL, by
absolute path, or by relative path.
If kustomization __A__ depends on kustomization __B__, then
* __B__ may not _contain_ __A__.
* __B__ may not _depend on_ __A__, even transitively.
__A__ may contain __B__, but in this case it might be
simplest to have __A__ directly depend on __B__'s
resources and eliminate __B__'s kustomization.yaml file
(i.e. absorb __B__ into __A__).
Conventionally, __B__ is in a directory that's sibling
to __A__, or __B__ is off in a completely independent
git repository, referencable from any kustomization.
A common layout is
> ```
> ├── base
> │   ├── deployment.yaml
> │   ├── kustomization.yaml
> │   └── service.yaml
> └── overlays
> ├── dev
> │   ├── kustomization.yaml
> │   └── patch.yaml
> ├── prod
> │   ├── kustomization.yaml
> │   └── patch.yaml
> └── staging
> ├── kustomization.yaml
> └── patch.yaml
> ```
The three roots `dev`, `prod` and `staging`
(presumably) all refer to the `base` root. One would
have to inspect the `kustomization.yaml` files to be
sure.
## kubernetes
[Kubernetes](https://kubernetes.io) is an open-source
system for automating deployment, scaling, and
management of containerized applications.
It's often abbreviated as _k8s_.
## kubernetes-style object
[fields required]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
An object, expressed in a YAML or JSON file, with the
[fields required] by kubernetes. Basically just a
_kind_ field to identify the type, a _metadata/name_
field to identify the particular instance, and an
_apiVersion_ field to identify the version (if there's
more than one version).
## kustomize
_kustomize_ is a command line tool supporting
template-free, structured customization of declarative
configuration targeted to k8s-style objects.
_Targeted to k8s means_ that kustomize has some
understanding of API resources, k8s concepts like
names, labels, namespaces, etc. and the semantics of
resource patching.
kustomize is an implementation of [DAM].
## off-the-shelf configuration
An _off-the-shelf_ configuration is a kustomization and
resources intentionally published somewhere for others
to use.
E.g. one might create a github repository like this:
> ```
> github.com/username/someapp/
> kustomization.yaml
> deployment.yaml
> configmap.yaml
> README.md
> ```
Someone could then _fork_ this repo (on github) and
_clone_ their fork to their local disk for
customization.
This clone could act as a [base] for the user's
own [overlays] to do further customization.
## overlay
An _overlay_ is a kustomization that depends on
another kustomization.
The [kustomizations] an overlay refers to (via file
path, URI or other method) are called [bases].
An overlay is unusable without its bases.
An overlay may act as a base to another overlay.
Overlays make the most sense when there is _more than
one_, because they create different [variants] of a
common base - e.g. _development_, _QA_, _staging_ and
_production_ environment variants.
These variants use the same overall resources, and vary
in relatively simple ways, e.g. the number of replicas
in a deployment, the CPU to a particular pod, the data
source used in a ConfigMap, etc.
One configures a cluster like this:
> ```
> kustomize build someapp/overlays/staging |\
> kubectl apply -f -
>
> kustomize build someapp/overlays/production |\
> kubectl apply -f -
> ```
Usage of the base is implicit - the overlay's
kustomization points to the base.
See also [root].
## package
The word _package_ has no meaning in kustomize, as
kustomize is not to be confused with a package
management tool in the tradition of, say, [apt] or
[rpm].
## patch
General instructions to modify a resource.
There are two alternative techniques with similar
power but different notation - the
[strategic merge patch](#patchstrategicmerge)
and the [JSON patch](#patchjson6902).
## patchStrategicMerge
A _patchStrategicMerge_ is [strategic-merge]-style patch (SMP).
An SMP looks like an incomplete YAML specification of
a k8s resource. The SMP includes `TypeMeta`
fields to establish the group/version/kind/name of the
[resource] to patch, then just enough remaining fields
to step into a nested structure to specify a new field
value, e.g. an image tag.
By default, an SMP _replaces_ values. This is
usually desired when the target value is a simple
string, but may not be desired when the target
value is a list.
To change this
default behavior, add a _directive_. Recognized
directives in YAML patches are _replace_ (the default)
and _delete_ (see [these notes][strategic-merge]).
Note that for custom resources, SMPs are treated as
[json merge patches][JSONMergePatch].
Fun fact - any resource file can be used as
an SMP, overwriting matching fields in another
resource with the same group/version/kind/name,
but leaving all other fields as they were.
TODO(monopole): add ptr to example.
## patchJson6902
A _patchJson6902_ refers to a kubernetes [resource] and
a [JSONPatch] specifying how to change the resource.
A _patchJson6902_ can do almost everything a
_patchStrategicMerge_ can do, but with a briefer
syntax. See this [example][patchExampleJson6902].
## plugin
A chunk of code used by kustomize, but not necessarily
compiled into kustomize, to generate and/or transform a
kubernetes resource as part of a kustomization.
Details [here](/docs/extending_kustomize).
## resource
A _resource_ in the context of a REST-ful API is the
target object of an HTTP operation like _GET_, _PUT_ or
_POST_. k8s offers a REST-ful API surface to interact
with clients.
A _resource_, in the context of a kustomization, is a
[root] relative path to a [YAML] or [JSON] file
describing a k8s API object, like a Deployment or a
ConfigMap, or it's a path to a kustomization, or a URL
that resolves to a kustomization.
More generally, a resource can be any correct YAML file
that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)
with a _kind_ and a _metadata/name_ field.
## root
See [kustomization root][root].
## sub-target / sub-application / sub-package
A _sub-whatever_ is not a thing. There are only
[bases] and [overlays].
## target
The _target_ is the argument to `kustomize build`, e.g.:
> ```
> kustomize build $target
> ```
`$target` must be a path or a url to a [kustomization].
The target contains, or refers to, all the information
needed to create customized resources to send to the
[apply] operation.
A target can be a [base] or an [overlay].
## transformer
A transformer can modify a resource, or merely
visit it and collect information about it in the
course of a `kustomize build`.
## variant
A _variant_ is the outcome, in a cluster, of applying
an [overlay] to a [base].
E.g., a _staging_ and _production_ overlay both modify
some common base to create distinct variants.
The _staging_ variant is the set of resources exposed
to quality assurance testing, or to some external users
who'd like to see what the next version of production
will look like.
The _production_ variant is the set of resources
exposed to production traffic, and thus may employ
deployments with a large number of replicas and higher
cpu and memory requests.

272
site/content/en/docs/Reference/versioningPolicy.md Normal file
View File

@@ -0,0 +1,272 @@
---
title: "Versioning Policy"
linkTitle: "Versioning Policy"
weight: 99
type: docs
description: >
CLI and API Versioning
---
Running `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
[kustomization] file.
> If you're having trouble with `go get`, please
> read [Go API Versioning](#go-api-versioning)
> and be patient.
## CLI Program Versioning
The command `kustomize version` prints a three
field version tag (e.g. `v3.0.0`) that aspires to
[semantic versioning].
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.
### Installation
See the [installation docs].
## Go API Versioning
The public methods in the public packages
of module `sigs.k8s.io/kustomize/api` constitute
the _kustomize Go API_.
#### Version sigs.k8s.io/kustomize/v3 and earlier
[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
In `kustomize/v3` (and preceding major versions), the
kustomize program and the API live the same Go
module at `sigs.k8s.io/kustomize`, at [import path]
`sigs.k8s.io/kustomize/v3`.
This has been fine for the CLI, but it presents a
problem for the Go API.
[minimal version selection]: https://research.swtch.com/vgo-mvs
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
directory named `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
`internal`.
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
```
sigs.k8s.io/kustomize/api
```
The _kustomize_ program itself (`main.go`
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 `main`
package.
The `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 `sigs.k8s.io/kustomize/api/v2/`.
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 `sigs.k8s.io/kustomize`
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 `apiVersion`.
### The `edit fix` Command
This `kustomize` command reads a Kustomization
file, converts deprecated fields to new
fields, and writes it out again in the latest
format.
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).
### Examples
With the 2.0.0 release, there were three field
removals:
- `imageTag` was deprecated when `images` was
introduced, because the latter offers more
general features for image data manipulation.
`imageTag` was removed in v2.0.0.
- `patches` was deprecated and replaced by
`patchesStrategicMerge` when `patchesJson6902`
was introduced, to make a clearer
distinction between patch specification formats.
`patches` was removed in v2.0.0.
- `secretGenerator/commands` was removed
due to security concerns in v2.0.0
with no deprecation period.
The `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 k8s API has specific [conventions] and a
process for making [changes].
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.
[CRDs versioning] gives an overview on
how to manage versioning in CustomResourceDefinitions.
### Differences
- A k8s API server is able to go _forward_ and
_backward_ in versioning, to work with older
clients, over [some range].
- The `kustomize edit fix` command 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
(`metadata`, `spec`, `status`, etc.) aren't used.
This is enforced via code review.
#### Default values for k8s `kind` and `apiVersion`
In `v3` or below, the two [special] k8s
resource fields [`kind`] and [`apiVersion`] may
be omitted from the kustomization file.
If either field is present, they both must be.
If present, the value of `kind` must be:
> ```
> kind: Kustomization
> ```
If missing, the value of `apiVersion` defaults to
> ```
> apiVersion: kustomize.config.k8s.io/v1beta1
> ```
[field change policy]: #field-change-policy
[some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy
[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md
[CRDs versioning]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#overview
[beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions
[changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md
[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources
[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
[release page]: https://github.com/kubernetes-sigs/kustomize/releases
[release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md
[kustomization]: /docs/reference/glossary#kustomization
[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds
[`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning
[semantic versioning]: https://semver.org
[installation docs]: /docs/getting-started/installation/

83
site/content/en/faq/_index.md
View File

@@ -2,11 +2,88 @@
title: "FAQ"
linkTitle: "FAQ"
type: docs
description:
"Frequently asked questions on Kustomize"
menu:
main:
weight: 70
---
<!---
TODO: add general FAQ info
-->
## kubectl doesn't have the latest kustomize, when will it be updated?
TLDR: This is blocked on either moving kubectl into its own repo, or changing its dependencies. ETA k8s ~1.20.
The adoption of go modules in the kubernetes/kubernetes repo broke the update process for kustomize.
This is due to the kustomize libraries depending on the kubernetes apimachinery libraries, which are
published out of the kubernetes staging directory.
2 pieces of work are underway which will allow kustomize to be updated in kubectl:
- migrating kubectl out of kubernetes/kubernetes (expected Kubernetes ~1.20)
- migrating kustomize off of the apimachinery libraries (expected Kubernetes ~1.20)
- [2506](https://github.com/kubernetes-sigs/kustomize/issues/2506)
Once either of these issues is resolved we will then update kubectl with the latest kustomize version.
## security: file 'foo' is not in or below 'bar'
v2.0 added a security check that prevents
kustomizations from reading files outside their own
directory root.
This was meant to help protect the person inclined to
download kustomization directories from the web and use
them without inspection to control their production
cluster
(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693),
[#700](https://github.com/kubernetes-sigs/kustomize/pull/700),
[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and
[#998](https://github.com/kubernetes-sigs/kustomize/pull/998))
Resources (including configmap and secret generators)
can _still be shared_ via the recommended best practice
of placing them in a directory with their own
kustomization file, and referring to this directory as a
[`base`](/docs/reference/glossary/#base) from any kustomization that
wants to use it. This encourages modularity and
relocatability.
To disable this in v3, use the `load_restrictor` flag:
```bash
kustomize build --load_restrictor none $target
```
To disable this in v4+, use the `load-restrictor` flag:
```bash
kustomize build --load-restrictor LoadRestrictionsNone $target
```
## Some field is not transformed by kustomize
Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc.
The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configurations:
- kustomizeconfig.yaml
```
The configuration directive allows customization of the following transformers:
```yaml
commonAnnotations: []
commonLabels: []
nameprefix: []
namespace: []
varreference: []
namereference: []
images: []
replicas: []
```
To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc.

12
site/content/en/faq/eschewedfeatures.md
View File

@@ -1,12 +0,0 @@
---
title: "Eschewed Features"
linkTitle: "Eschewed Features"
type: docs
weight: 99
description: >
Eschewed Features
---
<!---
TODO
-->

9
site/content/en/faq/versioningPolicy.md
View File

@@ -1,9 +0,0 @@
---
title: "Versioning Policy"
linkTitle: "Versioning Policy"
weight: 99
type: docs
---
<!---
TODO
-->

2
site/hugo.toml
View File

@@ -159,7 +159,7 @@ navbar_logo = false
# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
navbar_translucent_over_cover_disable = false
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = false
sidebar_menu_compact = true
# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
sidebar_search_disable = false