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

added field tables

Browse Source
This commit is contained in:
Chris Carty
2019-02-19 22:22:23 -05:00
committed by Jeffrey Regan
parent e287f615f4
commit b07bea40f7
4 changed files with 331 additions and 542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

506
docs/fields.md
View File

@@ -1,141 +1,64 @@
# Kustomize Fields
# Kustomization File Fields
- [Operators](#operators)
- [Operands](#operands)
- [Generators](#generators)
An explanation of the fields in a [kustomization.yaml](glossary.md#kustomization) file.
You can find examples of how to use Kustomize [here](https://github.com/kubernetes-sigs/kustomize/tree/master/examples).
## Operators
## Resources
For modifying operands, e.g. namePrefix, nameSuffix, commonLabels, patches, etc.
What existing things should be customized.
### Namespace
| Field | Type | Explanation |
|---|---|---|
|[resources](#resources) | list |completely specified k8s API objects, e.g. deployment.yaml, configmap.yaml, etc|
|[bases](#bases)| list |paths or github URLs specifying directories containing a kustomization. These bases may be subjected to more customization, or merely included in the output.|
|[CRDs](#crds)| list |custom resource definition files, to allow specification of the custom resources in the resources list. |
Adds namespace to all resources
## Generators
What things should be created (and optionally subsequently customized)?
| Field | Type | Explanation |
|---|---|---|
|[configMapGenerator](#configmapgenerator)| list |Each entry in this list results in the creation of one ConfigMap resource (it's a generator of n maps).|
|[secretGenerator](#secretgenerator)| list |Each entry in this list results in the creation of one Secret resource (it's a generator of n secrets)|
|[generatorOptions](#generatoroptions)|string|generatorOptions modify behavior of all ConfigMap and Secret generators|
|[generators](#generators)|list|[plugin](plugins.md) configuration files|
## Transformers
What transformations (customizations) should be applied?
| Field | Type | Explanation |
|---|---|---|
| [namespace](#namespace) | string | Adds namespace to all resources |
| [namePrefix](#nameprefix) | string | Prepends value to the names of all resources |
| [nameSuffix](#namesuffix) | string | The value is appended to the names of all resources. |
| [commonLabels](#commonlabels) | string | Adds annotions (non-identifying metadata) to add all resources. Like labels, these are key value pairs. |
| [images](#images) | list | Images modify the name, tags and/or digest for images without creating patches. |
|[patchesStrategicMerge](#patchesstrategicmerge)| list |Each entry in this list should resolve to a partial or complete resource definition file.|
|[patchesJson6902](#patchesjson6902)| list |Each entry in this list should resolve to a kubernetes object and a JSON patch that will be applied to the object.|
|[transformers](#transformers)|list|[plugin](plugins.md) configuration files|
## Meta
[k8s metadata]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
|Field|Type|Explanation|
|---|---|---|
| [vars](#vars) | string | Vars capture text from one resource's field and insert that text elsewhere. |
| [apiVersion](#apiversion) | string | [k8s metadata] field. |
| [kind](#kind) | string | [k8s metadata] field. |
----
### apiVersion
If missing, this field's value defaults to
```
namespace: my-namespace
apiVersion: kustomize.config.k8s.io/v1beta1
```
### namePrefix
Prepends value to the names of all resources
Ex. a deployment named `wordpress` would become `alices-wordpress`
```
namePrefix: alices-
```
### nameSuffix
The value is appended to the names of all resources.
Ex. A deplou,ent names "wordpress" would become "wordpress-v2"
The suffix is appended before content has if resource type is ConfigMap or Secret
```
nameSuffix: -v2
```
### commonLabels
Adds labels to all resources and selectors
```
commonLabels:
someName: someValue
owner: alice
app: bingo
```
### commonAnnotations
Adds annotions (non-identifying metadata) to add all resources. Like labls, these are key value pairs.
```
commonAnnotations:
oncallPager: 800-555-1212
```
### vars
Vars are used to capture text from one resource's field
and insert that text elsewhere.
For example, suppose one specify 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:
```
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:
```
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
```
### images
```
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
```
## Operands
[resources](#resources) - completely specified k8s API objects, e.g. deployment.yaml, configmap.yaml, etc.
[bases](#bases) - paths or github URLs specifying directories containing a kustomization. These bases may be subjected to more customization, or merely included in the output.
[CRDs](#crds) - custom resource definition files, to allow use of custom resources in the resources list. Not an actual operand - but allows the use of new operands.
### resources
Each entry in this list must resolve to an existing
resource definition in YAML. These are the resource
files that kustomize reads, modifies and emits as a
YAML string, with resources separated by document
markers ("---").
```
resource:
- some-service.yaml
- sub-dir/some-deployment.yaml
```
### bases
Each entry in this list should resolve to a directory
@@ -155,38 +78,209 @@ Typical use case: a dev, staging and production
environment that are mostly identical but differing
crucial ways (image tags, a few server arguments,
etc. that differ from the common base).
```
bases:
- ../../base
- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6
- github.com/Liujingfang1/mysql
- github.com/Liujingfang1/kustomize//examples/helloWorld?ref=test-branch
- github.com/kubernets-sigs/kustomize//examples/helloWorld?ref=test-branch
```
### commonLabels
Adds labels to all resources and selectors
```
commonLabels:
someName: someValue
owner: alice
app: bingo
```
### commonAnnotations
Adds annotions (non-identifying metadata) to add
all resources. Like labels, these are key value
pairs.
```
commonAnnotations:
oncallPager: 800-555-1212
```
### 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 two ConfigMaps. One with the
names and contents of the given files, the other with
key/value as data.
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.
```
configMapGenerator:
- name: myJavaServerProps
files:
- application.properties
- more.properties
- name: myJavaServerEnvVars
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
```
### crds
Each entry in this list should be a relative path to
a file for custom resource definition(CRD).
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 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.
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",
```
crds:
- crds/typeA.yaml
- crds/typeB.yaml
```
### generatorOptions
Modifies behavior of all [ConfigMap](#configmapgenerator)
and [Secret](#secretgenerator) generators.
```
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
```
### generators
A list of generator [plugin](plugins.md) configuration files.
```
generators:
- mySecretGeneratorPlugin.yaml
- myAppGeneratorPlugin.yaml
```
### 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
```
### kind
If missing, this field's value defaults to
```
kind: Kustomization
```
### namespace
Adds namespace to all resources
```
namespace: my-namespace
```
### namePrefix
Prepends value to the names of all resources
Ex. a deployment named `wordpress` would become `alices-wordpress`
```
namePrefix: alices-
```
### nameSuffix
The value is appended to the names of all
resources. Ex. A deployment named `wordpress`
would become `wordpress-v2`.
The suffix is appended before content has if
resource type is ConfigMap or Secret.
```
nameSuffix: -v2
```
### patchesStrategicMerge
Each entry in this list should resolve to
a partial or complete resource definition file.
Each entry in this list should be a relative path
resolving to a partial or complete resource
definition file.
The names in these (possibly partial) resource files
must match names already loaded via the `resources`
@@ -199,6 +293,13 @@ 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
```
### patchesJson6902
Each entry in this list should resolve to
@@ -239,32 +340,24 @@ patchesJson6902:
kind: Service
name: my-service
path: add_service_annotation.yaml
```
```
## Generators
Generators, for creating more resources (configmaps and secrets) which can then be customized.
### resources
### 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 two ConfigMaps. One with the
names and contents of the given files, the other with
key/value as data.
Each entry in this list must resolve to an existing
resource definition in YAML. These are the resource
files that kustomize reads, modifies and emits as a
YAML string, with resources separated by document
markers ("---").
```
configMapGenerator:
- name: myJavaServerProps
files:
- application.properties
- more.properties
- name: myJavaServerEnvVars
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
resource:
- some-service.yaml
- sub-dir/some-deployment.yaml
```
### secretGenerator
Each entry in this list results in the creation of
@@ -274,40 +367,95 @@ one Secret resource (it's a generator of n secrets).
secretGenerator:
- name: app-tls
files:
- secret/tls.cert
- secret/tls.key
- secret/tls.cert
- secret/tls.key
type: "kubernetes.io/tls"
- name: app-tls-namespaced
# you can define a namespace to generate secret in, defaults to: "default"
namespace: apps
files:
- tls.crt=catsecret/tls.cert
- tls.key=secret/tls.key
- tls.crt=catsecret/tls.cert
- tls.key=secret/tls.key
type: "kubernetes.io/tls"
- name: env_file_secret
envs:
- env.txt
type: Opaque
```
env is a path to a file to read lines of key=val
you can only specify one env file per secret.
### vars
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:
```
env: env.txt
type: Opaque
containers:
- image: myimage
command: ["start", "--host", "$(MY_SERVICE_NAME)"]
env:
- name: SECRET_TOKEN
value: $(SOME_SECRET_NAME)
```
### generatorOptions
generatorOptions modify behavior of all ConfigMap and Secret generators
To do so, add an entry to `vars:` as follows:
```
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
```
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
https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/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.