<!-- 
  TODO: Generate this file (or files) from
        data in directories under plugin/builtin.
        
        This file too hard to maintain distinctly
        from what's going on in those directories.
        We could expand pluginator to do this, since
        it already scans the relevant files in the
        relevant directory to generate the static
        factory methods for plugins.
-->

# 内置插件

内置插件包括生成器和转化器。

每个插件都可以通过如下两种方式触发：

* 通过 kustomization 文件的字段隐式触发插件，例如 `AnnotationsTransformer` 就是由 `commonAnnotations` 字段触发的。

* 通过 `generators` 或 `transformers` 字段显式触发插件（通过指定插件的配置文件）。

直接使用 `kustomization.yaml` 文件中的字段比如 `commonLables`、`commonAnnotation` 他们可以修改一些默认的字段，如果用户想要添加或减少能被 `commonLabel` 所修改的字段，则不是很容易做到；而使用 `transformers` 的话，用户可以指定哪些字段能被修改，而不受默认值的影响。

[types.GeneratorOptions]: ../../api/types/generatoroptions.go
[types.SecretArgs]: ../../api/types/secretargs.go
[types.ConfigMapArgs]: ../../api/types/configmapargs.go
[config.FieldSpec]: ../../api/types/fieldspec.go
[types.ObjectMeta]: ../../api/types/objectmeta.go
[types.Selector]: ../../api/types/selector.go
[types.Replica]: ../../api/types/replica.go
[types.PatchStrategicMerge]: ../../api/types/patchstrategicmerge.go
[types.PatchTarget]: ../../api/types/patchtarget.go
[image.Image]: ../../api/types/image.go

## _AnnotationTransformer_

### 使用 `kustomization.yaml`

#### 字段名称：`commonAnnotations`

为所有资源添加注释，和标签一样以 key: value 的形式。

```
commonAnnotations:
  oncallPager: 800-555-1212
```

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`configMapGenerator`

列表中的每个条目都将生成一个 ConfigMap （合计可以生成 n 个 ConfigMap）。

下面的示例会生成 3 个ConfigMap：第一个带有给定文件的名称和内容，第二个将在 data 中添加 key/value，第三个通过 `options` 为单个 ConfigMap 设置注释和标签。

每个 configMapGenerator 项均接受的参数 `behavior: [create|replace|merge]`，这个参数允许修改或替换父级现有的 configMap。

此外，每个条目都有一个 `options` 字段，该字段具有与 kustomization 文件的 `generatorOptions` 字段相同的子字段。

`options` 字段允许用户为生成的实例添加标签和（或）注释，或者分别禁用该实例名称的哈希后缀。此处添加的标签和注释不会被 kustomization 文件 `generatorOptions` 字段关联的全局选项覆盖。但是如果全局 `generatorOptions` 字段指定 `disableNameSuffixHash: true`，其他 `options` 的设置将无法将其覆盖。

```
# 这个标签将添加到所有的 ConfigMap 和 Secret 中。
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"
```

这里也可以[定义一个 key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) 来为文件设置不同名称。

下面这个示例会创建一个 ConfigMap，并将 `whatever.ini` 重命名为 `myFileName.ini`：

```
configMapGenerator:
- name: app-whatever
  files:
  - myFileName.ini=whatever.ini
```

### 使用插件

#### Arguments

> [types.ConfigMapArgs]

#### Example
> ```
> apiVersion: builtin
> kind: ConfigMapGenerator
> metadata:
>   name: mymap
> envs:
> - devops.env
> - uxteam.env
> literals:
> - FRUIT=apple
> - VEGETABLE=carrot
> ```


## _ImageTagTransformer_

### 使用 `kustomization.yaml`

#### 字段名称：`images`

修改镜像的名称、tag 或 image digest ，而无需使用 patches 。例如，对于这种 kubernetes Deployment 片段：

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

想要将 `image` 做如下更改：
 
 - 将 `postgres:8` 改为 `my-registry/my-postgres:v1`
 - 将 nginx tag 从 `1.7.9` 改为 `1.8.0`
 - 将镜像名称 `my-demo-app` 改为 `my-app`
 - 将 alpine 的 tag `3.7` 改为 digest 值

