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

Convert docs to docsy

Browse Source
This commit is contained in:
Phillip Wittrock
2020-06-07 21:07:46 -07:00
parent 25a38ad2b6
commit 42497c664f
11469 changed files with 816051 additions and 4557 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
site/content/en/api-reference/_index.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: "API Reference"
linkTitle: "API Reference"
type: docs
weight: 4
menu:
main:
weight: 40
description: >
Reference for Kustomize client-side APIs
---

483
site/content/en/api-reference/glossary/_index.md Normal file
View File

@@ -0,0 +1,483 @@
---
title: "Glossary"
linkTitle: "Glossary"
type: docs
weight: 99
description: >
Glossary of terms
---
# Glossary
[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/community/blob/master/contributors/design-proposals/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]: http://www.yaml.org/start.html
[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
[workflow]: /kustomize/guides
## 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](fields.md)
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](plugins).
## 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.

11
site/content/en/api-reference/kustomization/_index.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: "kustomization.yaml"
linkTitle: "kustomization.yaml"
type: docs
weight: 10
description: >
kustomization.yaml fields and API
---

17
site/content/en/api-reference/kustomization/bases/_index.md Normal file
View File

@@ -0,0 +1,17 @@
---
title: "bases"
linkTitle: "bases"
type: docs
description: >
Add resources from a kustomization dir.
---
{{% pageinfo color="warning" %}}
The `bases` field was deprecated in v2.1.0
{{% /pageinfo %}}
Move entries into the [resources](/kustomize/api-reference/kustomization/resources)
field. This allows bases - which are still a
[central concept](/kustomize/api-reference/kustomization/glossary#base) - to be
ordered relative to other input resources.

17
site/content/en/api-reference/kustomization/commonannotations/_index.md Normal file
View File

@@ -0,0 +1,17 @@
---
title: "commonAnnotations"
linkTitle: "commonAnnotations"
type: docs
description: >
Add annotations to add all resources.
---
Add annotations (non-identifying metadata) to all resources. These are key value pairs.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonAnnotations:
oncallPager: 800-555-1212
```

19
site/content/en/api-reference/kustomization/commonlabels/_index.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: "commonLabels"
linkTitle: "commonLabels"
type: docs
description: >
Add labels and selectors to add all resources.
---
Add labels and selectors to all resources.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonLabels:
someName: someValue
owner: alice
app: bingo
```

9
site/content/en/api-reference/kustomization/components/_index.md Normal file
View File

@@ -0,0 +1,9 @@
---
title: "components"
linkTitle: "components"
type: docs
description: >
Compose kustomizations.
---
*Coming soon*

84
site/content/en/api-reference/kustomization/configmapgenerator/_index.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: "configMapGenerator"
linkTitle: "configMapGenerator"
type: docs
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 three ConfigMaps. One with the names and contents of
the given files, one with key/value as data, and a third 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-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
```

39
site/content/en/api-reference/kustomization/crds/_index.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: "crds"
linkTitle: "crds"
type: docs
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
```

31
site/content/en/api-reference/kustomization/generatoroptions/_index.md Normal file
View File

@@ -0,0 +1,31 @@
---
title: "generatorOptions"
linkTitle: "generatorOptions"
type: docs
description: >
Control behavior of [ConfigMap](/kustomize/api-reference/kustomization/configmapgenerator) and
[Secret](/kustomize/api-reference/kustomization/secretgenerator) 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
```

52
site/content/en/api-reference/kustomization/images/_index.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: "images"
linkTitle: "images"
type: docs
description: >
Modify the name, tags and/or digest for images.
---
Images modify the name, tags and/or digest for images without creating patches. E.g. Given this
kubernetes Deployment fragment:
```yaml
kind: 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
```
one can change the `image` in the following ways:
- `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
all with the following *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
```

16
site/content/en/api-reference/kustomization/nameprefix/_index.md Normal file
View File

@@ -0,0 +1,16 @@
---
title: "namePrefix"
linkTitle: "namePrefix"
type: docs
description: >
Prepends the value to the names of all resources and references.
---
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: alices-
```
A deployment named `wordpress` would become `alices-wordpress`.

17
site/content/en/api-reference/kustomization/namespace/_index.md Normal file
View File

@@ -0,0 +1,17 @@
---
title: "namespace"
linkTitle: "namespace"
type: docs
description: >
Adds namespace to all resources.
---
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: my-namespace
```
Will override the existing namespace if it is set on a resource, or add it
if it is not set on a resource.

18
site/content/en/api-reference/kustomization/namesuffix/_index.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: "nameSuffix"
linkTitle: "nameSuffix"
type: docs
description: >
Appends the value to the names of all resources and references.
---
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
nameSuffix: -v2
```
A deployment named `wordpress` would become `wordpress-v2`.
**Note:** The suffix is appended before the content hash if the resource type is ConfigMap or Secret.

38
site/content/en/api-reference/kustomization/patches/_index.md Normal file
View File

@@ -0,0 +1,38 @@
---
title: "patches"
linkTitle: "patches"
type: docs
description: >
Patch resources
---
Each entry in this list should resolve to patch object, which includes a patch and a target selector.
The patch can be either a strategic merge patch or a JSON patch. It can be either a patch file, or an inline
string. The target selects resources by group, version, kind, name, namespace, labelSelector and
annotationSelector. Any resource which matches all the specified fields has the patch applied.
```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$`.

56
site/content/en/api-reference/kustomization/patchesStrategicMerge/_index.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: "patchesStrategicMerge"
linkTitle: "patchesStrategicMerge"
type: docs
description: >
Patch resources using the strategic merge patch standard.
---
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.

71
site/content/en/api-reference/kustomization/patchesjson6902/_index.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: "patchesJson6902"
linkTitle: "patchesJson6902"
type: docs
description: >
Patch resources using the [json 6902 standard](https://tools.ietf.org/html/rfc6902)
---
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"}
]
```
or in YAML format as
```yaml
- op: add
path: /some/new/path
value: value
- op: replace
path: /some/existing/path
value: new 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"
```

43
site/content/en/api-reference/kustomization/replicas/_index.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: "replicas"
linkTitle: "replicas"
type: docs
description: >
Change the number of replicas for a resource.
---
Given this kubernetes Deployment fragment:
```
# deployment.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:
```
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.

34
site/content/en/api-reference/kustomization/resources/_index.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: "resources"
linkTitle: "resources"
type: docs
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.
[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format
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.

44
site/content/en/api-reference/kustomization/secretegenerator/_index.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: "secretGenerator"
linkTitle: "secretGenerator"
type: docs
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](/kustomize/api-reference/kustomization/configmapgenerator).
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
secretGenerator:
- name: app-tls
files:
- secret/tls.cert
- 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.cert
- 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"
```

85
site/content/en/api-reference/kustomization/vars/_index.md Normal file
View File

@@ -0,0 +1,85 @@
---
title: "vars"
linkTitle: "vars"
type: docs
description: >
Substitute name references.
---
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](/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.