kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-11 17:12:51 +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

22
site/content/en/_index.md Normal file
View File

@@ -0,0 +1,22 @@
+++
title = "Kustomize"
linkTitle = "Kustomize"
+++
{{% blocks/lead color="primary" %}}
Kustomize provides a solution for customizing Kubernetes resource configuration free from templates
and DSLs.
{{% /blocks/lead %}}
{{< blocks/section >}}
{{% blocks/feature icon="fab fa-github" title="Contribute" %}}
We do a [Pull Request](https://github.com/kubernetes-sigs/kustomize/pulls) contributions workflow on **GitHub**.
New users are always welcome!
{{% /blocks/feature %}}
{{< /blocks/section >}}

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.

7
site/content/en/blog/_index.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: "Kustomize Blog"
linkTitle: "Blog"
menu:
main:
weight: 80
---

6
site/content/en/blog/releases/_index.md Normal file
View File

@@ -0,0 +1,6 @@
---
title: "New Releases"
linkTitle: "Releases"
weight: 20
---

22
site/content/en/blog/releases/v1.0.1.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: "v1.0.1"
linkTitle: "v1.0.1"
date: 2018-05-21
description: >
Kustomize v1.0.1
---
Initial release after move from github.com/kubernetes/kubectl to github.com/kubernetes-sigs/kustomize.
History
* May 2018: v1.0 after move to github.com/kubernetes-sigs/kubectl
from github.com/kubernetes/kubectl.
Has kustomization file, bases, overlays, basic transforms.
* Apr 2018: s/kinflate/kustomize/, s/manifest/kustomization/
* Oct 2017: s/kexpand/kinflate/
* Sep 2017: kexpand [starts](https://github.com/kubernetes/kubectl/pull/65)
in github.com/kubernetes/kubectl
* Aug 2017: [DAM] authored by Brian Grant
[DAM]: https://docs.google.com/document/d/1cLPGweVEYrVqQvBLJg6sxV-TrE5Rm2MNOBA_cxZP2WU

137
site/content/en/blog/releases/v2.0.0.md Normal file
View File

@@ -0,0 +1,137 @@
---
title: "v2.0.0"
linkTitle: "v2.0.0"
date: 2019-02-05
description: >
Kustomize v2.0.0
---
[security concern]: https://docs.google.com/document/d/1FYgLVdq-siB_Cef9yuQBmit0PbrE8lsyTBdGI2eA2y8/edit
After security review, a field used in secret
generation (see below) was removed from the
definition of a kustomization file with no
mechanism to convert it to a new form. Also, the
set of files accessible from a kustomization file
has been further constrained.
Per the [versioning policy](/kustomize/faq/versioningpolicy),
backward incompatible changes trigger an increment
of the major version number, hence we go
from 1.0.11 to 2.0.0. We're taking this major
version increment opportunity to remove some
already deprecated fields, and the code paths
associated with them.
## Backward Incompatible Changes
### Kustomization Path Constraints
A kustomization file can specify paths to other
files, including resources, patches, configmap
generation data, secret generation data and
bases. In the case of a base, the path can be a
git URL instead.
In 1.x, these paths had to be relative to the
current kustomization directory (the location of
the kustomization file used in the `build`
command).
In 2.0, bases can continue to specify, via
relative paths, kustomizations outside the current
kustomization directory. But non-base paths are
constrained to terminate in or below the current
kustomization directory. Further, bases specified
via a git URL may not reference files outside of
the directory used to clone the repository.
### Kustomization Field Removals
#### patches
`patches` was deprecated and replaced by
`patchesStrategicMerge` when `patchesJson6902` was
introduced. In Kustomize 2.0.0, `patches` is
removed. Please use `patchesStrategicMerge`
instead.
#### imageTags
`imageTags` is replaced by `images` since `images`
can provide more features to change image names,
registries, tags and digests.
#### secretGenerator/commands
`commands` is removed from SecretGenerator due to
a [security concern]. One can use `files` or
`literals`, similar to ConfigMapGenerator, to
generate a secret.
```
secretGenerator:
- name: app-tls
files:
- secret/tls.cert
- secret/tls.key
type: "kubernetes.io/tls"
```
## Compatible Changes (New Features)
As this release is triggered by a security change,
there are no major new features to announce. A few
things that are worth mentioning in this release
are:
* More than _40_ issues closed since 1.0.11
release (including many extensions to
transformation rules).
* Users can run `kustomize edit fix` to migrate a
kustomization file working with previous
versions to one working with 2.0.0. For example,
a kustomization.yaml with following content
```
patches:
- deployment-patch.yaml
imageTags:
- name: postgres
newTag: v1
```
will be converted to
```
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesStrategicMerge:
- deployment-patch.yaml
images:
- name: postgres
newTag: v1
```
* Kustomization filename
In previous versions, the name of a
kustomization file had to be
`kustomization.yaml`.
Kustomize allows `kustomization.yaml`,
`kustomization.yml` and
`Kustomization`. In a directory, only one of
those filenames is allowed. If there are more
than one found, Kustomize will exit with an
error. Please select the best filename for your
use cases.
* Cancelled plans to deprecate applying prefix/suffix to namespace.
The deprecation warning
```
Adding nameprefix and namesuffix to Namespace resource will be deprecated in next release.
```
was removed.

249
site/content/en/blog/releases/v2.1.0.md Normal file
View File

@@ -0,0 +1,249 @@
---
title: "v2.1.0"
linkTitle: "v2.1.0"
date: 2019-06-18
description: >
Kustomize v2.1.0
---
[Go modules]: https://github.com/golang/go/wiki/Modules
[generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md
[imgModules]: /kustomize/images/goModules.png
[imgPlugins]: /kustomize/images/plugins.png
[imgPruning]: /kustomize/images/pruning.png
[imgSorted]: /kustomize/images/sorted.png
[imgWheels]: /kustomize/images/abandonedTrainingWheels.png
[kustomization]: glossary#kustomization
[_kustomization_]: /kustomize/api-reference/glossary#kustomization
[base]: /kustomize/api-reference/glossary#base
[bases]: /kustomize/api-reference/glossary#base
[_base_]: /kustomize/api-reference/glossary#base
[kustomize inventory object documentation]: https://github.com/kubernetes-sigs/kustomize/tree/master/docs/inventory_object.md
[kustomize plugin documentation]: plugins
[root]: /kustomize/api-reference/glossary#kustomization-root
[transformer configs]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs
[v1.0.9]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9
[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9releases/tag/v2.0.3
[v2.1.0]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v1.0.9releases/tag/v2.1.0
[versioning policy]: /kustomize/faq/versioningpolicy
Go modules, resource ordering respected, generator and transformer plugins, eased
loading restrictions, the notion of inventory, eased replica count modification.
About ~90 issues closed since [v2.0.3] in ~400 commits.
Download [here][v2.1.0].
## Go modules
![gopher with boxes][imgModules]
Kustomize now defines its dependencies in a top
level `go.mod` file. This is the first step
towards a package structure intentially exported
as one or more [Go modules] for use in other
programs (kubectl, kubebuilder, etc.) and in
kustomize plugins (see below).
## Resource ordering
![sort order retained][imgSorted]
Kustomize now retains the depth-first order of
resources as read, a frequently requested
feature.
This means resource order can be controlled
by editting kustomization files. This is
also vital to applying user-defined
transformations (plugins) in a particular
order.
Nothing needs to be done to activate this;
it happens automatically.
The `build` command now accepts a `--reorder`
flag with values `legacy` and `none`,
with a default value of `legacy`.
`legacy` means apply an ordering based on
GVK, that currently emits `Namespace` objects
first, and `ValidatingWebhookConfiguration`
objects last. This means that despite
automatic retention of load order, your
`build` output won't change by default.
`none` means _don't_ reorder the resources before
output. Specify this to see output order
respect input order.
## Generator and transformer plugins
![kid putting knife in electrical outlet][imgPlugins]
Since the beginning (as `kinflate` back in Sep
2017), kustomize has read or generated resources,
applied a series of pipelined transformation to
them, and emitted the result to `stdout`.
At that time, the only way to change the behavior
of a generator (e.g. a secret generator), or
change the behavior of a transformer (e.g. a name
changer, or json patcher), was to modify source
code and put out a release.
[v1.0.9] introduced [generator options] as a means
to change the behavior of the only two generators
available at the time - Secret and ConfigMap
generators. It also introduced
[transformer configs] as a way to fine tune the
targets of transformations (e.g. to which fields
_selectors_ should be added). Most of the feature
requests for kustomize revolve around changing the
behavior of the builtin generators and
transformers.
[v2.1.0] adds an _alpha_ plugin framework, that
encourages users to write their own generators or
transformers, _declaring them as kubernetes
objects just like everything else_, and apply them
as part of the `kustomize build` process.
To inform the API exposed to plugins, and to
confirm that the plugin framework can offer plugin
authors the same capabilities as builtin
operations, all the builtin generators and
tranformers have been converted to plugin form
(with one exceptions awaiting Go module
refinements). This means that adding, say, a
`secretGenerator` or `commonAnnotations` directive
to your kustomization will (in [v2.1.0]) trigger
execution of
[code committed as a plugin](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin).
For more information, see the
[kustomize plugin documentation].
## Remove load restrictions
![removed training wheels][imgWheels]
The following usage:
```
kustomize build --load_restrictor none $target
```
allows a `kustomization.yaml` file used in this
build to refer to files outside its own directory
(i.e. outside its [root]).
This is an opt-in to suppress a security feature
that denies this precise behavior.
This feature should only be used to allow multiple
overlays (e.g. prod, staging and dev) to share a
patch file. To share _resources_, use a relative
path or URL to a kustomization directory in the
`resources` directive.
## Inventory generation for pruning
![pruning dead branches][imgPruning]
_Alpha_
Users can add an `inventory` stanza to their
kustomization file, to add a special _inventory
object_ to the `build` result.
This object applies to the cluster along with
everything else in the build result and can be
used by other clients to intelligently _prune_
orphaned cluster resources.
For more information see the
[kustomize inventory object documentation].
## Field changes / deprecations
### `resources` expanded, `bases` deprecated
The `resources` field has been generalized; it now
accepts what formerly could only be specified in
the `bases` field.
This change was made to allow users fine control
over resource processing order. With a distinct
`bases` field, bases had to be loaded separately
from resources as a group. Now, base loading may
be interleaved as desired with the loading of
resource files from the current
directory. [Resource ordering](#resource-ordering)
had to be respected before this feature could be
introduced.
The `bases` field is now deprecated, and will be
deleted in some future major release. Manage the
deprecation simply moving the arguments of the
`bases` field to the `resources` field in the
desired order, e.g.
> ```
> resources:
> - someResouceFile.yaml
> - someOtherResourceFile.yaml
> bases:
> - ../../someBaseDir
> ```
could become
> ```
> resources:
> - someResouceFile.yaml
> - ../../someBaseDir
> - someOtherResourceFile.yaml
> ```
The `kustomized edit fix` command will do this for
you, though it will always put the bases at the
end.
As an aside, the `resources`, `generators` and
`transformers` fields now all accept the same
argument format.
> Each field's argument is a _string list_,
> where each entry is either a _resource_ (a
> relative path to a YAML file) or a
> [_kustomization_] (a path or URL
> pointing to a directory with a kustomization
> file). A kustomization directory used in this
> context is called a [_base_].
The fact that the `generators` and `transformers`
field accept [bases] and the fact that generator
and transformer configuration objects are just
normal k8s resources means that one can generate
or transform a generator or a transformer (see
[TestTransformerTransformers]).
[TestTransformerTransformers]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/internal/target/transformerplugin_test.go
### `replicas` field
The common task of patching a deployment to edit
the number of replicas is now made easier
with the new [replicas](/kustomize/api-reference/kustomization/replicas) field.
### `envs` field
An `envs` sub-field has been added to both
`configMapGenerator` and `secretGenerator`,
replacing the now deprecated (and singular)
`env` field. The new field accepts lists, just
like its sibling fields `files` and `literals`.
Optionally use `kustomize edit fix` to merge
singular `env` field into a plural field.

75
site/content/en/blog/releases/v3.0.0.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: "v3.0.0"
linkTitle: "v3.0.0"
date: 2019-07-03
description: >
Kustomize v3.0.0
---
This release is basically [v2.1.0](v2.1.0.md),
with many post-v2.1.0 bugs fixed (in about 150
commits) and a `v3` in Go package paths.
[plugin]: /docs/plugins
The major version increment to `v3` puts a new
floor on a stable API for [plugin] developers
(both _Go_ plugin developers and _exec_ plugin
developers who happen to use Go).
### Why so soon after v2.1.0?
[semantic versioning]: https://semver.org
[Go modules doc]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
[versioning policy]: /kustomize/faq/versioningpolicy
We made a mistake - v2.1.0 should have been
v3.0.0. Per the [Go modules doc] (which have
improved a great deal recently), a release that's
already tagged v2 or higher should increment the
major version when performing their first Go
module-based release.
This advice applies to kustomize, since it was
already at major version 2 when it began using Go
modules to state _its own_ dependencies in v2.1.0.
But the more important reason for `v3` is a change
to the kustomize [versioning policy], forced by
the introduction of plugins.
Historically, kustomize's [versioning policy]
didn't involve Go modules and addressed _only_ the
command line tool's behavior and the fields in a
kustomization file. The underlying packages were
an implementation detail, not under semantic
versioning, because they weren't intended for
export (and should have all been under
`internal`). Thus although the v2.1.0 CLI is
backward compatible with v2.0.3, the underlying
package APIs are not.
[minimal version selection]: https://research.swtch.com/vgo-mvs
With Go modules, the `go` tool must assume that Go
packages respect [semantic versioning], so it can
perform [minimal version selection].
With the introduction of alpha plugins, kustomize
sub-packages - in particular `loader` and
`resmap` - become part of an API formally exposed
to plugin authors, and so must be semantically
versioned. This allows plugins defined in other
repositories to clarify that they depend on
kustomize v3.0.0, and not see confusing errors
arising from incompatibilities between v2.1.0 and
v2.0.3. Hence, the jump to v3.
Aside - the set of kustomize packages outside
`internal` is too large, and over time, informed
by package use, this API surface must shrink.
Such shrinkage will trigger a major version
increment.

132
site/content/en/blog/releases/v3.1.0.md Normal file
View File

@@ -0,0 +1,132 @@
---
title: "v3.1.0"
linkTitle: "v3.1.0"
date: 2019-07-26
description: >
Kustomize v3.1.0
---
## Extended patches
Since this version, Kustomize allows applying one patch to multiple resources. This works for both Strategic Merge Patch and JSON Patch. Take a look at [patch multiple objects](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/patchMultipleObjects.md).
## Improved Resource Matching
Multiple improvements have been made to allow the user to leverage "namespace"
instead/or with "name suffix/prefix" to segregate resources.
### Patch resolution improvement
The following example demonstrates how using the namespace field in the patch definition,
will let the user define two different patches against two different Deployment having the
same "deploy1" name but in different namespaces in the same Kustomize context/folder.
Unless the `namespace:` field has been specified in the kustomization.yaml, no namespace
value will be handled as Kubernetes `default` namespace.
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: deploy1
namespace: main
spec:
template:
spec:
containers:
- name: nginx
env:
- name: ANOTHERENV
value: TESTVALUE
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: deploy1
namespace: production
spec:
template:
spec:
containers:
- name: main
env:
- name: ANOTHERENV
value: PRODVALUE
```
### Variable resolution improvement
It is possible to add namespace field to the variable declaration. In the following example,
two `Service` objects with the same `elasticsearch` name have been declared.
Specifying the namespace in the objRef of the corresponding varriables, allows Kustomize to
resovlve thoses variables.
If the namespace is not specified, Kustomize will handle it has a "wildcard" value.
Extract of kustomization.yaml:
```yaml
vars:
- name: elasticsearch-test-protocol
objref:
kind: Service
name: elasticsearch
namespace: test
apiVersion: v1
fieldref:
fieldpath: spec.ports[0].protocol
- name: elasticsearch-dev-protocol
objref:
kind: Service
name: elasticsearch
namespace: dev
apiVersion: v1
fieldref:
fieldpath: spec.ports[0].protocol
```
### Simultaneous change of names and namespaces
Kustomize is now able to deal with simultaneous changes of name and namespace.
Special attention has been paid the handling of:
- ClusterRoleBinding/RoleBinding "subjects" field,
- ValidatingWebhookConfiguration "webhooks" field.
The user should be able to use a kustomization.yaml as shown in the example bellow
even if ClusterRoleBind,RoleBinding and ValidatingWebookConfiguration are part of the
resources he needs to declare.
Extract of kustomization.yaml:
```yaml
namePrefix: pfx-
nameSuffix: -sfx
namespace: testnamespace
resources:
...
```
### Resource and Kustomize Context matching.
Kustomize is now able to support more aggregation patterns.
If for instance, the top level of kustomization.yaml, is simply
combining sub-components, (as in the following example), Kustomize has improved
resource matching capabilities. This removes some of the constraints which were
present on the utilization of prefix/suffix and namespace transformers in the
individual components.
```yaml
resources:
- ../component1
- ../component2
- ../component3
```
## Other improvements
- Image transformation has been improved. This allows the user to update the sha256 of
an image with another sha256.
- Multiple default transformer configuration entries have been added, removing the need for the
user to add them as part of the `configurations:` section of the kustomization.yaml.
- `kustomize` help command has been tidied up.

34
site/content/en/blog/releases/v3.2.0.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: "v3.2.0"
linkTitle: "v3.2.0"
date: 2019-09-17
description: >
Kustomize v3.2.0
---
## Inline Patch
Since this version, Kustomize allows inline patches in all three of `patchesStrategicMerge`, `patchesJson6902` and `patches`. Take a look at [inline patch](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/examples/inlinePatch.md).
## New Subcommand
Since this version, one can create a kustomization.yaml file in a directory through a `create` subcommand.
Create a new overlay from the base ../base
```
kustomize create --resources ../base
```
Create a new kustomization detecing resources in the current directory
```
kustomize create --autodetect
```
Once can also add all resources in the current directory recursively by
```
kustomize create --autodetect --recursive
```
### New Example Generator
A new example generator of using go-getter to download resources is added. Take a look at [go-getter generator](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/goGetterGeneratorPlugin.md).

19
site/content/en/blog/releases/v3.2.1.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: "v3.2.1"
linkTitle: "v3.2.1"
date: 2019-09-26
description: >
Kustomize v3.2.1
---
This is a patch release, with no new features from 3.2.0.
It reflects a change in dependence.
The kustomize binary is now built as a client, with no special
consideration, of the set of public packages represented by the Go
module at [https://github.com/kubernetes-sigs/kustomize].
kustomize the binary is now a client of the kustomize API
represented by the public package surface presented by
`https://github.com/kubernetes-sigs/kustomize/v{whatever}`

121
site/content/en/blog/releases/v3.3.0.md Normal file
View File

@@ -0,0 +1,121 @@
---
title: "v3.3.0"
linkTitle: "v3.3.0"
date: 2019-10-24
description: >
Kustomize v3.3.0
---
[versioning policy documentation]: /site/content/en/faq/versioningPolicy.md
[release process documentation]: /releasing
## Summary of changes
### First release of the Go API-only module.
Many of the PRs since the last vrelease were
around restructuring the _sigs.k8s.io/kustomize_
repository into three Go modules instead of just one.
The reasons for this are detailed in the [versioning
policy documentation], and what it means for releasing
is explained in the [release process documentation].
The tl;dr is that the top level module
`sigs.k8s.io/kustomize` now defines the kustomize Go
API, and the _kustomize_ CLI sits below it in an
independent module `sigs.k8s.io/kustomize/kustomize`.
The modules release independently, though in practice a
new release of the kustomize Go API will likely be
followed quickly by a new release of the `kustomize`
executable.
This is a necessary step to creating a much smaller
kustomize Go API surface that has some hope of
conforming to semantic versioning and being of some use
to clients.
The kustomize CLI will see the same kustomize Go API as
any other client.
The new semver-able API will begin with `v4.0.0` (not
yet released) and be a clean break with `v3` etc.
### Change log since v3.2.0
```
3c9d828f - Have kustomize CLI depend on kustomize Go API v3.3.0 (Jeffrey Regan)
5d800f0b - Merge pull request #1595 from monopole/threeReleases (Jeff Regan)
4eb2d5bc - Three builders. (Jeffrey Regan)
988af1ff - Update README.md (Jeff Regan)
1617183e - Merge pull request #1590 from monopole/releaseProcessUpdate (Kubernetes Prow Robot)
ee727464 - update release process doc (jregan)
c9e7dc3b - Merge pull request #1589 from monopole/moreTestsAroundKustFileName (Jeff Regan)
07e0e46a - improve tests for alternative kustomization file names (Jeffrey Regan)
404d2d63 - Merge pull request #1587 from monopole/reducePgmconfig (Jeff Regan)
baa0296a - Reduce size of pgmconfig package (Jeffrey Regan)
0f665ac1 - Merge pull request #1544 from ptux/add-transformer-href (Jeff Regan)
14b0a650 - Merge pull request #1581 from monopole/refactorFs (Jeff Regan)
2d58f8b8 - Break the dep between fs and pgmconfig. (Jeffrey Regan)
9a43ca53 - Merge pull request #1578 from nlamirault/fix/build-plugins-doc (Jeff Regan)
5372fc6f - Merge pull request #1579 from monopole/fsPackageCleanup (Jeff Regan)
86bc3440 - Merge pull request #1513 from nimohunter/fix_empty_list_item (Kubernetes Prow Robot)
a014f7d4 - Merge pull request #1561 from beautytiger/dev-190925 (Jeff Regan)
9a94bcb8 - Improve fs package and doc in prep to officially go public (Jeffrey Regan)
07634ef0 - Merge pull request #1575 from monopole/versioning (Jeff Regan)
995f88d6 - Update versioning notes. (jregan)
334a6467 - Fix: documentation link for plugins (Nicolas Lamirault)
08963ba5 - improve test code coverage in transformers (Guangming Wang)
326fb689 - Merge pull request #1570 from bzub/1234-go_plugin_doc (Jeff Regan)
970ce67c - Update goPluginCaveats.md (Jeff Regan)
98d18930 - Update INSTALL.md (Jeff Regan)
d89b448c - Fix git tag recovery in cloud build. (Jeff Regan)
17bf9d32 - Update releasing README. (Jeff Regan)
a99aff1d - Merge pull request #1571 from monopole/updateCloudBuildProcess (Kubernetes Prow Robot)
a694ac7b - Update cloud build process for kustomize. (Jeffrey Regan)
b5b11ef6 - Fix compile kustomize example. (bzub)
fa1af6f5 - Merge pull request #1473 from richardmarshall/execpluginhash (Jeff Regan)
9288dec0 - Fix failing BashedConfigMapTest (Jeff Regan)
1a45dd0b - Merge pull request #1566 from monopole/releaseNotes3.2.1 (Kubernetes Prow Robot)
592c5acf - docs: Exec plugin generator options (Richard Marshall)
ac9424fa - tests: Add unit tests for update resource options (Richard Marshall)
79fbe7c4 - Support resource generator options in exec plugins (Richard Marshall)
f69d526f - v3.2.1 release notes (Jeff Regan)
07a95a60 - Merge pull request #1565 from monopole/tweakBinaryDepsBeforeTagging (Jeff Regan)
032b3857 - Pin the kustomize binary's dependence on kustomize libs. (jregan)
81062959 - Merge pull request #1564 from monopole/moveKustomizeBinaryToOwnModule (Kubernetes Prow Robot)
b82a8fd3 - Move the kustomize binary to its own module. (Jeffrey Regan)
2d0c22d6 - Merge pull request #1562 from keleustes/tools (Kubernetes Prow Robot)
aa342def - Pin tool versions using go modules (Ian Howell)
10786ec0 - Merge pull request #1554 from keleustes/readme (Kubernetes Prow Robot)
7c705687 - Update README.md to include Kubernetes 1.16 (Jerome Brette)
e8933d97 - Merge pull request #1560 from monopole/precommitTuneup (Jeff Regan)
9d7b6544 - Make pre-commit more portable and less tricky. (jregan)
7a0946a9 - Merge pull request #1558 from monopole/dependOnNewPluginatorModule (Jeff Regan)
def4f045 - Depend on new pluginator location. (Jeffrey Regan)
2f2408f1 - Merge pull request #1559 from monopole/compressCopyright (Jeff Regan)
3b9bcc48 - Compress copyright in the commands package. (Jeffrey Regan)
d0429ff4 - Merge pull request #1557 from monopole/pluginatorModule (Jeff Regan)
33deefc3 - Copy pluginator to its own module. (Jeffrey Regan)
9b3de82b - Merge pull request #1506 from Liujingfang1/release (Jeff Regan)
d217074f - Merge pull request #1550 from keleustes/apiversion (Kubernetes Prow Robot)
1d90ba7c - Fix typo in apiVersion yaml declaration (Jerome Brette)
eeeb4c36 - Merge pull request #1547 from keleustes/extensions (Kubernetes Prow Robot)
b1faa989 - Update Ingress apiVersion to networking.k8s.io/v1beta1 (Jerome Brette)
d8250c9e - move test case (nimohunter)
c9500466 - add transformer href (Wang(わん))
0c32691e - Merge pull request #1537 from jaypipes/gomod-install-note (Kubernetes Prow Robot)
88b1d627 - Merge pull request #1541 from rtnpro/patch-1 (Jeff Regan)
aec82066 - Update INSTALL.md (Jeff Regan)
20c2b53a - Merge pull request #1542 from monopole/tweakFilePathsInTest (Jeff Regan)
274b5c3b - Tweak file path handling and logging in test. (Jeffrey Regan)
b1fdaa23 - Fix typo in transformerconfigs README (Ratnadeep Debnath)
b5d5e70b - empty list or map item return error (nimohunter)
2e829853 - empty list or map item return error (nimohunter)
55941f57 - add note about GO111MODULE for source install (Jay Pipes)
9e226001 - empty list or map item return error (nimohunter)
77b63f96 - add release note for v3.2.0 (jingfangliu)
```

10
site/content/en/contributing/_index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: "Contributing"
linkTitle: "Contributing"
type: docs
menu:
main:
weight: 99
---
Follow are resources for Kustomize contributors.

57
site/content/en/contributing/bugs/_index.md Normal file
View File

@@ -0,0 +1,57 @@
---
title: "Filing Bugs"
linkTitle: "Filing Bugs"
type: docs
weight: 10
description: >
How to file bugs against Kustomize
---
[krusty package]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty
[reusable custom transformer test]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty/customconfigreusable_test.go
File issues as desired, but if you've found a problem
with how `kustomize build` works, please report
* the output of `kustomize version`,
* the input (the content of `kustomization.yaml`
and any files it refers to),
* the expected YAML output.
## If you have `go` installed
kustomize has a simple test harness in the [krusty
package] for specifying a kustomization's input and the
expected output.
Copy one of those tests, e.g. this [reusable custom
transformer test], to a new test file in the
krusty package.
Insert the inputs you want to use, and run it as
you'd run the reusable custom transformer test:
```
(cd api; go test -run TestReusableCustomTransformers ./krusty)
```
The output will demonstrate the bug or missing feature.
Record this output in the test file in a call to
`AssertActualEqualsExpected`, per all the other tests
in the [krusty package]. This makes the test pass,
albeit with output demonstrating behavior you
presumably want to change.
Send the new test in a PR, along with commentary (in
the test) on what you'd prefer to see.
The person who fixes the bug then has a clear bug
reproduction and a test to modify when the bug is
fixed.
Any bug fix first requires a test demonstrating the bug
(so we have permanent regression coverage), so if the
_bug reporter_ does this, it saves time and avoids
misunderstandings.

22
site/content/en/contributing/community/_index.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: "Community Engagment"
linkTitle: "Community"
type: docs
weight: 20
description: >
Joining SIG-CLI and the Kubernetes community
---
[CLI special interest group]: https://github.com/kubernetes/community/tree/master/sig-cli#cli-special-interest-group
[contributor roles]: https://github.com/kubernetes/community/blob/master/community-membership.md#community-membership
[mailing list]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli
[bi-weekly meetings]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit?usp=sharing
Kustomize is a sub project of the Kubernetes [CLI special interest group] and follows the Kubernetes
project [contributor roles].
If you are interested in contributing towards Kustomize or getting more involved with the community,
reach out on the [mailing list] or join one of the [bi-weekly meetings] (alternating Wednesdays at
9:00am Pacific Time).

62
site/content/en/contributing/docs/_index.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: "Writing Docs"
linkTitle: "Writing Docs"
type: docs
weight: 30
description: >
How to make Kustomize docs contributions
---
Kustomize uses [Docsy](https://www.docsy.dev) for the site, and was
forked from the [docsy-example](https://github.com/google/docsy-example)
## Prerequisites
- [Install hugo](https://gohugo.io/getting-started/installing/#fetch-from-github)
- Clone kustomize
- `git clone git@github.com:kubernetes-sigs/kustomize && cd kustomize/`
## Development
The docs are in the `site` directory
```shell script
cd site/
```
To view the docs run
```shell script
hugo serve
```
```shell script
...
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/kustomize/ (bind address 127.0.0.1)
```
and visit the URL that is printed
## Publishing
The `site` content is compiled by Hugo into the `docs` folder using the hugo command:
```shell script
hugo
```
```shell script
| EN
-------------------+-----
Pages | 99
Paginator pages | 0
Non-page files | 0
Static files | 47
Processed images | 0
Aliases | 2
Sitemaps | 1
Cleaned | 0
```
Add the `site` and `docs` folders to a commit, and create a PR.

57
site/content/en/contributing/howitworks/_index.md Normal file
View File

@@ -0,0 +1,57 @@
---
title: "Writing Code"
linkTitle: "Writing Code"
type: docs
weight: 40
description: >
How Kustomize is implemented
---
Call stack when running `kustomize build`, with links to code.
## Run build
* [RunBuild](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L121)
* [MakeKustomizer](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L32)
* [Run](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L47): performs a kustomization. It uses its internal filesystem reference to read the file at the given path argument, interpret it as a kustomization.yaml file, perform the kustomization it represents, and return the resulting resources.
* Create factories
* [tranformer.NewFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/k8sdeps/transformer/factory.go#L17)
* [resmap.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resmap/factory.go#L21)
* [resource.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resource/factory.go#L23)
* [kustruct.NewKunstructuredFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/kunstruct/factory.go#L28)
* [loader.NewLoader](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/loader/loader.go#L19)
* [validator.NewKustValidator](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/validator/validators.go#L23)
* [NewKustTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L38)
* [Load](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L54)
* [MakeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L109): details in next section
* [emitResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L143)
## Make resource map
* [makeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L117)
* [AccumulateTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L196): returns a new ResAccumulator, holding customized resources and the data/rules used to do so. The name back references and vars are not yet fixed.
* [accummulateResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L302): fills the given resourceAccumulator with resources read from the given list of paths.
* Merge config from builtin and CRDs
* [runGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L239)
* [configureBuiltinGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L28)
* ConfigMapGenerator
* SecretGenerator
* [configureExternalGenerators]()
* Iterate all generators
* [runTransfomers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L274)
* [configureBuiltinTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L44)
* PatchStrategicMergeTransformer
* PatchTransformer
* NamespaceTransformer
* PrefixSuffixTransformer
* LabelTransformer
* AnnotationsTransformer
* PatchJson6902Transformer
* ReplicaCountTransformer
* ImageTagTransformer
* [configureExternalTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L291)
* [MergeVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L64)
* The following steps must be done last, not as part of the recursion implicit in AccumulateTarget.
* [addHashesToNames](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L153)
* [FixBackReferences](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L160): Given that names have changed (prefixs/suffixes added), fix all the back references to those names.
* [ResolveVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L141)

46
site/content/en/contributing/mac/_index.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: "MacOS Dev Guide"
linkTitle: "MacOS Dev Guide"
type: docs
weight: 50
description: >
How to develop on MacOS
---
First install the tools to build and run tests
### Install go 1.13
[Instructions](https://golang.org/doc/install)
Add `go` to your PATH
### Install kubeval
[Instructions](https://github.com/instrumenta/kubeval)
```sh
go get github.com/instrumenta/kubeval
```
Add `kubeval` to your PATH
### Install gnu tools
[Instructions](https://www.topbug.net/blog/2013/04/14/install-and-use-gnu-command-line-tools-in-mac-os-x/)
```sh
brew install coreutils wget gnu-sed tree
```
Add the new tools to your PATH
## Make everything
Verify your install by running `make`:
```sh
make
```
Be default, this runs all tests needed to qualify a pull request.

61
site/content/en/contributing/windows/_index.md Normal file
View File

@@ -0,0 +1,61 @@
---
title: "Windows Dev Guide"
linkTitle: "Windows Dev Guide"
type: docs
weight: 60
description: >
How to develop on Windows
---
This is the PowerShell script to run all go tests for Kustomize on a windows based platform which mimics /build/pre-commit.sh
## Pre-Reqs:
- PowerShell installed
- PowerShell Core is supported
- go installed
- golangci-lint installed
- mdrip installed
This script should output to the current console and return an exit code if all tests are successful(0) or any failed(1).
### If you are tryin to run these tests locally you can follow these instructions.
Assume:
- Running a stock Windows 10 system
- Local Admin rights.
- You can open [PowerShell as administrator](http://lmgtfy.com/?iie=1&q=How+to+open+powershell+as+administrator)
- You should be knowledgeable enough to pull source for packages into your GO ```src``` directory
- Yes, this means you also need to know a bit about **git** usually
#### Step 1 - Install Go
- [Install Go](https://golang.org/dl/) - please use the msi
- If you use chocolatey - it's using the zip not msi and assumptions on where go is located are made for you.
#### Step 2 - Install Go Packages
- Open new PowerShell Administrative window
- Install golangci-lint
- ```go get -u github.com/golangci/golangci-lint/cmd/golangci-lint```
- Install mdrip
- ```go get github.com/monopole/mdrip```
You should now be able to issue these commands and see comparable responses
```
C:\...> golangci-lint --help
Smart, fast linters runner. Run it in cloud for every GitHub pull request on https://golangci.com
...
C:\...> mdrip --help
Usage: C:\_go\bin\mdrip.exe {fileName}...
...
```
#### Step 3 - Get Source and Test
- In your GoRoot src
- ```Example: C:\_go\src```
- Navigate to the Kustomize `travis` directory
- ```Example: C:\_go\src\sigs.k8s.io\kustomize\travis```
- Now Execute:
- ```.\Invoke-PreCommit.ps1```
This should run all pre-commit tests thus defined in the script.

65
site/content/en/faq/_index.md Normal file
View File

@@ -0,0 +1,65 @@
---
title: "FAQ"
linkTitle: "FAQ"
type: docs
menu:
main:
weight: 70
---
## security: file 'foo' is not in or below 'bar'
v2.0 added a security check that prevents
kustomizations from reading files outside their own
directory root.
This was meant to help protect the person inclined to
download kustomization directories from the web and use
them without inspection to control their production
cluster
(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693),
[#700](https://github.com/kubernetes-sigs/kustomize/pull/700),
[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and
[#998](https://github.com/kubernetes-sigs/kustomize/pull/998))
Resources (including configmap and secret generators)
can _still be shared_ via the recommended best practice
of placing them in a directory with their own
kustomization file, and referring to this directory as a
[`base`](/kustomize/api-reference/glossary#base) from any kustomization that
wants to use it. This encourages modularity and
relocatability.
To disable this, use v3, and the `load_restrictor` flag:
```
kustomize build --load_restrictor none $target
```
## Some field is not transformed by kustomize
Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc.
The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g.
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configurations:
- kustomizeconfig.yaml
```
The configuration directive allows customization of the following transformers:
```yaml
commonAnnotations: []
commonLabels: []
nameprefix: []
namespace: []
varreference: []
namereference: []
images: []
replicas: []
```
To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc.

163
site/content/en/faq/eschewedfeatures/_index.md Normal file
View File

@@ -0,0 +1,163 @@
---
title: "Eschewed Features"
linkTitle: "Eschewed Features"
type: docs
weight: 99
description: >
Eschewed Features
---
The maintainers established this list to
place bounds on the kustomize feature
set. The bounds can be changed with
a consensus on the risks.
For a bigger picture about why kustomize
does some things and not others, see the
glossary entry for [DAM].
## Removal directives
`kustomize` supports configurations that can be reasoned about as
_compositions_ or _mixins_ - concepts that are widely accepted as
a best practice in various programming languages.
To this end, `kustomize` offers various _addition_ directives.
One may add labels, annotations, patches, resources, bases, etc.
Corresponding _removal_ directives are not offered.
Removal semantics would introduce many possibilities for
inconsistency, and the need to add code to detect, report and
reject it. It would also allow, and possibly encourage,
unnecessarily complex configuration layouts.
When faced with a situation where removal is desirable, it's
always possible to remove things from a base like labels and
annotations, and/or split multi-resource manifests into individual
resource files - then add things back as desired via the
[kustomization].
If the underlying base is outside of one's control, an [OTS
workflow] is the recommended best practice. Fork the base, remove
what you don't want and commit it to your private fork, then use
kustomize on your fork. As often as desired, use _git rebase_ to
capture improvements from the upstream base.
## Unstructured edits
_Structured edits_ are changes controlled by
knowledge of the k8s API, and YAML or JSON syntax.
Most edits performed by kustomize can be expressed as
[JSON patches] or [SMP patches].
Those can be verbose, so common patches,
like adding labels or annotatations, get dedicated
transformer plugins - `LabelTransformer`,
`AnnotationsTransformer`, etc.
These accept relatively simple YAML configuration
allowing easy targeting of any number of resources.
Another class of edits take data from one specific
object's field and use it in another (e.g. a service
object's name found and copied into a container's
command line). These reflection-style edits
are called _replacements_.
The above edits create valid output given valid input,
and can provide syntactically and semantically
informed error messages if inputs are invalid.
_Unstructured edits_, edits that don't limit
themselves to a syntax or object structure,
come in many forms. A common one in the
configuration domain is the template or
parameterization approach.
In this technique, the source
material is sprinkled with strings of the
form `${VAR}`. A scanner replaces them
with a value taken from a map using `VAR`
as the map key. It's trivial to implement.
kustomize eschews parameterization, because
- The source yaml gets polluted with `$VARs`
and can no longed be applied as is
to the cluster (it _must_ be processed).
- The source material is no longer structured,
making it unusable with any YAML processor.
It's no longer _data_, it's now logic that
must be compiled.
- Errors in the output are disconnected from
the edit that caused it.
- The input becomes [unintelligible] as the project
scales in any number of dimensions (resource
count, cluster count, environment count, etc.)
Kustomizations are meant to be sharable and stackable.
Imagine tracing down a problem rooted in a
clever set of stacked regexp replacements
performed by various overlays on some remote base.
We've used such systems, and never want to again.
Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet,
etc.) provide varying degrees of unstructured editting
and/or embedded languages, and can be used instead
of, or in a pipe with, kustomize. If you want to
go all-in on _configuration as a language_, consider [cue].
kustomize is going to stick to YAML in / YAML out.
## Build-time side effects from CLI args or env variables
`kustomize` supports the best practice of storing one's
entire configuration in a version control system.
Changing `kustomize build` configuration output as a result
of additional arguments or flags to `build`, or by
consulting shell environment variable values in `build`
code, would frustrate that goal.
`kustomize` insteads offers [kustomization] file `edit`
commands. Like any shell command, they can accept
environment variable arguments.
For example, to set the tag used on an image to match an
environment variable, run
```
kustomize edit set image nginx:$MY_NGINX_VERSION
```
as part of some encapsulating work flow executed before
`kustomize build`.
## Globs in kustomization files
`kustomize` supports the best practice of storing one's
entire configuration in a version control system.
Globbing the local file system for files not explicitly
declared in the [kustomization] file at `kustomize build` time
would violate that goal.
Allowing globbing in a kustomization file would also introduce
the same problems as allowing globbing in [java import]
declarations or BUILD/Makefile dependency rules.
`kustomize` will instead provide kustomization file editting
commands that accept globbed arguments, expand them at _edit
time_ relative to the local file system, and store the resulting
explicit names into the kustomization file.
[base]: /kustomize/api-reference/glossary#base
[DAM]: /kustomize/api-reference/glossary#declarative-application-management
[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards
[JSON patches]: /kustomize/api-reference/glossary#patchjson6902
[kustomization]: /kustomize/api-reference/glossary#kustomization
[OTS workflow]: /kustomize/api-reference/glossary#off-the-shelf-configuration
[SMP patches]: /kustomize/api-reference/glossary#patchstrategicmerge
[parameterization pitfall discussion]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#parameterization-pitfalls
[unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml
[cue]: https://cuelang.org/

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

@@ -0,0 +1,272 @@
---
title: "Versioning Policy"
linkTitle: "Versioning Policy"
weight: 99
type: docs
---
Running `kustomize` means one is running a
particular version of a program (a CLI), using a
particular version of underlying packages (a Go
API), and reading a particular version of a
[kustomization] file.
> If you're having trouble with `go get`, please
> read [Go API Versioning](#go-api-versioning)
> and be patient.
## CLI Program Versioning
The command `kustomize version` prints a three
field version tag (e.g. `v3.0.0`) that aspires to
[semantic versioning].
This notion of semver applies only to the CLI;
the command names, their arguments and their flags.
The major version changes when some backward
incompatibility appears in how the commands
behave.
### Installation
See the [installation docs](INSTALL.md).
## Go API Versioning
The public methods in the public packages
of module `sigs.k8s.io/kustomize/api` constitute
the _kustomize Go API_.
#### Version sigs.k8s.io/kustomize/v3 and earlier
[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher
In `kustomize/v3` (and preceding major versions), the
kustomize program and the API live the same Go
module at `sigs.k8s.io/kustomize`, at [import path]
`sigs.k8s.io/kustomize/v3`.
This has been fine for the CLI, but it presents a
problem for the Go API.
[minimal version selection]: https://research.swtch.com/vgo-mvs
The process around Go modules, in particular the
notion of [minimal version selection], demands
that the module respect semver.
Almost all the code in module
`sigs.k8s.io/kustomize/v3` is exposed (not in a
directory named `internal`). Even a minor
refactor changing a method name or argument type
in some deeply buried (but still public) method is
a backward incompatible change. As a result, Go
API semver hasn't been followed. This was a mistake.
Some options are
- continue to ignore Go API semver and stick to
CLI semver (eliminating the usefullness of
minimal version selection),
- obey semver, and increment the module's major
version number with every release (drastically
reducing the usefullness of minimal version
selection - since virtually all releases will
be major),
- slow down change in the huge API in favor of
stability, yet somehow continue to deliver
features,
- drastically reduce the API surface, stabilize on
semver there, and refactor as needed inside
`internal`.
The last option seems the most appealing.
#### The first stable API version is coming
The first stable API version will launch
as the Go module
```
sigs.k8s.io/kustomize/api
```
The _kustomize_ program itself (`main.go`
and CLI specific code) will have moved out of
`sigs.k8s.io/kustomize` and into the new module
`sigs.k8s.io/kustomize/kustomize`. This is a
submodule in the same repo, and it will retain its
current notion of semver (e.g. a backward
incompatible change in command behavior will
trigger a major version bump). This module will
not export packages; it's just home to a `main`
package.
The `sigs.k8s.io/kustomize/api` module will
obey semver with a sustainable public
surface, informed by current usage. Clients
should import packages from this module, i.e.
from import paths prefixed by
`sigs.k8s.io/kustomize/api/` at first,
and later by `sigs.k8s.io/kustomize/api/v2/`.
The kustomize binary
itself is an API client requiring this module.
The clients and API will evolve independently.
## Kustomization File Versioning
The kustomization file is a struct that is part of
the kustomize Go API (the `sigs.k8s.io/kustomize`
module), but it also evolves as a k8s API object -
it has an `apiVersion` field containing its
own version number.
### Field Change Policy
- A field's meaning cannot be changed.
- A field may be deprecated, then removed.
- Deprecation means triggering a _minor_ (semver)
version bump in the kustomize Go API, and
defining a migration path in a non-fatal error
message.
- Removal means triggering a _major_ (semver)
version bump in the kustomize Go API, and fatal
error if field encountered (as with any unknown
field). Likewise a change in `apiVersion`.
### The `edit fix` Command
This `kustomize` command reads a Kustomization
file, converts deprecated fields to new
fields, and writes it out again in the latest
format.
This is a type version upgrade mechanism that
works within _major_ API revisions. There is no
downgrade capability, as there's no use case for
it (see discussion below).
### Examples
With the 2.0.0 release, there were three field
removals:
- `imageTag` was deprecated when `images` was
introduced, because the latter offers more
general features for image data manipulation.
`imageTag` was removed in v2.0.0.
- `patches` was deprecated and replaced by
`patchesStrategicMerge` when `patchesJson6902`
was introduced, to make a clearer
distinction between patch specification formats.
`patches` was removed in v2.0.0.
- `secretGenerator/commands` was removed
due to security concerns in v2.0.0
with no deprecation period.
The `edit fix` command in a v2.0.x binary
will no longer recognize these fields.
## Relationship to the k8s API
### Review of k8s API versioning
The k8s API has specific [conventions] and a
process for making [changes].
The presence of an `apiVersion` field in a k8s
native type signals:
- its reliability level (alpha vs beta vs
generally available),
- the existence of code to provide default values
to fields not present in a serialization,
- the existence of code to provide both forward
and backward conversion between different
versions of types.
The k8s API promises a lossless _conversion_
between versions over a specific range. This
means that a recent client can write an object
bearing the newest possible value for its version,
the server will accept it and store it in
"versionless" JSON form in storage, and can
convert it to a range of older versions should
an older client request data.
For native k8s types, this all requires writing Go
code in the kubernetes core repo, to provide
defaulting and conversions.
For CRDs, there's a [proposal] on how to manage
versioning (e.g. a remote service can offer type
defaulting and conversions).
### Differences
- A k8s API server is able to go _forward_ and
_backward_ in versioning, to work with older
clients, over [some range].
- The `kustomize edit fix` command only moves
_forward_ within a _major_ API
version.
At the time of writing, the YAML in a
kustomization file does not represent a [k8s API]
object, and the kustomize command and associated
library is neither a server of, nor a client to,
the k8s API.
### Additional Kustomization file rules
In addition to the [field change policy] described
above, kustomization files conform to
the following rules.
#### Eschew classic k8s fields
Field names with dedicated meaning in k8s
(`metadata`, `spec`, `status`, etc.) aren't used.
This is enforced via code review.
#### Default values for k8s `kind` and `apiVersion`
In `v3` or below, the two [special] k8s
resource fields [`kind`] and [`apiVersion`] may
be omitted from the kustomization file.
If either field is present, they both must be.
If present, the value of `kind` must be:
> ```
> kind: Kustomization
> ```
If missing, the value of `apiVersion` defaults to
> ```
> apiVersion: kustomize.config.k8s.io/v1beta1
> ```
[field change policy]: #field-change-policy
[some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy
[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md
[beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions
[changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md
[adapt]: /types/kustomization.go#L166
[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources
[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
[release page]: https://github.com/kubernetes-sigs/kustomize/releases
[release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md
[kustomization]: /kustomize/api-reference/glossary#kustomization
[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds
[`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning
[semantic versioning]: https://semver.org

11
site/content/en/guides/_index.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: "Guides"
linkTitle: "Guides"
type: docs
weight: 2
menu:
main:
weight: 20
description: >
Reference for Kustomize CLI commands
---

81
site/content/en/guides/bespoke/_index.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: "Bespoke Application"
linkTitle: "Bespoke Application"
type: docs
weight: 1
description: >
Workflow for bespoke applications
---
In this workflow, all configuration (resource YAML) files are owned by the user.
No content is incorporated from version control repositories owned by others.
![bespoke config workflow image][workflowBespoke]
#### 1) create a directory in version control
Speculate some overall cluster application called _ldap_;
we want to keep its configuration in its own repo.
> ```
> git init ~/ldap
> ```
#### 2) create a [base]
> ```
> mkdir -p ~/ldap/base
> ```
In this directory, create and commit a [kustomization]
file and a set of [resources].
#### 3) create [overlays]
> ```
> mkdir -p ~/ldap/overlays/staging
> mkdir -p ~/ldap/overlays/production
> ```
Each of these directories needs a [kustomization]
file and one or more [patches].
The _staging_ directory might get a patch
that turns on an experiment flag in a configmap.
The _production_ directory might get a patch
that increases the replica count in a deployment
specified in the base.
#### 4) bring up [variants]
Run kustomize, and pipe the output to [apply].
> ```
> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
> kustomize build ~/ldap/overlays/production | kubectl apply -f -
> ```
You can also use [kubectl-v1.14.0] to apply your [variants].
> ```
> kubectl apply -k ~/ldap/overlays/staging
> kubectl apply -k ~/ldap/overlays/production
> ```
[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration
[apply]: /kustomize/api-reference/glossary#apply
[applying]: /kustomize/api-reference/glossary#apply
[base]: /kustomize/api-reference/glossary#base
[fork]: https://guides.github.com/activities/forking/
[variants]: /kustomize/api-reference/glossary#variant
[kustomization]: /kustomize/api-reference/glossary#kustomization
[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration
[overlays]: /kustomize/api-reference/glossary#overlay
[patch]: /kustomize/api-reference/glossary#patch
[patches]: /kustomize/api-reference/glossary#patch
[rebase]: https://git-scm.com/docs/git-rebase
[resources]: /kustomize/api-reference/glossary#resource
[workflowBespoke]: /kustomize/images/workflowBespoke.jpg
[workflowOts]: /kustomize/images/workflowOts.jpg
[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/

83
site/content/en/guides/offtheshelf/_index.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: "Off The Shelf Application"
linkTitle: "Off The Shelf Application"
type: docs
weight: 2
description: >
Workflow for off the shelf applications
---
In this workflow, all files are owned by the user and maintained in a repository under their control, but
they are based on an [off-the-shelf] configuration that is periodically consulted for updates.
![off-the-shelf config workflow image][workflowOts]
#### 1) find and [fork] an [OTS] config
#### 2) clone it as your [base]
The [base] directory is maintained in a repo whose upstream is an [OTS] configuration, in this case
some user's `ldap` repo:
> ```
> mkdir ~/ldap
> git clone https://github.com/$USER/ldap ~/ldap/base
> cd ~/ldap/base
> git remote add upstream git@github.com:$USER/ldap
> ```
#### 3) create [overlays]
As in the bespoke case above, create and populate an _overlays_ directory.
The [overlays] are siblings to each other and to the [base] they depend on.
> ```
> mkdir -p ~/ldap/overlays/staging
> mkdir -p ~/ldap/overlays/production
> ```
The user can maintain the `overlays` directory in a
distinct repository.
#### 4) bring up [variants]
> ```
> kustomize build ~/ldap/overlays/staging | kubectl apply -f -
> kustomize build ~/ldap/overlays/production | kubectl apply -f -
> ```
You can also use [kubectl-v1.14.0] to apply your [variants].
> ```
> kubectl apply -k ~/ldap/overlays/staging
> kubectl apply -k ~/ldap/overlays/production
> ```
#### 5) (optionally) capture changes from upstream
The user can periodically [rebase] their [base] to
capture changes made in the upstream repository.
> ```
> cd ~/ldap/base
> git fetch upstream
> git rebase upstream/master
> ```
[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration
[apply]: /kustomize/api-reference/glossary#apply
[applying]: /kustomize/api-reference/glossary#apply
[base]: /kustomize/api-reference/glossary#base
[fork]: https://guides.github.com/activities/forking/
[variants]: /kustomize/api-reference/glossary#variant
[kustomization]: /kustomize/api-reference/glossary#kustomization
[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration
[overlays]: /kustomize/api-reference/glossary#overlay
[patch]: /kustomize/api-reference/glossary#patch
[patches]: /kustomize/api-reference/glossary#patch
[rebase]: https://git-scm.com/docs/git-rebase
[resources]: /kustomize/api-reference/glossary#resource
[workflowBespoke]: /kustomize/images/workflowBespoke.jpg
[workflowOts]: /kustomize/images/workflowOts.jpg
[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/

375
site/content/en/guides/plugins/_index.md Normal file
View File

@@ -0,0 +1,375 @@
---
title: "Kustomize Plugins"
linkTitle: "Kustomize Plugins"
type: docs
weight: 98
description: >
Kustomize plugins guide
---
Kustomize offers a plugin framework allowing people to write their own resource _generators_
and _transformers_.
[generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md
[transformer configs]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs
Write a plugin when changing [generator options]
or [transformer configs] doesn't meet your needs.
[12-factor]: https://12factor.net
* A _generator_ plugin could be a helm chart
inflator, or a plugin that emits all the
components (deployment, service, scaler,
ingress, etc.) needed by someone's [12-factor]
application, based on a smaller number of free
variables.
* A _transformer_ plugin might perform special
container command line edits, or any other
transformation beyond those provided by the
builtin (`namePrefix`, `commonLabels`, etc.)
transformers.
## Specification in `kustomization.yaml`
Start by adding a `generators` and/or `transformers`
field to your kustomization.
Each field accepts a string list:
> ```
> generators:
> - relative/path/to/some/file.yaml
> - relative/path/to/some/kustomization
> - /absolute/path/to/some/kustomization
> - https://github.com/org/repo/some/kustomization
>
> transformers:
> - {as above}
> ```
The value of each entry in a `generators` or
`transformers` list must be a relative path to a
YAML file, or a path or URL to a [kustomization].
This is the same format as demanded by the
`resources` field.
[kustomization]: /kustomize/api-reference/glossary#kustomization
YAML files are read from disk directly. Paths or
URLs leading to kustomizations trigger an
in-process kustomization run. Each of the
resulting objects is now further interpreted by
kustomize as a _plugin configuration_ object.
## Configuration
A kustomization file could have the following lines:
```
generators:
- chartInflator.yaml
```
Given this, the kustomization process would expect
to find a file called `chartInflator.yaml` in the
kustomization [root](/kustomize/api-reference/glossary#kustomization-root).
This is the plugin's configuration file;
it contains a YAML configuration object.
The file `chartInflator.yaml` could contain:
```
apiVersion: someteam.example.com/v1
kind: ChartInflator
metadata:
name: notImportantHere
chartName: minecraft
```
__The `apiVersion` and `kind` fields are
used to locate the plugin.__
[k8s object]: /kustomize/api-reference/glossary#kubernetes-style-object
Thus, these fields are required. They are also
required because a kustomize plugin configuration
object is also a [k8s object].
To get the plugin ready to generate or transform,
it is given the entire contents of the
configuration file.
[NameTransformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go
[ChartInflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go
[plugins]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin
For more examples of plugin configuration YAML,
browse the unit tests below the [plugins] root,
e.g. the tests for [ChartInflator] or
[NameTransformer].
## Placement
Each plugin gets its own dedicated directory named
[`XDG_CONFIG_HOME`]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
```
$XDG_CONFIG_HOME/kustomize/plugin
/${apiVersion}/LOWERCASE(${kind})
```
The default value of [`XDG_CONFIG_HOME`] is
`$HOME/.config`.
The one-plugin-per-directory requirement eases
creation of a plugin bundle (source, tests, plugin
data files, etc.) for sharing.
In the case of a [Go plugin](#go-plugins), it also
allows one to provide a `go.mod` file for the
single plugin, easing resolution of package
version dependency skew.
When loading, kustomize will first look for an
_executable_ file called
```
$XDG_CONFIG_HOME/kustomize/plugin
/${apiVersion}/LOWERCASE(${kind})/${kind}
```
If this file is not found or is not executable,
kustomize will look for a file called `${kind}.so`
in the same directory and attempt to load it as a
[Go plugin](#go-plugins).
If both checks fail, the plugin load fails the overall
`kustomize build`.
## Execution
Plugins are only used during a run of the
`kustomize build` command.
Generator plugins are run after processing the
`resources` field (which itself can be viewed as a
generator, simply reading objects from disk).
The full set of resources is then passed into the
transformation pipeline, wherein builtin
transformations like `namePrefix` and
`commonLabel` are applied (if they were specified
in the kustomization file), followed by the
user-specified transformers in the `transformers`
field.
The order specified in the `transformers` field is
respected, as transformers cannot be expected to
be commutative.
#### No Security
Kustomize plugins do not run in any kind of
kustomize-provided sandbox. There's no notion
of _"plugin security"_.
A `kustomize build` that tries to use plugins but
omits the flag
> `--enable_alpha_plugins`
will not load plugins and will fail with a
warning about plugin use.
The use of this flag is an opt-in acknowledging
the unstable (alpha) plugin API, the absence of
plugin provenance, and the fact that a plugin
is not part of kustomize.
To be clear, some kustomize plugin downloaded
from the internet might wonderfully transform
k8s config in a desired manner, while also
quietly doing anything the user could do to the
system running `kustomize build`.
## Authoring
There are two kinds of plugins, [exec](#exec-plugins) and [Go](#go-plugins).
### Exec plugins
A _exec plugin_ is any executable that accepts a
single argument on its command line - the name of
a YAML file containing its configuration (the file name
provided in the kustomization file).
> TODO: restrictions on plugin to allow the _same exec
> plugin_ to be targeted by both the
> `generators` and `transformers` fields.
>
> - first arg could be the fixed string
> `generate` or `transform`,
> (the name of the configuration file moves to
> the 2nd arg), or
> - or by default an exec plugin behaves as a tranformer
> unless a flag `-g` is provided, switching the
> exec plugin to behave as a generator.
[helm chart inflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator
[bashed config map]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/bashedconfigmap
[sed transformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/sedtransformer
[hashicorp go-getter]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/gogetter
#### Examples
* [helm chart inflator] - A generator that inflates a helm chart.
* [bashed config map] - Super simple configMap generation from bash.
* [sed transformer] - Define your unstructured edits using a
plugin like this one.
* [hashicorp go-getter] - Download kustomize layes and build it to generate resources
A generator plugin accepts nothing on `stdin`, but emits
generated resources to `stdout`.
A transformer plugin accepts resource YAML on `stdin`,
and emits those resources, presumably transformed, to
`stdout`.
kustomize uses an exec plugin adapter to provide
marshalled resources on `stdin` and capture
`stdout` for further processing.
#### Generator Options
A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations.
> NOTE: These annotations are local to kustomize and will not be included in the final output.
**`kustomize.config.k8s.io/needs-hash`**
Resources can be marked as needing to be processed by the internal hash transformer by including the `needs-hash` annotation. When set valid values for the annotation are `"true"` and `"false"` which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value `"false"`.
If this annotation is set on a resource not supported by the hash transformer the build will fail.
Example:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: cm-test
annotations:
kustomize.config.k8s.io/needs-hash: "true"
data:
foo: bar
```
**`kustomize.config.k8s.io/behavior`**
The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default.
Example:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: cm-test
annotations:
kustomize.config.k8s.io/behavior: "merge"
data:
foo: bar
```
### Go plugins
Be sure to read [Go plugin caveats](goPluginCaveats.md).
[Go plugin]: https://golang.org/pkg/plugin/
A `.go` file can be a [Go plugin] if it declares
'main' as it's package, and exports a symbol to
which useful functions are attached.
It can further be used as a _kustomize_ plugin if
the symbol is named 'KustomizePlugin' and the
attached functions implement the `Configurable`,
`Generator` and `Transformer` interfaces.
A Go plugin for kustomize looks like this:
> ```
> package main
>
> import (
> "sigs.k8s.io/kustomize/api/ifc"
> "sigs.k8s.io/kustomize/api/resmap"
> ...
> )
>
> type plugin struct {...}
>
> var KustomizePlugin plugin
>
> func (p *plugin) Config(
> ldr ifc.Loader,
> rf *resmap.Factory,
> c []byte) error {...}
>
> func (p *plugin) Generate() (resmap.ResMap, error) {...}
>
> func (p *plugin) Transform(m resmap.ResMap) error {...}
> ```
Use of the identifiers `plugin`, `KustomizePlugin`
and implementation of the method signature
`Config` is required.
Implementing the `Generator` or `Transformer`
method allows (respectively) the plugin's config
file to be added to the `generators` or
`transformers` field in the kustomization file.
Do one or the other or both as desired.
[secret generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/secretsfromdatabase
[service generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/someservicegenerator
[string prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/stringprefixer
[date prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/dateprefixer
[sops encoded secrets]: https://github.com/monopole/sopsencodedsecrets
#### Examples
* [service generator] - generate a service from a name and port argument.
* [string prefixer] - uses the value in `metadata/name` as the prefix.
This particular example exists to show how a plugin can
transform the behavior of a plugin. See the
`TestTransformedTransformers` test in the `target` package.
* [date prefixer] - prefix the current date to resource names, a simple
example used to modify the string prefixer plugin just mentioned.
* [secret generator] - generate secrets from a toy database.
* [sops encoded secrets] - a more complex secret generator.
* [All the builtin plugins](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin).
User authored plugins are
on the same footing as builtin operations.
A Go plugin can be both a generator and a
transformer. The `Generate` method will run along
with all the other generators before the
`Transform` method runs.
Here's a build command that sensibly assumes the
plugin source code sits in the directory where
kustomize expects to find `.so` files:
```
d=$XDG_CONFIG_HOME/kustomize/plugin\
/${apiVersion}/LOWERCASE(${kind})
go build -buildmode plugin \
-o $d/${kind}.so $d/${kind}.go
```

724
site/content/en/guides/plugins/builtins.md Normal file
View File

@@ -0,0 +1,724 @@
---
title: "Builtin Plugins"
linkTitle: "Builtin Plugins"
type: docs
description: >
Builtin Plugins
---
# Builtin Plugins
A list of kustomize's builtin plugins - both
generators and transformers.
For each plugin, an example is given for
* implicitly triggering
the plugin via a dedicated kustomization
file field (e.g. the `AnnotationsTransformer` is
triggered by the `commonAnnotations` field).
* explicitly triggering the plugin
via the `generators` or `transformers` field
(by providing a config file specifying the
plugin).
The former method is convenient but limited in
power as most of the plugins arguments must
be defaulted. The latter method allows for
complete plugin argument specification.
[types.GeneratorOptions]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/generatoroptions.go
[types.SecretArgs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/secretargs.go
[types.ConfigMapArgs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/configmapargs.go
[config.FieldSpec]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/fieldspec.go
[types.ObjectMeta]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/objectmeta.go
[types.Selector]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/selector.go
[types.Replica]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/replica.go
[types.PatchStrategicMerge]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchstrategicmerge.go
[types.PatchTarget]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchtarget.go
[image.Image]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/image.go
## _AnnotationTransformer_
### Usage via `kustomization.yaml`
#### field name: `commonAnnotations`
Adds annotions (non-identifying metadata) to add
all resources. Like labels, these are key value
pairs.
```
commonAnnotations:
oncallPager: 800-555-1212
```
### Usage via plugin
#### Arguments
> Annotations map\[string\]string
>
> FieldSpecs \[\][config.FieldSpec]
#### Example
> ```
> apiVersion: builtin
> kind: AnnotationsTransformer
> metadata:
> name: not-important-to-example
> annotations:
> app: myApp
> greeting/morning: a string with blanks
> fieldSpecs:
> - path: metadata/annotations
> create: true
> ```
## _ConfigMapGenerator_
### Usage via `kustomization.yaml`
#### field name: `configMapGenerator`
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.
```
# 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`.
```
configMapGenerator:
- name: app-whatever
files:
- myFileName.ini=whatever.ini
```
### Usage via plugin
#### Arguments
> [types.ConfigMapArgs]
#### Example
> ```
> apiVersion: builtin
> kind: ConfigMapGenerator
> metadata:
> name: mymap
> envs:
> - devops.env
> - uxteam.env
> literals:
> - FRUIT=apple
> - VEGETABLE=carrot
> ```
## _ImageTagTransformer_
### Usage via `kustomization.yaml`
#### field name: `images`
Images modify the name, tags and/or digest for images
without creating patches. E.g. Given this
kubernetes Deployment fragment:
```
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*:
```
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
```
### Usage via plugin
#### Arguments
> ImageTag [image.Image]
>
> FieldSpecs \[\][config.FieldSpec]
#### Example
> ```
> apiVersion: builtin
> kind: ImageTagTransformer
> metadata:
> name: not-important-to-example
> imageTag:
> name: nginx
> newTag: v2
> ```
## _LabelTransformer_
### Usage via `kustomization.yaml`
#### field name: `commonLabels`
Adds labels to all resources and selectors
```
commonLabels:
someName: someValue
owner: alice
app: bingo
```
### Usage via plugin
#### Arguments
> Labels map\[string\]string
>
> FieldSpecs \[\][config.FieldSpec]
#### Example
> ```
> apiVersion: builtin
> kind: LabelTransformer
> metadata:
> name: not-important-to-example
> labels:
> app: myApp
> env: production
> fieldSpecs:
> - path: metadata/labels
> create: true
> ```
## _NamespaceTransformer_
### Usage via `kustomization.yaml`
#### field name: `namespace`
Adds namespace to all resources
```
namespace: my-namespace
```
Adds namespace to all resources
```
namespace: my-namespace
```
### Usage via plugin
#### Arguments
> [types.ObjectMeta]
>
> FieldSpecs \[\][config.FieldSpec]
#### Example
> ```
> apiVersion: builtin
> kind: NamespaceTransformer
> metadata:
> name: not-important-to-example
> namespace: test
> fieldSpecs:
> - path: metadata/namespace
> create: true
> - path: subjects
> kind: RoleBinding
> group: rbac.authorization.k8s.io
> - path: subjects
> kind: ClusterRoleBinding
> group: rbac.authorization.k8s.io
> ```
## _PatchesJson6902_
### Usage via `kustomization.yaml`
#### field name: `patchesJson6902`
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
```
[
{"op": "add", "path": "/some/new/path", "value": "value"},
{"op": "replace", "path": "/some/existing/path", "value": "new value"}
]
```
or in YAML format as
```
- op: add
path: /some/new/path
value: value
- op: replace
path: /some/existing/path
value: new value
```
```
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:
```
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"
```
### Usage via plugin
#### Arguments
> Target [types.PatchTarget]
>
> Path string
>
> JsonOp string
#### Example
> ```
> apiVersion: builtin
> kind: PatchJson6902Transformer
> metadata:
> name: not-important-to-example
> target:
> group: apps
> version: v1
> kind: Deployment
> name: my-deploy
> path: jsonpatch.json
> ```
## _PatchesStrategicMerge_
### Usage via `kustomization.yaml`
#### field name: `patchesStrategicMerge`
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.
```
patchesStrategicMerge:
- service_port_8888.yaml
- deployment_increase_replicas.yaml
- deployment_increase_memory.yaml
```
The patch content can be a inline string as well.
```
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.
### Usage via plugin
#### Arguments
> Paths \[\][types.PatchStrategicMerge]
>
> Patches string
#### Example
> ```
> apiVersion: builtin
> kind: PatchStrategicMergeTransformer
> metadata:
> name: not-important-to-example
> paths:
> - patch.yaml
> ```
## _PatchTransformer_
### Usage via `kustomization.yaml`
#### field name: `patches`
Each entry in this list should resolve to an 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. A resource
which matches all the specified fields is selected
to apply the patch.
```
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$`.
### Usage via plugin
#### Arguments
> Path string
>
> Patch string
>
> Target \*[types.Selector]
#### Example
> ```
> apiVersion: builtin
> kind: PatchTransformer
> metadata:
> name: not-important-to-example
> patch: '[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "nginx:latest"}]'
> target:
> name: .*Deploy
> kind: Deployment
> ```
## _PrefixSuffixTransformer_
### Usage via `kustomization.yaml`
#### field names: `namePrefix`, `nameSuffix`
Prepends or postfixes the value to the names
of all resources.
E.g. a deployment named `wordpress` could
become `alices-wordpress` or `wordpress-v2`
or `alices-wordpress-v2`.
```
namePrefix: alices-
nameSuffix: -v2
```
The suffix is appended before the content hash if
the resource type is ConfigMap or Secret.
### Usage via plugin
#### Arguments
> Prefix string
>
> Suffix string
>
> FieldSpecs \[\][config.FieldSpec]
#### Example
> ```
> apiVersion: builtin
> kind: PrefixSuffixTransformer
> metadata:
> name: not-important-to-example
> prefix: baked-
> suffix: -pie
> fieldSpecs:
> - path: metadata/name
> ```
## _ReplicaCountTransformer_
### Usage via `kustomization.yaml`
#### field name: `replicas`
Replicas modified the number of replicas for a resource.
E.g. Given this kubernetes Deployment fragment:
```
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:
```
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.
### Usage via plugin
#### Arguments
> Replica [types.Replica]
>
> FieldSpecs \[\][config.FieldSpec]
#### Example
> ```
> apiVersion: builtin
> kind: ReplicaCountTransformer
> metadata:
> name: not-important-to-example
> replica:
> name: myapp
> count: 23
> fieldSpecs:
> - path: spec/replicas
> create: true
> kind: Deployment
> - path: spec/replicas
> create: true
> kind: ReplicationController
> ```
## _SecretGenerator_
### Usage via `kustomization.yaml`
#### field name: `secretGenerator`
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` field
described above.
```
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"
```
### Usage via plugin
#### Arguments
> [types.ObjectMeta]
>
> [types.SecretArgs]
#### Example
> ```
> apiVersion: builtin
> kind: SecretGenerator
> metadata:
> name: my-secret
> namespace: whatever
> behavior: merge
> envs:
> - a.env
> - b.env
> files:
> - obscure=longsecret.txt
> literals:
> - FRUIT=apple
> - VEGETABLE=carrot
> ```

234
site/content/en/guides/plugins/execPluginGuidedExample.md Normal file
View File

@@ -0,0 +1,234 @@
---
title: "Exec plugin on linux"
linkTitle: "Exec plugin on linux"
type: docs
description: >
Exec plugin on linux in 60 seconds
---
This is a (no reading allowed!) 60 second copy/paste guided
example. Full plugin docs [here](README.md).
This demo writes and uses a somewhat ridiculous
_exec_ plugin (written in bash) that generates a
`ConfigMap`.
This is a guide to try it without damaging your
current setup.
#### requirements
* linux, git, curl, Go 1.13
## Make a place to work
```
DEMO=$(mktemp -d)
```
## Create a kustomization
Make a kustomization directory to
hold all your config:
```
MYAPP=$DEMO/myapp
mkdir -p $MYAPP
```
Make a deployment config:
```
cat <<'EOF' >$MYAPP/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
replicas: 3
template:
spec:
containers:
- name: the-container
image: monopole/hello:1
command: ["/hello",
"--port=8080",
"--date=$(THE_DATE)",
"--enableRiskyFeature=$(ENABLE_RISKY)"]
ports:
- containerPort: 8080
env:
- name: THE_DATE
valueFrom:
configMapKeyRef:
name: the-map
key: today
- name: ALT_GREETING
valueFrom:
configMapKeyRef:
name: the-map
key: altGreeting
- name: ENABLE_RISKY
valueFrom:
configMapKeyRef:
name: the-map
key: enableRisky
EOF
```
Make a service config:
```
cat <<EOF >$MYAPP/service.yaml
kind: Service
apiVersion: v1
metadata:
name: the-service
spec:
type: LoadBalancer
ports:
- protocol: TCP
port: 8666
targetPort: 8080
EOF
```
Now make a config file for the plugin
you're about to write.
This config file is just another k8s resource
object. The values of its `apiVersion` and `kind`
fields are used to _find_ the plugin code on your
filesystem (more on this later).
```
cat <<'EOF' >$MYAPP/cmGenerator.yaml
apiVersion: myDevOpsTeam
kind: SillyConfigMapGenerator
metadata:
name: whatever
argsOneLiner: Bienvenue true
EOF
```
Finally, make a kustomization file
referencing all of the above:
```
cat <<EOF >$MYAPP/kustomization.yaml
commonLabels:
app: hello
resources:
- deployment.yaml
- service.yaml
generators:
- cmGenerator.yaml
EOF
```
Review the files
```
ls -C1 $MYAPP
```
## Make a home for plugins
Plugins must live in a particular place for
kustomize to find them.
This demo will use the ephemeral directory:
```
PLUGIN_ROOT=$DEMO/kustomize/plugin
```
The plugin config defined above in
`$MYAPP/cmGenerator.yaml` specifies:
> ```
> apiVersion: myDevOpsTeam
> kind: SillyConfigMapGenerator
> ```
This means the plugin must live in a directory
named:
```
MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator
mkdir -p $MY_PLUGIN_DIR
```
The directory name is the plugin config's
_apiVersion_ followed by its lower-cased _kind_.
A plugin gets its own directory to hold itself,
its tests and any supplemental data files it
might need.
## Create the plugin
There are two kinds of plugins, _exec_ and _Go_.
Make an _exec_ plugin, installing it to the
correct directory and file name. The file name
must match the plugin's _kind_ (in this case,
`SillyConfigMapGenerator`):
```
cat <<'EOF' >$MY_PLUGIN_DIR/SillyConfigMapGenerator
#!/bin/bash
# Skip the config file name argument.
shift
today=`date +%F`
echo "
kind: ConfigMap
apiVersion: v1
metadata:
name: the-map
data:
today: $today
altGreeting: "$1"
enableRisky: "$2"
"
EOF
```
By definition, an _exec_ plugin must be executable:
```
chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator
```
## Install kustomize
Per the [instructions](/kustomize/installation):
```
curl -s "https://raw.githubusercontent.com/\
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
mkdir -p $DEMO/bin
mv kustomize $DEMO/bin
```
## Review the layout
```
tree $DEMO
```
## Build your app, using the plugin:
```
XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP
```
Above, if you had set
> ```
> PLUGIN_ROOT=$HOME/.config/kustomize/plugin
> ```
there would be no need to use `XDG_CONFIG_HOME` in the
_kustomize_ command above.

123
site/content/en/guides/plugins/goPluginCaveats.md Normal file
View File

@@ -0,0 +1,123 @@
---
title: "Go plugin Caveats"
linkTitle: "Go plugin Caveats"
type: docs
description: >
Go plugin Caveats
---
[plugin package]: https://golang.org/pkg/plugin
[Go modules]: https://github.com/golang/go/wiki/Modules
[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
[tensorflow plugin]: https://www.tensorflow.org/guide/extend/op
A _Go plugin_ is a compilation artifact described
by the Go [plugin package]. It is built with
special flags and cannot run on its own.
It must be loaded into a running Go program.
> A normal program written in Go might be usable
> as _exec plugin_, but is not a _Go plugin_.
Go plugins allow kustomize extensions that run
without the cost marshalling/unmarshalling all
resource data to/from a subprocess for each plugin
run. The Go plugin API assures a certain level of
consistency to avoid confusing downstream
transformers.
Go plugins work as described in the [plugin
package], but fall short of common notions
associated with the word _plugin_.
## The skew problem
Go plugin compilation creates an [ELF] formatted
`.so` file, which by definition has no information
about the provenance of the object code.
Skew between the compilation conditions (versions
of package dependencies, `GOOS`, `GOARCH`) of the
main program ELF and the plugin ELF will cause
plugin load failure, with non-helpful error
messages.
Exec plugins also lack provenance, but won't fail
due to compilation skew.
In either case, the only sensible way to share a
plugin is as some kind of _bundle_ (a git repo
URL, a git archive file, a tar file, etc.)
containing source code, tests and associated data,
unpackable under
`$XDG_CONFIG_HOME/kustomize/plugin`.
In the case of a Go plugin, an _end user_
accepting a shared plugin _must compile both
kustomize and the plugin_.
This means a one-time run of
```
# Or whatever is appropriate at time of reading
GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api
```
and then a normal development cycle using
```
go build -buildmode plugin \
-o ${wherever}/${kind}.so ${wherever}/${kind}.go
```
with paths and the release version tag (e.g. `v3.0.0`)
adjusted as needed.
For comparison, consider what one
must do to write a [tensorflow plugin].
## Why support Go plugins?
### Safety
The Go plugin developer sees the same API offered
to native kustomize operations, assuring certain
semantics, invariants, checks, etc. An exec
plugin sub-process dealing with this via
stdin/stdout will have an easier time screwing
things up for downstream transformers and
consumers.
Minor point: if the plugin reads files via
the kustomize-provided file `Loader` interface, it
will be constrained by kustomize file loading
restrictions. Of course, nothing but a code audit
prevents a Go plugin from importing the `io` package
and doing whatever it wants.
### Debugging
A Go plugin developer can debug the plugin _in
situ_, setting breakpoints inside the plugin and
elsewhere while running a plugin in feature tests.
To get the best of both worlds (shareability and safety),
a developer can write an `.go` program that functions
as an _exec plugin_, but can be processed by `go generate`
to emit a _Go plugin_ (or vice versa).
### Unit of contribution
All the builtin generators and transformers
are themselves Go plugins. This means that
the kustomize maintainers can promote a contributed
plugin to a builtin without needing code changes
(beyond those mandated by normal code review).
### Ecosystems grow through use
Tooling could ease Go plugin _sharing_, but this
requires some critical mass of Go plugin
_authoring_, which in turn is hampered by
confusion around sharing. [Go modules], once they
are more widely adopted, will solve the
biggest plugin sharing difficulty: ambiguous
plugin vs host dependencies.

375
site/content/en/guides/plugins/goPluginGuidedExample.md Normal file
View File

@@ -0,0 +1,375 @@
---
title: "Go plugin example"
linkTitle: "Go plugin example"
type: docs
description: >
Go plugin example
---
# Go Plugin Guided Example for Linux
[SopsEncodedSecrets repository]: https://github.com/monopole/sopsencodedsecrets
[Go plugin]: https://golang.org/pkg/plugin
[Go plugin caveats]: goPluginCaveats.md
This is a (no reading allowed!) 60 second copy/paste guided
example.
Full plugin docs [here](README.md).
Be sure to read the [Go plugin caveats].
This demo uses a Go plugin, `SopsEncodedSecrets`,
that lives in the [sopsencodedsecrets repository].
This is an inprocess [Go plugin], not an
sub-process exec plugin that happens to be written
in Go (which is another option for Go authors).
This is a guide to try it without damaging your
current setup.
#### requirements
* linux, git, curl, Go 1.13
For encryption
* gpg
Or
* Google cloud (gcloud) install
* a Google account with KMS permission
## Make a place to work
```shell
# Keeping these separate to avoid cluttering the DEMO dir.
DEMO=$(mktemp -d)
tmpGoPath=$(mktemp -d)
```
## Install kustomize
Need v3.0.0 for what follows, and you must _compile_
it (not download the binary from the release page):
```shell
GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize
```
## Make a home for plugins
A kustomize plugin is fully determined by
its configuration file and source code.
[required fields]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
Kustomize plugin configuration files are formatted
as kubernetes resource objects, meaning
`apiVersion`, `kind` and `metadata` are [required
fields] in these config files.
The kustomize program reads the config file
(because the config file name appears in the
`generators` or `transformers` field in the
kustomization file), then locates the Go plugin's
object code at the following location:
> ```shell
> $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so
> ```
where `lKind` holds the lowercased kind. The
plugin is then loaded and fed its config, and the
plugin's output becomes part of the overall
`kustomize build` process.
The same plugin might be used multiple times in
one kustomize build, but with different config
files. Also, kustomize might customize config
data before sending it to the plugin, for whatever
reason. For these reasons, kustomize owns the
mapping between plugins and config data; it's not
left to plugins to find their own config.
This demo will house the plugin it uses at the
ephemeral directory
```shell
PLUGIN_ROOT=$DEMO/kustomize/plugin
```
and ephemerally set `XDG_CONFIG_HOME` on a command
line below.
### What apiVersion and kind?
At this stage in the development of kustomize
plugins, plugin code doesn't know or care what
`apiVersion` or `kind` appears in the config file
sent to it.
The plugin could check these fields, but it's the
remaining fields that provide actual configuration
data, and at this point the successful parsing of
these other fields are the only thing that matters
to a plugin.
This demo uses a plugin called _SopsEncodedSecrets_,
and it lives in the [SopsEncodedSecrets repository].
Somewhat arbitrarily, we'll chose to install
this plugin with
```shell
apiVersion=mygenerators
kind=SopsEncodedSecrets
```
### Define the plugin's home dir
By convention, the ultimate home of the plugin
code and supplemental data, tests, documentation,
etc. is the lowercase form of its kind.
```shell
lKind=$(echo $kind | awk '{print tolower($0)}')
```
### Download the SopsEncodedSecrets plugin
In this case, the repo name matches the lowercase
kind already, so we just clone the repo and get
the proper directory name automatically:
```shell
mkdir -p $PLUGIN_ROOT/${apiVersion}
cd $PLUGIN_ROOT/${apiVersion}
git clone git@github.com:monopole/sopsencodedsecrets.git
```
Remember this directory:
```shell
MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind}
```
### Try the plugin's own test
Plugins may come with their own tests.
This one does, and it hopefully passes:
```shell
cd $MY_PLUGIN_DIR
go test SopsEncodedSecrets_test.go
```
Build the object code for use by kustomize:
```shell
cd $MY_PLUGIN_DIR
GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go
```
This step may succeed, but kustomize might
ultimately fail to load the plugin because of
dependency [skew].
[skew]: /docs/plugins/README.md#caveats
[used in this demo]: #install-kustomize
On load failure
* be sure to build the plugin with the same
version of Go (_go1.13_) on the same `$GOOS`
(_linux_) and `$GOARCH` (_amd64_) used to build
the kustomize being [used in this demo].
* change the plugin's dependencies in its `go.mod`
to match the versions used by kustomize (check
kustomize's `go.mod` used in its tagged commit).
Lacking tools and metadata to allow this to be
automated, there won't be a Go plugin ecosystem.
Kustomize has adopted a Go plugin architecture as
to ease accept new generators and transformers
(just write a plugin), and to be sure that native
operations (also constructed and tested as
plugins) are compartmentalized, orderable and
reusable instead of bizarrely woven throughout the
code as a individual special cases.
## Create a kustomization
Make a kustomization directory to
hold all your config:
```shell
MYAPP=$DEMO/myapp
mkdir -p $MYAPP
```
Make a config file for the SopsEncodedSecrets plugin.
Its `apiVersion` and `kind` allow the plugin to be
found:
```shell
cat <<EOF >$MYAPP/secGenerator.yaml
apiVersion: ${apiVersion}
kind: ${kind}
metadata:
name: mySecretGenerator
name: forbiddenValues
namespace: production
file: myEncryptedData.yaml
keys:
- ROCKET
- CAR
EOF
```
This plugin expects to find more data in
`myEncryptedData.yaml`; we'll get to that shortly.
Make a kustomization file referencing the plugin
config:
```shell
cat <<EOF >$MYAPP/kustomization.yaml
commonLabels:
app: hello
generators:
- secGenerator.yaml
EOF
```
Now generate the real encrypted data.
### Assure you have an encryption tool installed
We're going to use [sops](https://github.com/mozilla/sops) to encode a file. Choose either GPG or Google Cloud KMS as the secret provider to continue.
#### GPG
Try this:
```shell
gpg --list-keys
```
If it returns a list, presumably you've already created keys. If not, try import test keys from sops for dev.
```shell
curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import
SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A"
```
#### Google Cloude KMS
Try this:
```shell
gcloud kms keys list --location global --keyring sops
```
If it succeeds, presumably you've already created keys and placed them in a keyring called sops. If not, do this:
```shell
gcloud kms keyrings create sops --location global
gcloud kms keys create sops-key --location global \
--keyring sops --purpose encryption
```
Extract your keyLocation for use below:
```shell
keyLocation=$(\
gcloud kms keys list --location global --keyring sops |\
grep GOOGLE | cut -d " " -f1)
echo $keyLocation
```
### Install `sops`
```shell
GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops
```
### Create data encrypted with your private key
Create raw data to encrypt:
```shell
cat <<EOF >$MYAPP/myClearData.yaml
VEGETABLE: carrot
ROCKET: saturn-v
FRUIT: apple
CAR: dymaxion
EOF
```
Encrypt the data into file the plugin wants to read:
With PGP
```shell
$tmpGoPath/bin/sops --encrypt \
--pgp $SOPS_PGP_FP \
$MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
```
Or GCP KMS
```shell
$tmpGoPath/bin/sops --encrypt \
--gcp-kms $keyLocation \
$MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml
```
Review the files
```shell
tree $DEMO
```
This should look something like:
> ```shell
> /tmp/tmp.0kIE9VclPt
> ├── kustomize
> │   └── plugin
> │   └── mygenerators
> │   └── sopsencodedsecrets
> │   ├── go.mod
> │   ├── go.sum
> │   ├── LICENSE
> │   ├── README.md
> │   ├── SopsEncodedSecrets.go
> │   ├── SopsEncodedSecrets.so
> │   └── SopsEncodedSecrets_test.go
> └── myapp
> ├── kustomization.yaml
> ├── myClearData.yaml
> ├── myEncryptedData.yaml
> └── secGenerator.yaml
> ```
## Build your app, using the plugin:
```shell
XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP
```
This should emit a kubernetes secret, with
encrypted data for the names `ROCKET` and `CAR`.
Above, if you had set
> ```shell
> PLUGIN_ROOT=$HOME/.config/kustomize/plugin
> ```
there would be no need to use `XDG_CONFIG_HOME` in the
_kustomize_ command above.

9
site/content/en/installation/_index.md Normal file
View File

@@ -0,0 +1,9 @@
---
title: "Installation"
linkTitle: "Installation"
weight: 20
type: docs
menu:
main:
weight: 10
---

21
site/content/en/installation/binaries/_index.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: "Binaries"
linkTitle: "Binaries"
weight: 3
type: docs
description: >
Install Kustomize by downloading precompiled binaries.
---
Binaries at various versions for linux, MacOs and Windows are published on the [release page].
The follow [script] detects your OS and downloads the appropriate kustomize binary to your
current working directory.
```
curl -s "https://raw.githubusercontent.com/\
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
```
[releases page]: https://github.com/kubernetes-sigs/kustomize/releases
[script]: https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh

17
site/content/en/installation/chocolatey/_index.md Normal file
View File

@@ -0,0 +1,17 @@
---
title: "Chocolatey"
linkTitle: "Chocolatey"
weight: 4
type: docs
description: >
Install Kustomize for Windows using Chocolatey
---
```
choco install kustomize
```
For support on the chocolatey package
and prior releases, see:
- [Choco Package](https://chocolatey.org/packages/kustomize)
- [Package Source](https://github.com/kenmaglio/choco-kustomize)

21
site/content/en/installation/homebrew/_index.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: "Homebrew / MacPorts"
linkTitle: "Homebrew / MacPorts"
weight: 3
type: docs
description: >
Install Kustomize for MacOS using Homebrew or MacPorts
---
For [Homebrew](https://brew.sh) users:
```
brew install kustomize
```
For [MacPorts](https://www.macports.org) users:
```
sudo port install kustomize
```

43
site/content/en/installation/source/_index.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: "Go Source"
linkTitle: "Go Source"
weight: 2
type: docs
description: >
Install Kustomize from the Go source code
---
Requires [Go] to be installed.
## Install the kustomize CLI from source without cloning the repo
```
GOBIN=$(pwd)/ GO111MODULE=on go get sigs.k8s.io/kustomize/kustomize/v3
```
## Install the kustomize CLI from local source with cloning the repo
```
# Need go 1.13 or higher
unset GOPATH
# see https://golang.org/doc/go1.13#modules
unset GO111MODULES
# clone the repo
git clone git@github.com:kubernetes-sigs/kustomize.git
# get into the repo root
cd kustomize
# Optionally checkout a particular tag if you don't
# want to build at head
git checkout kustomize/v3.2.3
# build the binary
(cd kustomize; go install .)
# run it
~/go/bin/kustomize version
```
[Go]: https://golang.org

4
site/content/en/search-index.md Normal file
View File

@@ -0,0 +1,4 @@
---
type: "search-index"
url: "index.json"
---

6
site/content/en/search.md Normal file
View File

@@ -0,0 +1,6 @@
---
title: Search Results
layout: search
---