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

docs: setup API section with cli-experimental site

Browse Source
This commit is contained in:
Jeong Jinwoo
2023-09-04 23:17:02 +09:00
parent 56d37acc7d
commit e19ca5405a
25 changed files with 3413 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
site/content/en/docs/Reference/API/bases.md Normal file
View File

@@ -0,0 +1,24 @@
---
title: "bases"
linkTitle: "bases"
type: docs
weight: 1
description: >
Add resources from a kustomization dir.
---
{{% pageinfo color="warning" %}}
The `bases` field was deprecated in v2.1.0. This field will never be removed from the
kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included
in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available,
we will announce the deprecation of the v1beta1 version. There will be at least
two releases between deprecation and removal of Kustomization v1beta1 support from the
kustomize CLI, and removal itself will happen in a future major version bump.
You can run `kustomize edit fix` to automatically convert `bases` to `resources`.
{{% /pageinfo %}}
Move entries into the [resources](/references/kustomize/kustomization/resource)
field. This allows bases - which are still a
[central concept](/references/kustomize/glossary#base) - to be
ordered relative to other input resources.

316
site/content/en/docs/Reference/API/buildMetadata.md Normal file
View File

@@ -0,0 +1,316 @@
---
title: "buildMetadata"
linkTitle: "buildMetadata"
type: docs
weight: 2
description: >
Specify options for including information about the build in annotations or labels.
---
The `buildMetadata` field is a list of strings. The strings can be one of three builtin
options that add some metadata to each resource about how the resource was built.
These options are:
- `managedByLabel`
- `originAnnotations`
- `transformerAnnotations`
It is possible to set one or all of these options in the kustomization file:
```yaml
buildMetadata: [managedByLabel, originAnnotations, transformerAnnotations]
```
### Managed By Label
To mark the resource as having been managed by kustomize, you can specify the `managedByLabel`
option in the `buildMetadata` field of the kustomization:
```yaml
buildMetadata: [managedByLabel]
```
This will add the label `app.kubernetes.io/managed-by` to each resource with the version of kustomize
that has built it. For example, given the following input:
kustomization.yaml
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- service.yaml
buildMetadata: [managedByLabel]
```
service.yaml
```yaml
apiVersion: v1
kind: Service
metadata:
name: myService
spec:
ports:
- port: 7002
```
`kustomize build` will produce a resource with an output like the following:
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/managed-by: kustomize-v4.4.1
name: myService
spec:
ports:
- port: 7002
```
### Origin Annotation
To annotate resources with information about their origin, you can specify the `originAnnotations`:
```yaml
buildMetadata: [originAnnotations]
```
When this option is set, generated resources will receive an annotation with key `config.kubernetes.io/origin`,
containing data about the generator that produced it. If the resource is from the `resources` field, this annotation
contains data about the file it originated from.
The possible fields of these annotations are:
- `path`: The path to a resource file itself
- `ref`: If from a remote file or generator, the ref of the repo URL.
- `repo`: If from a remote file or generator, the repo source
- `configuredIn`: If a generated resource, the path to the generator config. If a generator is invoked via a field
in the kustomization file, this would point to the kustomization file itself.
- `configuredBy`: If a generated resource, the ObjectReference of the generator config.
All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon
which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths
in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the
remote repository. Any fields that are not applicable would be omitted from the final output.
Here is an example of what this would look like:
```yaml
config.kubernetes.io/origin: |
path: path.yaml
ref: v0.0.0
repo: http://github.com/examplerepo
configuredIn: path/to/generatorconfig
configuredBy:
kind: Generator
apiVersion: builtin
name: foo
namespace: default
```
#### Examples
##### Resource declared from `resources`
A kustomization such as the following:
```yaml
resources:
- deployment.yaml
buildMetadata: [originAnnotations]
```
would produce a resource with an annotation like the following:
```yaml
config.kubernetes.io/origin: |
path: deployment.yaml
```
##### Local custom generator
A kustomization such as the following:
```yaml
generators:
- generator.yaml
buildMetadata: [originAnnotations]
```
would produce a resource with an annotation like the following:
```yaml
config.kubernetes.io/origin: |
configuredIn: generator.yaml
configuredBy:
kind: MyGenerator
apiVersion: v1
name: generator
```
##### Remote builtin generator
We have a top-level kustomization such as the following:
```yaml
resources:
- github.com/examplerepo/?ref=v1.0.6
buildMetadata: [originAnnotations]
```
which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization
defined in `github.com/examplerepo/kustomization.yaml`:
```yaml
configMapGenerator:
- name: my-java-server-env-vars
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
```
Running `kustomize build` on the top-level kustomization would produce the following output:
```yaml
apiVersion: v1
data:
JAVA_HOME: /opt/java/jdk
JAVA_TOOL_OPTIONS: -agentlib:hprof
kind: ConfigMap
metadata:
name: my-java-server-env-vars-44k658k8gk
annotations:
config.kubernetes.io/origin: |
ref: v1.0.6
repo: github.com/examplerepo
configuredIn: kustomization.yaml
configuredBy:
kind: ConfigMapGenerator
apiVersion: builtin
```
### Transformer Annotations [Alpha]
To annotate resources with information about the transformers that have acted on them, you can add the
`transformerAnnotations` option to the `buildMetadata` field of the kustomization:
```yaml
buildMetadata: [transformerAnnotations]
```
When the `transformerAnnotations` option is set, kustomize will add annotations with information about what transformers
have acted on each resource. Transformers can be invoked either through various fields in the kustomization file
(e.g. the `replacements` field will invoke the ReplacementTransformer), or through the `transformers` field.
The annotation key for transformer annotations will be `config.kubernetes.io/transformations`, which will contain a list of
transformer data. The possible fields in each item in this list is identical to the possible fields in `config.kubernetes.io/origin`,
except that the transformer annotation does not have a `path` field:
The possible fields of these annotations are:
- `path`: The path to a resource file itself
- `ref`: If from a remote file or generator, the ref of the repo URL.
- `repo`: If from a remote file or generator, the repo source
- `configuredIn`: The path to the transformer config. If a transformer is invoked via a field
in the kustomization file, this would point to the kustomization file itself.
- `configuredBy`: The ObjectReference of the transformer config.
All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon
which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths
in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the
remote repository. Any fields that are not applicable would be omitted from the final output.
Here is an example of what this would look like:
```yaml
config.kubernetes.io/transformations: |
- ref: v0.0.0
repo: http://github.com/examplerepo
configuredIn: path/to/transformerconfig
configuredBy:
kind: Transformer
apiVersion: builtin
name: foo
namespace: default
```
While this field is in alpha, it will receive the `alpha` prefix, so you will see the annotation key
`alpha.config.kubernetes.io/transformations` instead. We are not guaranteeing that the annotation content will be stable during
alpha, and reserve the right to make changes as we evolve the feature.
#### Examples
#### Local custom transformer
A kustomization such as the following:
```yaml
transformers:
- transformer.yaml
buildMetadata: [transformerAnnotations]
```
would produce a resource with an annotation like the following:
```yaml
config.kubernetes.io/transformations: |
- configuredIn: transformer.yaml
configuredBy:
kind: MyTransformer
apiVersion: v1
name: transformer
```
##### Remote builtin transformer + local builtin transformer
We have a top-level kustomization such as the following:
```yaml
resources:
- github.com/examplerepo/?ref=v1.0.6
buildMetadata: [transformerAnnotations]
namespace: my-ns
```
which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization
defined in `github.com/examplerepo/kustomization.yaml`:
```yaml
resources:
- deployment.yaml
namePrefix: pre-
```
`deployment.yaml` contains the following:
```yaml
apiVersion: v1
kind: Deployment
metadata:
name: deploy
```
Running `kustomize build` on the top-level kustomization would produce the following output:
```yaml
apiVersion: v1
kind: Deployment
metadata:
name: pre-deploy
annotations:
config.kubernetes.io/transformations: |
- ref: v1.0.6
repo: github.com/examplerepo
configuredIn: kustomization.yaml
configuredBy:
kind: PrefixSuffixTransformer
apiVersion: builtin
- configuredIn: kustomization.yaml
configuredBy:
kind: NamespaceTransformer
apiVersion: builtin
```

58
site/content/en/docs/Reference/API/commonAnnotations.md Normal file
View File

@@ -0,0 +1,58 @@
---
title: "commonAnnotations"
linkTitle: "commonAnnotations"
type: docs
weight: 3
description: >
Add annotations to add all resources.
---
Add annotations to all resources. If the annotation key already is present on the resource,
the value will be overridden.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonAnnotations:
oncallPager: 800-555-1212
```
## Example
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonAnnotations:
oncallPager: 800-555-1212
resources:
- deploy.yaml
```
```yaml
# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
spec:
...
```
### Build Output
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
annotations:
oncallPager: 800-555-1212
spec:
...
```

107
site/content/en/docs/Reference/API/commonLabels.md Normal file
View File

@@ -0,0 +1,107 @@
---
title: "commonLabels"
linkTitle: "commonLabels"
type: docs
weight: 4
description: >
Add labels and selectors to add all resources.
---
[labels]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/labels/
Add labels and selectors to all resources. If the label key already is present on the resource,
the value will be overridden.
An alternative to this field is the [labels] field, which allows adding labels without also automatically
injecting corresponding selectors.
{{% pageinfo color="warning" %}}
Selectors for resources such as Deployments and Services shouldn't be changed once the
resource has been applied to a cluster.
Changing commonLabels to live resources could result in failures.
{{% /pageinfo %}}
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonLabels:
someName: someValue
owner: alice
app: bingo
```
## Example
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonLabels:
someName: someValue
owner: alice
app: bingo
resources:
- deploy.yaml
- service.yaml
```
```yaml
# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
```
```yaml
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: example
```
### Build Output
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
spec:
selector:
app: bingo
owner: alice
someName: someValue
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
spec:
selector:
matchLabels:
app: bingo
owner: alice
someName: someValue
template:
metadata:
labels:
app: bingo
owner: alice
someName: someValue
```

11
site/content/en/docs/Reference/API/components.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: "components"
linkTitle: "components"
type: docs
weight: 5
description: >
Compose kustomizations.
---
Please check out the existing [components guide](/guides/config_management/components/) for explanation with examples.
More examples are in progress

359
site/content/en/docs/Reference/API/configMapGenerator.md Normal file
View File

@@ -0,0 +1,359 @@
---
title: "configMapGenerator"
linkTitle: "configMapGenerator"
type: docs
weight: 6
description: >
Generate ConfigMap resources.
---
Each entry in this list results in the creation of
one ConfigMap resource (it's a generator of n maps).
The example below creates four ConfigMaps:
- first, with the names and contents of the given files
- second, with key/value as data using key/value pairs from files
- third, also with key/value as data, directly specified using `literals`
- and a fourth, which sets an annotation and label via `options` for that single ConfigMap
Each configMapGenerator item accepts a parameter of
`behavior: [create|replace|merge]`.
This allows an overlay to modify or
replace an existing configMap from the parent.
Also, each entry has an `options` field, that has the
same subfields as the kustomization file's `generatorOptions` field.
This `options` field allows one to add labels and/or
annotations to the generated instance, or to individually
disable the name suffix hash for that instance.
Labels and annotations added here will not be overwritten
by the global options associated with the kustomization
file `generatorOptions` field. However, due to how
booleans behave, if the global `generatorOptions` field
specifies `disableNameSuffixHash: true`, this will
trump any attempt to locally override it.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
# These labels are added to all configmaps and secrets.
generatorOptions:
labels:
fruit: apple
configMapGenerator:
- name: my-java-server-props
behavior: merge
files:
- application.properties
- more.properties
- name: my-java-server-env-file-vars
envs:
- my-server-env.properties
- more-server-props.env
- name: my-java-server-env-vars
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
options:
disableNameSuffixHash: true
labels:
pet: dog
- name: dashboards
files:
- mydashboard.json
options:
annotations:
dashboard: "1"
labels:
app.kubernetes.io/name: "app1"
```
It is also possible to
[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file)
to set a name different than the filename.
The example below creates a ConfigMap
with the name of file as `myFileName.ini`
while the _actual_ filename from which the
configmap is created is `whatever.ini`.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: app-whatever
files:
- myFileName.ini=whatever.ini
```
## ConfigMap `from File`
ConfigMap Resources may be generated from files - such as a java `.properties` file. To generate a ConfigMap
Resource for a file, add an entry to `configMapGenerator` with the filename.
**Example:** Generate a ConfigMap with a data item containing the contents of a file.
The ConfigMaps will have data values populated from the file contents. The contents of each file will
appear as a single data item in the ConfigMap keyed by the filename.
The example illustrates how you can create ConfigMaps from File using Generators.
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: my-application-properties
files:
- application.properties
```
```yaml
# application.properties
FOO=Bar
```
### Build Output
```yaml
apiVersion: v1
data:
application.properties: |-
FOO=Bar
kind: ConfigMap
metadata:
name: my-application-properties-f7mm6mhf59
```
## ConfigMap `from Literals`
ConfigMap Resources may be generated from literal key-value pairs - such as `JAVA_HOME=/opt/java/jdk`.
To generate a ConfigMap Resource from literal key-value pairs, add an entry to `configMapGenerator` with a
list of `literals`.
{{< alert color="success" title="Literal Syntax" >}}
- The key/value are separated by a `=` sign (left side is the key)
- The value of each literal will appear as a data item in the ConfigMap keyed by its key.
{{< /alert >}}
**Example:** Create a ConfigMap with 2 data items generated from literals.
The example illustrates how you can create ConfigMaps from Literals using Generators.
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: my-java-server-env-vars
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
```
### Build Output
```yaml
apiVersion: v1
data:
JAVA_HOME: /opt/java/jdk
JAVA_TOOL_OPTIONS: -agentlib:hprof
kind: ConfigMap
metadata:
name: my-java-server-env-vars-44k658k8gk
```
## ConfigMap `from env file`
ConfigMap Resources may be generated from key-value pairs much the same as using the literals option
but taking the key-value pairs from an environment file. These generally end in `.env`.
To generate a ConfigMap Resource from an environment file, add an entry to `configMapGenerator` with a
single `envs` entry, e.g. `envs: [ 'config.env' ]`.
{{< alert color="success" title="Environment File Syntax" >}}
- The key/value pairs inside of the environment file are separated by a `=` sign (left side is the key)
- The value of each line will appear as a data item in the ConfigMap keyed by its key.
- Pairs may span a single line only.
{{< /alert >}}
**Example:** Create a ConfigMap with 3 data items generated from an environment file.
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: tracing-options
envs:
- tracing.env
```
```bash
# tracing.env
ENABLE_TRACING=true
SAMPLER_TYPE=probabilistic
SAMPLER_PARAMETERS=0.1
```
### Build Output
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
# The name has had a suffix applied
name: tracing-options-6bh8gkdf7k
# The data has been populated from each literal pair
data:
ENABLE_TRACING: "true"
SAMPLER_TYPE: "probabilistic"
SAMPLER_PARAMETERS: "0.1"
```
## Overriding Base ConfigMap Values
ConfigMap values from bases may be overridden by adding another generator for the ConfigMap
in the overlay and specifying the `behavior` field. `behavior` may be
one of:
* `create` (default value): used to create a new ConfigMap. A name conflict error will be thrown if a ConfigMap with the same name and namespace already exists.
* `replace`: replace an existing ConfigMap from the base.
* `merge`: add or update the values in an existing ConfigMap from the base.
When updating an existing ConfigMap with the `merge` or `replace` strategies, you must ensure that both the name and namespace match the ConfigMap you're targeting. For example, if the namespace is unspecified in the base, you should not specify it in the overlay. Conversely, if it is specified in the base, you must specify it in the overlay as well. This is true even if the overlay Kustomization includes a namespace, because configMapGenerator runs before the namespace transformer.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: my-new-namespace
resources:
- ../base
configMapGenerator:
- name: existing-name
namespace: existing-ns # needs to match target ConfigMap from base
behavior: replace
literals:
- ENV=dev
```
{{< alert color="warning" title="Name suffixing with overlay configMapGenerator" >}}
When using configMapGenerator to override values of an existing ConfigMap, the overlay configMapGenerator does not cause suffixing of the existing ConfigMap's name to occur. To take advantage of name suffixing, use configMapGenerator in the base, and the overlay generator will correctly update the suffix based on the new content.
{{< /alert >}}
## Propagating the Name Suffix
Workloads that reference the ConfigMap or Secret will need to know the name of the generated Resource,
including the suffix. Kustomize takes care of this automatically by identifying
references to generated ConfigMaps and Secrets, and updating them.
In the following example, the generated ConfigMap name will be `my-java-server-env-vars` with a suffix unique to its contents.
Changes to the contents will change the name suffix, resulting in the creation of a new ConfigMap,
which Kustomize will transform Workloads to point to.
The PodTemplate volume references the ConfigMap by the name specified in the generator (excluding the suffix).
Kustomize will update the name to include the suffix applied to the ConfigMap name.
**Input:** The kustomization.yaml and deployment.yaml files
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: my-java-server-env-vars
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
resources:
- deployment.yaml
```
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: test-deployment
labels:
app: test
spec:
selector:
matchLabels:
app: test
template:
metadata:
labels:
app: test
spec:
containers:
- name: container
image: registry.k8s.io/busybox
command: [ "/bin/sh", "-c", "ls /etc/config/" ]
volumeMounts:
- name: config-volume
mountPath: /etc/config
volumes:
- name: config-volume
configMap:
name: my-java-server-env-vars
```
**Result:** The output of the Kustomize build.
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
# The name has been updated to include the suffix
name: my-java-server-env-vars-k44mhd6h5f
data:
JAVA_HOME: /opt/java/jdk
JAVA_TOOL_OPTIONS: -agentlib:hprof
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: test
name: test-deployment
spec:
selector:
matchLabels:
app: test
template:
metadata:
labels:
app: test
spec:
containers:
- command:
- /bin/sh
- -c
- ls /etc/config/
image: registry.k8s.io/busybox
name: container
volumeMounts:
- mountPath: /etc/config
name: config-volume
volumes:
- configMap:
# The name has been updated to include the
# suffix matching the ConfigMap
name: my-java-server-env-vars-k44mhd6h5f
name: config-volume
```

41
site/content/en/docs/Reference/API/crds.md Normal file
View File

@@ -0,0 +1,41 @@
---
title: "crds"
linkTitle: "crds"
type: docs
weight: 7
description: >
Adding CRD support
---
Each entry in this list should be a relative path to
a file for custom resource definition (CRD).
The presence of this field is to allow kustomize be
aware of CRDs and apply proper
transformation for any objects in those types.
Typical use case: A CRD object refers to a
ConfigMap object. In a kustomization, the ConfigMap
object name may change by adding namePrefix,
nameSuffix, or hashing. The name reference for this
ConfigMap object in CRD object need to be updated
with namePrefix, nameSuffix, or hashing in the
same way.
The annotations can be put into openAPI definitions are:
- "x-kubernetes-annotation": ""
- "x-kubernetes-label-selector": ""
- "x-kubernetes-identity": ""
- "x-kubernetes-object-ref-api-version": "v1",
- "x-kubernetes-object-ref-kind": "Secret",
- "x-kubernetes-object-ref-name-key": "name",
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
crds:
- crds/typeA.yaml
- crds/typeB.yaml
```

117
site/content/en/docs/Reference/API/generatorOptions.md Normal file
View File

@@ -0,0 +1,117 @@
---
title: "generatorOptions"
linkTitle: "generatorOptions"
type: docs
weight: 8
description: >
Control behavior of [ConfigMap]() and
[Secret]() generators.
---
Additionally, generatorOptions can be set on a per resource level within each
generator. For details on per-resource generatorOptions usage see
[field-name-configMapGenerator]() and See [field-name-secretGenerator]().
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
generatorOptions:
# labels to add to all generated resources
labels:
kustomize.generated.resources: somevalue
# annotations to add to all generated resources
annotations:
kustomize.generated.resource: somevalue
# disableNameSuffixHash is true disables the default behavior of adding a
# suffix to the names of generated resources that is a hash of
# the resource contents.
disableNameSuffixHash: true
# if set to true, the immutable property is added to generated resources
immutable: true
```
## Example I
Using ConfigMap
### Input Files
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: my-application-properties
files:
- application.properties
generatorOptions:
labels:
kustomize.generated.resources: config-label
annotations:
kustomize.generated.resource: config-annotation
```
```yaml
# application.properties
FOO=Bar
```
### Output File
```yaml
apiVersion: v1
data:
application.properties: |-
# application.properties
FOO=Bar
kind: ConfigMap
metadata:
annotations:
kustomize.generated.resource: config-annotation
labels:
kustomize.generated.resources: config-label
name: my-application-properties-f7mm6mhf59
```
## Example II
Using Secrets
### Input Files
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
secretGenerator:
- name: app-tls
files:
- "tls.cert"
- "tls.key"
type: "kubernetes.io/tls"
generatorOptions:
labels:
kustomize.generated.resources: secret-label
annotations:
kustomize.generated.resource: secret-annotation
disableNameSuffixHash: true
```
### Output File
```yaml
apiVersion: v1
data:
tls.cert: TFMwdExTMUNSVWQuLi50Q2c9PQ==
tls.key: TFMwdExTMUNSVWQuLi4wdExRbz0=
kind: Secret
metadata:
annotations:
kustomize.generated.resource: secret-annotation
labels:
kustomize.generated.resources: secret-label
name: app-tls
type: kubernetes.io/tls
```

46
site/content/en/docs/Reference/API/helmCharts.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: "helmCharts"
linkTitle: "helmCharts"
type: docs
weight: 8
description: >
Helm chart inflation generator.
---
[kustomize builtins]: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_helmchartinflationgenerator_
[Helm support long term plan]: https://github.com/kubernetes-sigs/kustomize/issues/4401
## Helm Chart Inflation Generator
Kustomize has limited support for helm chart inflation through the `helmCharts` field.
You can read a detailed description of this field in the docs about [kustomize builtins].
To enable the helm chart inflation generator, you have to specify the `enable-helm` flag as follows:
```sh
kustomize build --enable-helm
```
## Long term support
The helm chart inflation generator in kustomize is intended to be a limited subset of helm features to help with
getting started with kustomize, and we cannot support the entire helm feature set.
### The current builtin
For enhancements to the helm chart inflation generator feature, we will only support the following changes:
- bug fixes
- critical security issues
- additional fields that are analogous to flags passed to `helm template`, except for flags such as `post-renderer`
that allow arbitrary commands to be executed
We will not add support for:
- private repository or registry authentication
- OCI registries
- other large features that increase the complexity of the feature and/or have significant security implications
### Future support
The next iteration of the helm inflation generator will take the form of a KRM function, which will have
no such restrictions on what types of features we can add and support. You can see more details in
the [Helm support long term plan].

169
site/content/en/docs/Reference/API/images.md Normal file
View File

@@ -0,0 +1,169 @@
---
title: "images"
linkTitle: "images"
type: docs
weight: 9
description: >
Modify the name, tags and/or digest for images.
---
Images modify the name, tags and/or digest for images without creating patches.
One can change the `image` in the following ways (Refer the following example to know exactly how this is done):
- `postgres:8` to `my-registry/my-postgres:v1`,
- nginx tag `1.7.9` to `1.8.0`,
- image name `my-demo-app` to `my-app`,
- alpine's tag `3.7` to a digest value
It is possible to set image tags for container images through
the `kustomization.yaml` using the `images` field. When `images` are
specified, Apply will override the images whose image name matches `name` with a new
tag.
| Field | Description | Example Field | Example Result |
|-----------|--------------------------------------------------------------------------|----------| --- |
| `name` | Match images with this image name| `name: nginx`| |
| `newTag` | Override the image **tag** or **digest** for images whose image name matches `name` | `newTag: new` | `nginx:old` -> `nginx:new` |
| `newName` | Override the image **name** for images whose image name matches `name` | `newName: nginx-special` | `nginx:old` -> `nginx-special:old` |
## Example
### File Input
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
template:
spec:
containers:
- name: mypostgresdb
image: postgres:8
- name: nginxapp
image: nginx:1.7.9
- name: myapp
image: my-demo-app:latest
- name: alpine-app
image: alpine:3.7
```
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
images:
- name: postgres
newName: my-registry/my-postgres
newTag: v1
- name: nginx
newTag: 1.8.0
- name: my-demo-app
newName: my-app
- name: alpine
digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
resources:
- deployment.yaml
```
### Build Output
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
template:
spec:
containers:
- image: my-registry/my-postgres:v1
name: mypostgresdb
- image: nginx:1.8.0
name: nginxapp
- image: my-app:latest
name: myapp
- image: alpine@sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
name: alpine-app
```
## Setting a Name
The name for an image may be set by specifying `newName` and the name of the old container image.
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
images:
- name: mycontainerregistry/myimage
newName: differentregistry/myimage
```
## Setting a Tag
The tag for an image may be set by specifying `newTag` and the name of the container image.
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
images:
- name: mycontainerregistry/myimage
newTag: v1
```
## Setting a Digest
The digest for an image may be set by specifying `digest` and the name of the container image.
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
images:
- name: alpine
digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
```
## Setting a Tag from the latest commit SHA
A common CI/CD pattern is to tag container images with the git commit SHA of source code. e.g. if
the image name is `foo` and an image was built for the source code at commit `1bb359ccce344ca5d263cd257958ea035c978fd3`
then the container image would be `foo:1bb359ccce344ca5d263cd257958ea035c978fd3`.
A simple way to push an image that was just built without manually updating the image tags is to
download the [kustomize standalone](https://github.com/kubernetes-sigs/kustomize/) tool and run
`kustomize edit set image` command to update the tags for you.
**Example:** Set the latest git commit SHA as the image tag for `foo` images.
```bash
kustomize edit set image foo:$(git log -n 1 --pretty=format:"%H")
kubectl apply -f .
```
## Setting a Tag from an Environment Variable
It is also possible to set a Tag from an environment variable using the same technique for setting from a commit SHA.
**Example:** Set the tag for the `foo` image to the value in the environment variable `FOO_IMAGE_TAG`.
```bash
kustomize edit set image foo:$FOO_IMAGE_TAG
kubectl apply -f .
```
{{< alert color="success" title="Committing Image Tag Updates" >}}
The `kustomization.yaml` changes *may* be committed back to git so that they
can be audited. When committing the image tag updates that have already
been pushed by a CI/CD system, be careful not to trigger new builds +
deployments for these changes.
{{< /alert >}}

237
site/content/en/docs/Reference/API/labels.md Normal file
View File

@@ -0,0 +1,237 @@
---
title: "labels"
linkTitle: "labels"
type: docs
weight: 10
description: >
Add labels and optionally selectors to all resources.
---
A field that allows adding labels without also automatically injecting corresponding selectors.
This can be used instead of the `commonLabels` field, which always adds selectors.
{{% pageinfo color="warning" %}}
Selectors for resources such as Deployments and Services shouldn't be changed once the
resource has been applied to a cluster.
Changing `includeSelectors` to `true` or changing labels when `includeSelectors` is `true` in live resources
is equivalent to changing `commonLabels` and could result in failures.
{{% /pageinfo %}}
The following flags are available:
* `includeTemplates`: When set will also apply labels to metadata/labels and spec/template/metadata/labels. This can be used to add labels to Pods from owner resources, such as Deployments and StatefulSets, without modifying selectors. False by default.
* `includeSelectors`: When set will apply labels to metadata/labels, selectors, and spec/template/metadata/labels. False by default.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
labels:
- pairs:
someName: someValue
owner: alice
app: bingo
includeSelectors: true # <-- false by default
includeTemplates: true # <-- false by default
```
## Example 1 - selectors and templates NOT modified
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
labels:
- pairs:
someName: someValue
owner: alice
app: bingo
resources:
- deploy.yaml
- service.yaml
```
```yaml
# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
```
```yaml
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: example
```
### Build Output
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
```
## Example 2 - selectors modified
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
labels:
- pairs:
someName: someValue
owner: alice
app: bingo
includeSelectors: true
resources:
- deploy.yaml
- service.yaml
```
```yaml
# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
```
```yaml
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: example
```
### Build Output
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
spec:
selector:
app: bingo
owner: alice
someName: someValue
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
spec:
selector:
matchLabels:
app: bingo
owner: alice
someName: someValue
template:
metadata:
labels:
app: bingo
owner: alice
someName: someValue
```
## Example 3 - templates modified
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
labels:
- pairs:
someName: someValue
owner: alice
app: bingo
includeTemplates: true
resources:
- deploy.yaml
- service.yaml
```
```yaml
# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example
```
```yaml
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: example
```
### Build Output
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: bingo
owner: alice
someName: someValue
name: example
spec:
template:
metadata:
labels:
app: bingo
owner: alice
someName: someValue
```

64
site/content/en/docs/Reference/API/namePrefix.md Normal file
View File

@@ -0,0 +1,64 @@
---
title: "namePrefix"
linkTitle: "namePrefix"
type: docs
weight: 11
description: >
Prepends the value to the names of all resources and references.
---
As `namePrefix` is self explanatory, it helps adding prefix to names in the defined yaml files.
## Example
### File Input
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
replicas: 5
template:
containers:
- name: the-container
image: registry/container:latest
```
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: custom-prefix-
resources:
- deployment.yaml
```
### Build Output
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: custom-prefix-the-deployment
spec:
replicas: 5
template:
containers:
- image: registry/container:latest
name: the-container
```
{{< alert color="success" title="References" >}}
Apply will propagate the `namePrefix` to any place Resources within the project are referenced by other Resources
including:
- Service references from StatefulSets
- ConfigMap references from PodSpecs
- Secret references from PodSpecs
{{< /alert >}}

57
site/content/en/docs/Reference/API/nameSuffix.md Normal file
View File

@@ -0,0 +1,57 @@
---
title: "nameSuffix"
linkTitle: "nameSuffix"
type: docs
weight: 13
description: >
Appends the value to the names of all resources and references.
---
As `nameSuffix` is self explanatory, it helps adding suffix to names in the defined yaml files.
**Note:** The suffix is appended before the content hash if the resource type is ConfigMap or Secret.
## Example
### File Input
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
replicas: 5
template:
containers:
- name: the-container
image: registry/container:latest
```
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
nameSuffix: -custom-suffix
resources:
- deployment.yaml
```
### Build Output
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment-custom-suffix
spec:
replicas: 5
template:
containers:
- image: registry/container:latest
name: the-container
```

58
site/content/en/docs/Reference/API/namespace.md Normal file
View File

@@ -0,0 +1,58 @@
---
title: "namespace"
linkTitle: "namespace"
type: docs
weight: 12
description: >
Adds namespace to all resources.
---
Will override the existing namespace if it is set on a resource, or add it
if it is not set on a resource.
## Example
### File Input
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
namespace: the-namespace
spec:
replicas: 5
template:
containers:
- name: the-container
image: registry/container:latest
```
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: kustomize-namespace
resources:
- deployment.yaml
```
### Build Output
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
namespace: kustomize-namespace
spec:
replicas: 5
template:
containers:
- image: registry/container:latest
name: the-container
```

217
site/content/en/docs/Reference/API/openapi.md Normal file
View File

@@ -0,0 +1,217 @@
---
title: "openapi"
linkTitle: "openapi"
type: docs
weight: 14
description: >
Specify where kustomize gets its OpenAPI schema.
---
Kustomize uses kubernetes OpenAPI data to get merge key and patch strategy
information about resource types. Kustomize has an OpenAPI schema builtin,
but this schema only has information about builtin kubernetes types. If
you need to provide merge key and patch strategy information about custom
resource types, you will have to provide your own OpenAPI schema to do so.
In your kustomization file, you can specify where kustomize should get
its OpenAPI schema via an `openapi` field. For example:
```yaml
resources:
- my_resource.yaml
openapi:
path: my_schema.json
```
The `openapi` field of a kustomization file can either a path to a custom schema
file, as in the example above. It can also be used to explicitly tell kustomize to
use a builtin kubernetes OpenAPI schema:
```yaml
resources:
- my_resource.yaml
openapi:
version: v1.20.4
```
You can see what builtin kubernetes OpenAPI schemas are available with the command
`kustomize openapi info`.
Here is an example of a custom resource we might want to edit with a custom OpenAPI schema
file. It looks like this:
```yaml
apiVersion: example.com/v1alpha1
kind: MyResource
metadata:
name: service
spec:
template:
spec:
containers:
- name: server
image: server
command: example
ports:
- name: grpc
protocol: TCP
containerPort: 8080
```
This resource has an image field. Let's change its value from `server`
to `nginx` with a patch. You can get an OpenAPI document like this from
your locally favored cluster with the command `kustomize openapi fetch`.
Kustomize will use the OpenAPI extensions `x-kubernetes-patch-merge-key` and
`x-kubernetes-patch-strategy` to perform a strategic merge.
`x-kubernetes-patch-strategy` should be set to "merge", and you can set your
merge key to whatever you like.
Below, our custom resource inherits merge keys from PodTemplateSpec. In the
definition of "io.k8s.api.core.v1.Container", the `ports` field has its merge
key set to "containerPort":
```json
{
"definitions": {
"v1alpha1.MyResource": {
"properties": {
"apiVersion": {
"type": "string"
},
"kind": {
"type": "string"
},
"metadata": {
"type": "object"
},
"spec": {
"properties": {
"template": {
"\$ref": "#/definitions/io.k8s.api.core.v1.PodTemplateSpec"
}
},
"type": "object"
},
"status": {
"properties": {
"success": {
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object",
"x-kubernetes-group-version-kind": [
{
"group": "example.com",
"kind": "MyResource",
"version": "v1alpha1"
}
]
},
"io.k8s.api.core.v1.PodTemplateSpec": {
"properties": {
"metadata": {
"\$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta"
},
"spec": {
"\$ref": "#/definitions/io.k8s.api.core.v1.PodSpec"
}
},
"type": "object"
},
"io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta": {
"properties": {
"name": {
"type": "string"
}
},
"type": "object"
},
"io.k8s.api.core.v1.PodSpec": {
"properties": {
"containers": {
"items": {
"\$ref": "#/definitions/io.k8s.api.core.v1.Container"
},
"type": "array",
"x-kubernetes-patch-merge-key": "name",
"x-kubernetes-patch-strategy": "merge"
}
},
"type": "object"
},
"io.k8s.api.core.v1.Container": {
"properties": {
"command": {
"items": {
"type": "string"
},
"type": "array"
},
"image": {
"type": "string"
},
"name": {
"type": "string"
},
"ports": {
"items": {
"\$ref": "#/definitions/io.k8s.api.core.v1.ContainerPort"
},
"type": "array",
"x-kubernetes-list-map-keys": [
"containerPort",
"protocol"
],
"x-kubernetes-list-type": "map",
"x-kubernetes-patch-merge-key": "containerPort",
"x-kubernetes-patch-strategy": "merge"
}
},
"type": "object"
},
"io.k8s.api.core.v1.ContainerPort": {
"properties": {
"containerPort": {
"format": "int32",
"type": "integer"
},
"name": {
"type": "string"
},
"protocol": {
"type": "string"
}
},
"type": "object"
}
}
}
```
Then, our kustomization file to do the patch can be as follows:
```yaml
resources:
- my_resource.yaml
openapi:
path: my_schema.json
patchesStrategicMerge:
- |-
apiVersion: example.com/v1alpha1
kind: MyResource
metadata:
name: service
spec:
template:
spec:
containers:
- name: server
image: nginx
```

280
site/content/en/docs/Reference/API/patches.md Normal file
View File

@@ -0,0 +1,280 @@
---
title: "patches"
linkTitle: "patches"
type: docs
weight: 15
description: >
Patch resources
---
[strategic merge]: /references/kustomize/glossary#patchstrategicmerge
[JSON6902]: /references/kustomize/glossary#patchjson6902
Patches (also called overlays) add or override fields on resources. They are provided using the
`patches` Kustomization field.
The `patches` field contains a list of patches to be applied in the order they are specified.
Each patch may:
- be either a [strategic merge] patch, or a [JSON6902] patch
- be either a file, or an inline string
- target a single resource or multiple resources
The patch target selects resources by `group`, `version`, `kind`, `name`, `namespace`, `labelSelector` and
`annotationSelector`. Any resource which matches all the **specified** fields has the patch applied
to it (regular expressions).
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patches:
- path: patch.yaml
target:
group: apps
version: v1
kind: Deployment
name: deploy.*
labelSelector: "env=dev"
annotationSelector: "zone=west"
- patch: |-
- op: replace
path: /some/existing/path
value: new value
target:
kind: MyKind
labelSelector: "env=dev"
```
The `name` and `namespace` fields of the patch target selector are
automatically anchored regular expressions. This means that the value `myapp`
is equivalent to `^myapp$`.
## Name and kind changes
With `patches` it is possible to override the kind or name of the resource it is
editing with the options `allowNameChange` and `allowKindChange`. For example:
```yaml
resources:
- deployment.yaml
patches:
- path: patch.yaml
target:
kind: Deployment
options:
allowNameChange: true
allowKindChange: true
```
By default, these fields are false and the patch will leave the kind and name of the resource untouched.
## Name references
A patch can refer to a resource by any of its previous names or kinds.
For example, if a resource has gone through name-prefix transformations, it can refer to the
resource by its current name, original name, or any intermediate name that it had.
## Patching custom resources
[Strategic merge] patches may require additional configuration via [openapi](../openapi) field to work as expected with custom resources. For example, if a resource uses a merge key other than `name` or needs a list to be merged rather than replaced, Kustomize needs openapi information informing it about this.
[JSON6902] patch usage is the same for built-in and custom resources.
## Examples
Consider the following `deployment.yaml` common for all examples:
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: dummy-app
labels:
app.kubernetes.io/name: nginx
spec:
selector:
matchLabels:
app.kubernetes.io/name: nginx
template:
metadata:
labels:
app.kubernetes.io/name: nginx
spec:
containers:
- name: nginx
image: nginx:stable
ports:
- name: http
containerPort: 80
```
### Intents
- Make the container image point to a specific version and not to the latest container in the registry.
- Adding a standard label containing the deployed version.
There are multiple possible strategies that all achieve the same results.
### Patch using Inline Strategic Merge
```yaml
# kustomization.yaml
resources:
- deployment.yaml
patches:
- patch: |-
apiVersion: apps/v1
kind: Deployment
metadata:
name: dummy-app
labels:
app.kubernetes.io/version: 1.21.0
- patch: |-
apiVersion: apps/v1
kind: Deployment
metadata:
name: not-used
spec:
template:
spec:
containers:
- name: nginx
image: nginx:1.21.0
target:
labelSelector: "app.kubernetes.io/name=nginx"
```
If a `target` is specified, the `name` contained in the metadata is required but not used.
### Patch using Inline JSON6902
```yaml
# kustomization.yaml
resources:
- deployment.yaml
patches:
- patch: |-
- op: add
path: /metadata/labels/app.kubernetes.io~1version
value: 1.21.0
target:
group: apps
version: v1
kind: Deployment
- patch: |-
- op: replace
path: /spec/template/spec/containers/0/image
value: nginx:1.21.0
target:
labelSelector: "app.kubernetes.io/name=nginx"
```
The `target` field is always required for JSON6902 patches.
A special replacement character `~1` is used to replace `/` in label name.
### Patch using Path Strategic Merge
```yaml
# kustomization.yaml
resources:
- deployment.yaml
patches:
- path: add-label.patch.yaml
- path: fix-version.patch.yaml
target:
labelSelector: "app.kubernetes.io/name=nginx"
```
As with the Inline Strategic Merge, the `target` field can be omitted.
In that case, the target resource is matched using
the `apiVersion`, `kind` and `name` from the patch.
```yaml
# add-label.patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: dummy-app
labels:
app.kubernetes.io/version: 1.21.0
```
```yaml
# fix-version.patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: not-used
spec:
template:
spec:
containers:
- name: nginx
image: nginx:1.21.0
```
As with the Inline Strategic Merge, the `name` field in the patch is not used when a `target` is specified.
### Patch using Path JSON6902
```yaml
# kustomization.yaml
resources:
- deployment.yaml
patches:
- path: add-label.patch.json
target:
group: apps
version: v1
kind: Deployment
- path: fix-version.patch.yaml
target:
labelSelector: "app.kubernetes.io/name=nginx"
```
As with Inline JSON6902, the `target` field is mandatory.
```yaml
# add-label.patch.json
[
{"op": "add", "path": "/metadata/labels/app.kubernetes.io~1version", "value": "1.21.0"}
]
```
```yaml
# fix-version.patch.yaml
- op: replace
path: /spec/template/spec/containers/0/image
value: nginx:1.21.0
```
External patch file can be written both as YAML or JSON.
The content must follow the JSON6902 standard.
### Build Output
All four patches strategies lead to the exact same output:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/name: nginx
app.kubernetes.io/version: 1.21.0
name: dummy-app
spec:
selector:
matchLabels:
app.kubernetes.io/name: nginx
template:
metadata:
labels:
app.kubernetes.io/name: nginx
spec:
containers:
- image: nginx:1.21.0
name: nginx
ports:
- containerPort: 80
name: http
```

80
site/content/en/docs/Reference/API/patchesStrategicMerge.md Normal file
View File

@@ -0,0 +1,80 @@
---
title: "patchesStrategicMerge"
linkTitle: "patchesStrategicMerge"
type: docs
weight: 17
description: >
Patch resources using the strategic merge patch standard.
---
{{% pageinfo color="warning" %}}
The `patchesStrategicMerge` field was deprecated in v5.0.0. This field will never be removed from the
kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included
in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available,
we will announce the deprecation of the v1beta1 version. There will be at least
two releases between deprecation and removal of Kustomization v1beta1 support from the
kustomize CLI, and removal itself will happen in a future major version bump.
Please move your `patchesStrategicMerge` into
the [patches](/references/kustomize/kustomization/patches) field. This field supports patchesStrategicMerge,
but with slightly different syntax. You can run `kustomize edit fix` to automatically convert
`patchesStrategicMerge` to `patches`.
{{% /pageinfo %}}
Each entry in this list should be either a relative
file path or an inline content
resolving to a partial or complete resource
definition.
The names in these (possibly partial) resource
files must match names already loaded via the
`resources` field. These entries are used to
_patch_ (modify) the known resources.
Small patches that do one thing are best, e.g. modify
a memory request/limit, change an env var in a
ConfigMap, etc. Small patches are easy to review and
easy to mix together in overlays.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesStrategicMerge:
- service_port_8888.yaml
- deployment_increase_replicas.yaml
- deployment_increase_memory.yaml
```
The patch content can be a inline string as well.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesStrategicMerge:
- |-
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx
spec:
template:
spec:
containers:
- name: nginx
image: nignx:latest
```
Note that kustomize does not support more than one patch
for the same object that contain a _delete_ directive. To remove
several fields / slice elements from an object create a single
patch that performs all the needed deletions.
A patch can refer to a resource by any of its previous names or kinds.
For example, if a resource has gone through name-prefix transformations, it can refer to the
resource by its current name, original name, or any intermediate name that it had.
## Patching custom resources
Strategic merge patches may require additional configuration via [openapi](../openapi) field to work as expected with custom resources. For example, if a resource uses a merge key other than `name` or needs a list to be merged rather than replaced, Kustomize needs openapi information informing it about this.

111
site/content/en/docs/Reference/API/patchesjson6902.md Normal file
View File

@@ -0,0 +1,111 @@
---
title: "patchesJson6902"
linkTitle: "patchesJson6902"
type: docs
weight: 16
description: >
Patch resources using the [json 6902 standard](https://tools.ietf.org/html/rfc6902)
---
{{% pageinfo color="warning" %}}
The `patchesJson6902` field was deprecated in v5.0.0. This field will never be removed from the
kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included
in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available,
we will announce the deprecation of the v1beta1 version. There will be at least
two releases between deprecation and removal of Kustomization v1beta1 support from the
kustomize CLI, and removal itself will happen in a future major version bump.
Please move your `patchesJson6902` into
the [patches](/references/kustomize/kustomization/patches) field. This field supports patchesJson6902,
but with slightly different syntax. You can run `kustomize edit fix` to automatically convert
`patchesJson6902` to `patches`.
{{% /pageinfo %}}
Each entry in this list should resolve to a kubernetes object and a JSON patch that will be applied
to the object.
The JSON patch is documented at <https://tools.ietf.org/html/rfc6902>
target field points to a kubernetes object within the same kustomization
by the object's group, version, kind, name and namespace.
path field is a relative file path of a JSON patch file.
The content in this patch file can be either in JSON format as
```json
[
{"op": "add", "path": "/some/new/path", "value": "value"},
{"op": "replace", "path": "/some/existing/path", "value": "new value"},
{"op": "copy", "from": "/some/existing/path", "path": "/some/path"},
{"op": "move", "from": "/some/existing/path", "path": "/some/existing/destination/path"},
{"op": "remove", "path": "/some/existing/path"},
{"op": "test", "path": "/some/path", "value": "my-node-value"}
]
```
or in YAML format as
```yaml
# add: creates a new entry with a given value
- op: add
path: /some/new/path
value: value
# replace: replaces the value of the node with the new specified value
- op: replace
path: /some/existing/path
value: new value
# copy: copies the value specified in from to the destination path
- op: copy
from: /some/existing/path
path: /some/path
# move: moves the node specified in from to the destination path
- op: move
from: /some/existing/path
path: /some/existing/destination/path
# remove: delete's the node('s subtree)
- op: remove
path: /some/path
# test: check if the specified node has the specified value, if the value differs it will throw an error
- op: test
path: /some/path
value: "my-node-value"
```
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesJson6902:
- target:
version: v1
kind: Deployment
name: my-deployment
path: add_init_container.yaml
- target:
version: v1
kind: Service
name: my-service
path: add_service_annotation.yaml
```
The patch content can be an inline string as well:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesJson6902:
- target:
version: v1
kind: Deployment
name: my-deployment
patch: |-
- op: add
path: /some/new/path
value: value
- op: replace
path: /some/existing/path
value: "new value"
```
A patch can refer to a resource by any of its previous names or kinds.
For example, if a resource has gone through name-prefix transformations, it can refer to the
resource by its current name, original name, or any intermediate name that it had.

387
site/content/en/docs/Reference/API/replacements.md Normal file
View File

@@ -0,0 +1,387 @@
---
title: "replacements"
linkTitle: "replacements"
type: docs
weight: 18
description: >
Substitute field(s) in N target(s) with a field from a source.
---
Replacements are used to copy fields from one source into any
number of specified targets.
\
The `replacements` field can support a path to a replacement:
`kustomization.yaml`
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
replacements:
- path: replacement.yaml
```
`replacement.yaml`
```yaml
source:
kind: Deployment
fieldPath: metadata.name
targets:
- select:
name: my-resource
```
\
Alternatively, `replacements` supports inline replacements:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
replacements:
- source:
kind: Deployment
fieldPath: metadata.name
targets:
- select:
name: my-resource
```
### Syntax
The full schema of `replacements` is as follows:
```yaml
replacements:
- source:
group: string
version: string
kind: string
name: string
namespace: string
fieldPath: string
options:
delimiter: string
index: int
create: bool
targets:
- select:
group: string
version: string
kind: string
name: string
namespace: string
reject:
- group: string
version: string
kind: string
name: string
namespace: string
fieldPaths:
- string
options:
delimiter: string
index: int
create: bool
```
### Field Descriptions
| Field | Required| Description | Default |
| -----------: | :----:| ----------- | ---- |
| `source`| :heavy_check_mark: | The source of the value |
| `target`|:heavy_check_mark: | The N fields to write the value to |
| `group` | | The group of the referent |
| `version`| | The version of the referent
|`kind` | |The kind of the referent
|`name` | |The name of the referent
|`namespace`| |The namespace of the referent
|`select` |:heavy_check_mark: |Include objects that match this
|`reject`| |Exclude objects that match this
|`fieldPath`| |The structured path to the source value | `metadata.name`
|`fieldPaths`| |The structured path(s) to the target nodes | `metadata.name`
|`options`| |Options used to refine interpretation of the field
|`delimiter`| |Used to split/join the field
|`index`| |Which position in the split to consider | `0`
|`create`| |If target field is missing, add it | `false`
#### Source
The source field is a selector that determines the source of the value by finding a
match to the specified GVKNN. All the subfields of `source` are optional,
but the source selection must resolve to a single resource.
#### Targets
Replacements will be applied to all targets that are matched by the `select` field and
are NOT matched by the `reject` field, and will be applied to all listed `fieldPaths`.
##### Select
You can use any of the following fields to select the targets to replace:
`group`, `version`, `kind`, `name`, `namespace`
For example, the following will select all the Deployments as targets of replacement.
```yaml
select:
kind: Deployment
```
Also, you can use multiple fields together to select only the resources that match all the conditions.
For example, the following will select only the Deployments that are named my-deploy:
```yaml
select:
- kind: Deployment
name: my-deploy
```
Moreover, when the selected target is going to be transformed during the kustomization process,
you can use either the original or the transformed resource id to select it.
For example, the name of the target could be changed because of the `namePrefix` field, as below:
```yaml
namePrefix: my-
```
In this case, below will be enough if we wanted to select all the targets that were originally named deploy:
```yaml
select:
- name: deploy
```
Alternatively, using the transformed name with the prefix will produce the same behaviour.
So the following case will select all the resources that *will be* named my-deploy,
along with all the resources that *were* originally named my-deploy.
```yaml
select:
- name: my-deploy
```
##### Reject
The reject field is a selector that drops targets selected by select, overruling their selection.
For example, if we wanted to reject all Deployments named my-deploy:
```yaml
reject:
- kind: Deployment
name: my-deploy
```
This is distinct from the following:
```yaml
reject:
- kind: Deployment
- name: my-deploy
```
The first case would only reject resources that are both of kind Deployment and named my-deploy. The second case would reject all Deployments, and all resources named my-deploy.
We can also reject more than one kind, name, etc. For example:
```yaml
reject:
- kind: Deployment
- kind: StatefulSet
```
Moreover, when the selected target is going to be transformed during the kustomization process,
you can use either the original or the transformed resource id to reject it.
For example, the name of the target could be changed because of the `nameSuffix` field, as below:
```yaml
nameSuffix: -dev
```
You can use the original target name to prevent it from going through any replacement.
```yaml
reject:
- name: my-deploy
```
Alternatively, using the transformed name with the suffix will produce the same behaviour.
```yaml
reject:
- name: my-deploy-dev
```
#### Delimiter
This field is intended to be used in conjunction with the `index` field for partial string replacement.
For example, say we have a value:
`path: my/path/VALUE`
In our replacement target, we can specify something like:
```yaml
options:
delimiter: '/'
index: 2
```
and it would replace VALUE, e.g. `path: my/path/NEW_VALUE`.
#### Index
This field is intended to be used in conjunction with the `delimiter` field described above for partial string
replacement. The default value is 0.
If the index is out of bounds, behavior depends on whether it is in a source or target. In a source, an index out of bounds
will throw an error. For a target, a value less than 0 will cause the target to be prefixed, and a value beyond
the length of the split will cause the target to be suffixed.
If the fields `index` and `delimiter` are specified on sources or targets that are not scalar values (e.g. mapping or list values),
kustomize will throw an error.
#### Field Path format
The fieldPath and fieldPaths fields support a format of a '.'-separated path to a value. For example, the default:
`metadata.name`
You can escape the '.' one of two ways. For example, say we have the following resource:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
config.kubernetes.io/local-config: true # this is what we want to target
```
We can express our path:
1. With a '\\': `metadata.annotations.config\.kubernetes\.io/local-config`
2. With '[]': `metadata.annotations.[config.kubernetes.io/local-config]`
Strings are used for mapping nodes. For sequence nodes, we support three options:
1. Index by number: `spec.template.spec.containers.1.image`
2. Index by key-value pair: `spec.template.spec.containers.[name=nginx].image`. If the key-value pair matches multiple elements in the sequence node, all matching elements will be targetted.
3. Index with a wildcard match: `spec.template.spec.containers.*.env.[name=TARGET_ENV].value`. This will target every element in the list.
### Example
For example, suppose one specifies the name of a k8s Secret object in a container's
environment variable as follows:
`job.yaml`
```yaml
apiVersion: batch/v1
kind: Job
metadata:
name: hello
spec:
template:
spec:
containers:
- image: myimage
name: hello
env:
- name: SECRET_TOKEN
value: SOME_SECRET_NAME
```
Suppose you have the following resources:
`resources.yaml`
```yaml
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- image: busybox
name: myapp-container
restartPolicy: OnFailure
---
apiVersion: v1
kind: Secret
metadata:
name: my-secret
```
To (1) replace the value of SOME_SECRET_NAME with the name of my-secret, and (2) to add
a restartPolicy copied from my-pod, you can do the following:
`kustomization.yaml`
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- resources.yaml
- job.yaml
replacements:
- path: my-replacement.yaml
- source:
kind: Secret
name: my-secret
targets:
- select:
name: hello
kind: Job
fieldPaths:
- spec.template.spec.containers.[name=hello].env.[name=SECRET_TOKEN].value
```
`my-replacement.yaml`
```yaml
source:
kind: Pod
name: my-pod
fieldPath: spec.restartPolicy
targets:
- select:
name: hello
kind: Job
fieldPaths:
- spec.template.spec.restartPolicy
options:
create: true
```
The output of `kustomize build` will be:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: my-secret
---
apiVersion: batch/v1
kind: Job
metadata:
name: hello
spec:
template:
spec:
containers:
- env:
- name: SECRET_TOKEN
value: my-secret # this value is copied from my-secret
image: myimage
name: hello
restartPolicy: OnFailure # this value is copied from my-pod
---
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- image: busybox
name: myapp-container
restartPolicy: OnFailure
```

90
site/content/en/docs/Reference/API/replicas.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: "replicas"
linkTitle: "replicas"
type: docs
weight: 19
description: >
Change the number of replicas for a resource.
---
Given this kubernetes Deployment fragment:
```yaml
kind: Deployment
metadata:
name: deployment-name
spec:
replicas: 3
```
one can change the number of replicas to 5
by adding the following to your kustomization:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
replicas:
- name: deployment-name
count: 5
```
This field accepts a list, so many resources can
be modified at the same time.
As this declaration does not take in a `kind:` nor a `group:`
it will match any `group` and `kind` that has a matching name and
that is one of:
- `Deployment`
- `ReplicationController`
- `ReplicaSet`
- `StatefulSet`
For more complex use cases, revert to using a patch.
## Example
### Input File
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
replicas: 5
template:
containers:
- name: the-container
image: registry/container:latest
```
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
replicas:
- name: the-deployment
count: 10
resources:
- deployment.yaml
```
### Output
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
replicas: 10
template:
containers:
- name: the-container
image: registry/container:latest
```

35
site/content/en/docs/Reference/API/resources.md Normal file
View File

@@ -0,0 +1,35 @@
---
title: "resources"
linkTitle: "resources"
type: docs
weight: 20
description: >
Resources to include.
---
Each entry in this list must be a path to a _file_, or a path (or URL) referring to another
kustomization _directory_, e.g.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- myNamespace.yaml
- sub-dir/some-deployment.yaml
- ../../commonbase
- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6
- deployment.yaml
- github.com/kubernets-sigs/kustomize/examples/helloWorld?ref=test-branch
```
Resources will be read and processed in depth-first order.
Files should contain k8s resources in YAML form. A file may contain multiple resources separated by
the document marker `---`. File paths should be specified _relative_ to the directory holding the
kustomization file containing the `resources` field.
Directory specification can be relative, absolute, or part of a URL. URL specifications should
follow the [hashicorp URL] format. The directory must contain a `kustomization.yaml` file.
[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format

95
site/content/en/docs/Reference/API/secretGenerator.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: "secretGenerator"
linkTitle: "secretGenerator"
type: docs
weight: 21
description: >
Generate Secret resources.
---
Each entry in the argument list results in the creation of one Secret resource (it's a generator of N secrets).
This works like the [configMapGenerator](/references/kustomize/kustomization/configmapgenerator).
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
secretGenerator:
- name: app-tls
files:
- secret/tls.crt
- secret/tls.key
type: "kubernetes.io/tls"
- name: app-tls-namespaced
# you can define a namespace to generate
# a secret in, defaults to: "default"
namespace: apps
files:
- tls.crt=catsecret/tls.crt
- tls.key=secret/tls.key
type: "kubernetes.io/tls"
- name: env_file_secret
envs:
- env.txt
type: Opaque
- name: secret-with-annotation
files:
- app-config.yaml
type: Opaque
options:
annotations:
app_config: "true"
labels:
app.kubernetes.io/name: "app2"
```
Secret Resources may be generated much like ConfigMaps can. This includes generating them
from literals, files or environment files.
{{< alert color="success" title="Secret Syntax" >}}
Secret type is set using the `type` field.
{{< /alert >}}
## Example
### File Input
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
secretGenerator:
- name: app-tls
files:
- "tls.crt"
- "tls.key"
type: "kubernetes.io/tls"
```
```yaml
# tls.crt
LS0tLS1CRUd...tCg==
```
```yaml
# tls.key
LS0tLS1CRUd...0tLQo=
```
### Build Output
```yaml
apiVersion: v1
data:
tls.crt: TFMwdExTMUNSVWQuLi50Q2c9PQ==
tls.key: TFMwdExTMUNSVWQuLi4wdExRbz0=
kind: Secret
metadata:
name: app-tls-c888dfbhf8
type: kubernetes.io/tls
```
{{< alert color="warning" title="Important" >}}
It is important to note that the secrets are `base64` encoded
{{< /alert >}}

118
site/content/en/docs/Reference/API/sortOptions.md Normal file
View File

@@ -0,0 +1,118 @@
---
title: "sortOptions"
linkTitle: "sortOptions"
type: docs
weight: 22
description: >
Change the strategy used to sort resources at the end of the Kustomize build.
---
The `sortOptions` field is used to sort the resources kustomize outputs. It is
available in kustomize v5.0.0+.
IMPORTANT:
- Currently, this field is respected only in the top-level Kustomization (that
is, the immediate target of `kustomize build`). Any instances of the field in
Kustomizations further down the build chain (for example, in bases included
through the `resources` field) will be ignored.
- This field is the endorsed way to sort resources. It should be used instead of
the `--reorder` CLI flag, which is deprecated.
Currently, we support the following sort options:
- `legacy`
- `fifo`
```yaml
kind: Kustomization
sortOptions:
order: legacy | fifo # "legacy" is the default
```
## FIFO Sorting
In `fifo` order, kustomize does not change the order of resources. They appear
in the order they are loaded in `resources`.
### Example 1: FIFO Sorting
```yaml
kind: Kustomization
sortOptions:
order: fifo
```
## Legacy Sorting
The `legacy` sort is the default order, and is used when the sortOrder field is
unspecified.
In `legacy` order, kustomize sorts resources by using two priority lists:
- An `orderFirst` list for resources which should be first in the output.
- An `orderLast` list for resources which should be last in the output.
- Resources not on the lists will appear in between, sorted using their apiVersion and kind fields.
### Example 2: Legacy Sorting with orderFirst / orderLast lists
In this example, we use the `legacy` sort order to output `Namespace` objects
first and `Deployment` objects last.
```yaml
kind: Kustomization
sortOptions:
order: legacy
legacySortOptions:
orderFirst:
- Namespace
orderLast:
- Deployment
```
### Example 3: Default Legacy Sorting
If you specify `legacy` sort order without any arguments for the lists,
kustomize will fall back to the lists we were using before introducing this
feature. Since legacy sort is the default, this is also equivalent to not
specifying the field at all.
These two configs are equivalent:
```yaml
kind: Kustomization
sortOptions:
order: legacy
```
is equivalent to:
```yaml
kind: Kustomization
sortOptions:
order: legacy
legacySortOptions:
orderFirst:
- Namespace
- ResourceQuota
- StorageClass
- CustomResourceDefinition
- ServiceAccount
- PodSecurityPolicy
- Role
- ClusterRole
- RoleBinding
- ClusterRoleBinding
- ConfigMap
- Secret
- Endpoints
- Service
- LimitRange
- PriorityClass
- PersistentVolume
- PersistentVolumeClaim
- Deployment
- StatefulSet
- CronJob
- PodDisruptionBudget
orderLast:
- MutatingWebhookConfiguration
- ValidatingWebhookConfiguration
```

335
site/content/en/docs/Reference/API/vars.md Normal file
View File

@@ -0,0 +1,335 @@
---
title: "vars"
linkTitle: "vars"
type: docs
weight: 23
description: >
Substitute name references.
---
[replacements]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/
{{% pageinfo color="warning" %}}
The `vars` field was deprecated in v5.0.0. This field will never be removed from the
kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included
in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available,
we will announce the deprecation of the v1beta1 version. There will be at least
two releases between deprecation and removal of Kustomization v1beta1 support from the
kustomize CLI, and removal itself will happen in a future major version bump.
Please try to migrate to the
the [replacements](/references/kustomize/kustomization/replacements) field. If you are
unable to restructure your configuration to use replacements instead of vars, please
ask for help in slack or file an issue for guidance.
We are experimentally attempting to
automatically convert `vars` to `replacements` with `kustomize edit fix --vars`. However,
converting vars to replacements in this way will potentially overwrite many resource files
and the resulting files may not produce the same output when `kustomize build` is run.
We recommend doing this in a clean git repository where the change is easy to undo.
{{% /pageinfo %}}
Vars are used to capture text from one resource's field
and insert that text elsewhere - a reflection feature.
For example, suppose one specifies the name of a k8s Service
object in a container's command line, and the name of a
k8s Secret object in a container's environment variable,
so that the following would work:
```yaml
containers:
- image: myimage
command: ["start", "--host", "$(MY_SERVICE_NAME)"]
env:
- name: SECRET_TOKEN
value: $(SOME_SECRET_NAME)
```
To do so, add an entry to `vars:` as follows:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
vars:
- name: SOME_SECRET_NAME
objref:
kind: Secret
name: my-secret
apiVersion: v1
- name: MY_SERVICE_NAME
objref:
kind: Service
name: my-service
apiVersion: v1
fieldref:
fieldpath: metadata.name
- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY
objref:
kind: Deployment
name: my-deployment
apiVersion: apps/v1
fieldref:
fieldpath: spec.template.spec.restartPolicy
```
A var is a tuple of variable name, object
reference and field reference within that object.
That's where the text is found.
The field reference is optional; it defaults to
`metadata.name`, a normal default, since kustomize
is used to generate or modify the names of
resources.
At time of writing, only string type fields are
supported. No ints, bools, arrays etc. It's not
possible to, say, extract the name of the image in
container number 2 of some pod template.
A variable reference, i.e. the string '$(FOO)',
can only be placed in particular fields of
particular objects as specified by kustomize's
configuration data.
The default config data for vars is at [/api/konfig/builtinpluginconsts/varreference.go](https://github.com/kubernetes-sigs/kustomize/blob/master/api/konfig/builtinpluginconsts/varreference.go)
Long story short, the default targets are all
container command args and env value fields.
Vars should _not_ be used for inserting names in
places where kustomize is already handling that
job. E.g., a Deployment may reference a ConfigMap
by name, and if kustomize changes the name of a
ConfigMap, it knows to change the name reference
in the Deployment.
### Convert vars to replacements
There are plans to deprecate vars, so we recommend migration to [replacements] as early as possible.
#### Simple migration example
Let's first take a simple example of how to manually do this conversion. Suppose we have a container
referencing secret (similar to the above example):
`pod.yaml`
```yaml
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- image: myimage
name: hello
env:
- name: SECRET_TOKEN
value: $(SOME_SECRET_NAME)
```
and we are using vars as follows:
`kustomization.yaml`
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- pod.yaml
- secret.yaml
vars:
- name: SOME_SECRET_NAME
objref:
kind: Secret
name: my-secret
apiVersion: v1
```
In order to convert `vars` to `replacements`, we have to:
1. Replace every instance of $(SOME_SECRET_NAME) with any arbitrary placeholder value.
2. Convert the vars `objref` field to a [replacements] `source` field.
3. Replace the vars `name` fied with a [replacements] `targets` field that points to
every instance of the placeholder value in step 1.
In our simple example here, this would look like the following:
`pod.yaml`
```yaml
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- image: myimage
name: hello
env:
- name: SECRET_TOKEN
value: SOME_PLACEHOLDER_VALUE
```
`kustomization.yaml`
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- pod.yaml
- secret.yaml
replacements:
- source:
kind: Secret
name: my-secret
version: v1
targets:
- select:
kind: Pod
name: my-pod
fieldPaths:
- spec.containers.[name=hello].env.[name=SECRET_TOKEN].value
```
#### More complex migration example
Let's take a more complex usage of vars and convert it to [replacements]. We are going
to convert the vars in the [wordpress example](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/wordpress)
to replacements.
The wordpress example has the following directory structure:
```
.
├── README.md
├── kustomization.yaml
├── mysql
│   ├── deployment.yaml
│   ├── kustomization.yaml
│   ├── secret.yaml
│   └── service.yaml
├── patch.yaml
└── wordpress
├── deployment.yaml
├── kustomization.yaml
└── service.yaml
```
where `patch.yaml` has the following contents:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: wordpress
spec:
template:
spec:
initContainers:
- name: init-command
image: debian
command: ["/bin/sh"]
args: ["-c", "echo $(WORDPRESS_SERVICE); echo $(MYSQL_SERVICE)"]
containers:
- name: wordpress
env:
- name: WORDPRESS_DB_HOST
value: $(MYSQL_SERVICE)
- name: WORDPRESS_DB_PASSWORD
valueFrom:
secretKeyRef:
name: mysql-pass
key: password
```
and the top level `kustomization.yaml` has the following contents:
```
resources:
- wordpress
- mysql
patchesStrategicMerge:
- patch.yaml
namePrefix: demo-
vars:
- name: WORDPRESS_SERVICE
objref:
kind: Service
name: wordpress
apiVersion: v1
- name: MYSQL_SERVICE
objref:
kind: Service
name: mysql
apiVersion: v1
```
In this example, the patch is used to:
- Add an initial container to show the mysql service name
- Add environment variable that allow wordpress to find the mysql database
We can convert vars to replacements in this more complex case too, by taking the same steps as
the previous example. To do this, we can change the contents of `patch.yaml` to:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: wordpress
spec:
template:
spec:
initContainers:
- name: init-command
image: debian
command: ["/bin/sh"]
args: ["-c", "echo", "WORDPRESS_SERVICE", ";", "echo", "MYSQL_SERVICE"]
containers:
- name: wordpress
env:
- name: WORDPRESS_DB_HOST
value: MYSQL_SERVICE
- name: WORDPRESS_DB_PASSWORD
valueFrom:
secretKeyRef:
name: mysql-pass
key: password
```
Then, in our kustomization, we can have our replacements:
`kustomization.yaml`
```yaml
resources:
- wordpress
- mysql
patchesStrategicMerge:
- patch.yaml
namePrefix: demo-
replacements:
- source:
name: demo-wordpress
kind: Service
version: v1
targets:
- select:
kind: Deployment
name: demo-wordpress
fieldPaths:
- spec.template.spec.initContainers.[name=init-command].args.2
- source:
name: demo-mysql
kind: Service
version: v1
targets:
- select:
kind: Deployment
name: demo-wordpress
fieldPaths:
- spec.template.spec.initContainers.[name=init-command].args.5
- spec.template.spec.containers.[name=wordpress].env.[name=WORDPRESS_DB_HOST].value
```