只需在 *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
```

### 使用插件

#### Arguments

> ImageTag   [image.Image]
>
> FieldSpecs \[\][config.FieldSpec]

#### Example
> ```
> apiVersion: builtin
> kind: ImageTagTransformer
> metadata:
>   name: not-important-to-example
> imageTag:
>   name: nginx
>   newTag: v2
> ```

## _LabelTransformer_

### 使用 `kustomization.yaml`

#### 字段名称：`commonLabels`

为所有资源和 selectors 增加标签。

```
commonLabels:
  someName: someValue
  owner: alice
  app: bingo
```

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`namespace`

为所有资源添加 namespace。

```
namespace: my-namespace
```

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`patchesJson6902`

patchesJson6902 列表中的每个条目都应可以解析为 kubernetes 对象和将应用于该对象的 [JSON patch](https://tools.ietf.org/html/rfc6902)。

目标字段指向的 kubernetes 对象的 group、 version、 kind、 name 和 namespace 在同一 kustomization 内 path 字段内容是 JSON patch 文件的相对路径。

patch 文件中的内容可以如下这种 JSON 格式：

```
 [
   {"op": "add", "path": "/some/new/path", "value": "value"},
   {"op": "replace", "path": "/some/existing/path", "value": "new value"}
 ]
 ```

也可以使用 YAML 格式表示：

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

patch 内容也可以是一个inline string：

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

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`patchesStrategicMerge`

此列表中的每个条目都应可以解析为 [StrategicMergePatch](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md).

这些（也可能是部分的）资源文件中的 name 必须与已经通过 `resources` 加载的 name 字段匹配，或者通过 `bases` 中的 name 字段匹配。这些条目将用于 _patch_（修改）已知资源。

推荐使用小的 patches，例如：修改内存的 request/limit，更改 ConfigMap 中的 env 变量等。小的 patches 易于维护和查看，并且易于在 overlays 中混合使用。

```
patchesStrategicMerge:
- service_port_8888.yaml
- deployment_increase_replicas.yaml
- deployment_increase_memory.yaml
```

patch 内容也可以是一个inline string：

```
patchesStrategicMerge:
- |-
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: nginx
  spec:
    template:
      spec:
        containers:
          - name: nginx
            image: nignx:latest
```

请注意，kustomize 不支持同一个 patch 对象中包含多个 _删除_ 指令。要从一个对象中删除多个字段或切片元素，需要创建一个单独的 patch，以执行所有需要的删除。

### 使用插件

#### Arguments

> Paths \[\][types.PatchStrategicMerge]
>
> Patches string


#### Example
> ```
> apiVersion: builtin
> kind: PatchStrategicMergeTransformer
> metadata:
>   name: not-important-to-example
> paths:
> - patch.yaml
> ```


## _PatchTransformer_

### 使用 `kustomization.yaml`

#### 字段名称：`patches`

这个列表中的每个条目应该解析到一个 Patch 对象，其中包括一个 patch 和一个目标选择器。patch 可以是 Strategic Merge Patch 或 JSON patch，也可以是 patch 文件或 inline string。目标选择器可以通过 group、version、kind、name、namespace、标签选择器和注释选择器来选择资源，选择一个或多个匹配所有指定字段的资源来应用 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$`. 

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`namePrefix`, `nameSuffix`

为所有资源的名称添加前缀或后缀。

例如：将 deployment 名称从 `wordpress` 变为 `alices-wordpress` 或  `wordpress-v2` 或 `alices-wordpress-v2`。

```
namePrefix: alices-
nameSuffix: -v2
```

如果资源类型是 ConfigMap 或 Secret，则在哈希值之前添加后缀。

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`replicas`

修改资源的副本数。

例如：对于如下 kubernetes Deployment 片段：

```
kind: Deployment
metadata:
  name: deployment-name
spec:
  replicas: 3
```

在 kustomization 中添加以下内容，将副本数更改为 5：

```
replicas:
- name: deployment-name
  count: 5
```

该字段内容为列表，所以可以同时修改许多资源。

由于这个声明无法设置 `kind:` 或 `group:`，所以他只能匹配如下资源中的一种：
- `Deployment`
- `ReplicationController`
- `ReplicaSet`
- `StatefulSet`

对于更复杂的用例，请使用 patch 。

### 使用插件

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

### 使用 `kustomization.yaml`

#### 字段名称：`secretGenerator`

列表中的每个条目都将生成一个 Secret（合计可以生成 n 个 Secrets）。

功能与之前描述的 `configMapGenerator` 字段类似。

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

### 使用插件

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