Skip to content

Commit

Permalink
Example of configuring builtin plugin.
Browse files Browse the repository at this point in the history
  • Loading branch information
@monopole
monopole committed Sep 17, 2019
1 parent 32be1cf commit 9a50056
Show file tree
Hide file tree
Showing 3 changed files with 979 additions and 302 deletions.
315 changes: 13 additions & 302 deletions docs/fields.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ apiVersion: kustomize.config.k8s.io/v1beta1

### bases

The `bases` field was deprecated in v2.1.0.
_The `bases` field was deprecated in v2.1.0._

Move entries into the [resources](#resources)
field. This allows bases - which are still a
Expand All @@ -74,61 +74,14 @@ ordered relative to other input resources.

### commonLabels

Adds labels to all resources and selectors
```
commonLabels:
someName: someValue
owner: alice
app: bingo
```
See [./plugins/builtins.md#field-name-commonLabels]

### commonAnnotations

Adds annotions (non-identifying metadata) to add
all resources. Like labels, these are key value
pairs.

```
commonAnnotations:
oncallPager: 800-555-1212
```
See [./plugins/builtins.md#field-name-commonAnnotations]

### 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
```

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
```
See [./plugins/builtins.md#field-name-configMapGenerator]

### crds

Expand All @@ -155,9 +108,7 @@ The annotations can be put into openAPI definitions are:
- "x-kubernetes-object-ref-kind": "Secret",
- "x-kubernetes-object-ref-name-key": "name",


```
crds:
- crds/typeA.yaml
- crds/typeB.yaml
Expand Down Expand Up @@ -195,42 +146,7 @@ generators:

### 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
```
See [./plugins/builtins.md#field-name-images]

### inventory

Expand All @@ -244,217 +160,33 @@ If missing, this field's value defaults to
kind: Kustomization
```


### namespace

Adds namespace to all resources

```
namespace: my-namespace
```
See [./plugins/builtins.md#field-name-namespace]

### namePrefix

Prepends value to the names of all resources
Ex. a deployment named `wordpress` would become `alices-wordpress`

```
namePrefix: alices-
```
See [./plugins/builtins.md#field-name-namePrefix]

### 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
```
See [./plugins/builtins.md#field-name-namePrefix]

### 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$`.
See [./plugins/builtins.md#field-name-patches]

### 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.
See [./plugins/builtins.md#field-name-patchesStrategicMerge]

### 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"
```
See [./plugins/builtins.md#field-name-patchesJson6902]

### 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.


#### Limitation

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.

See [./plugins/builtins.md#field-name-replicas]

### resources

Expand Down Expand Up @@ -492,28 +224,7 @@ must contain a `kustomization.yaml` file.

### secretGenerator

Each entry in this list results in the creation of
one Secret resource (it's a generator of n secrets).

```
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 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
```
See [./plugins/builtins.md#field-name-secretGenerator]

### vars

Expand Down
Loading

0 comments on commit 9a50056

Please sign in to comment.