内置插件

内置插件

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

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

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

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

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

AnnotationTransformer

使用 kustomization.yaml

字段名称：commonAnnotations

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

  1. commonAnnotations:
  2.   oncallPager: 800-555-1212

使用插件

Arguments

Annotations map[string]string

FieldSpecs []config.FieldSpec

Example

  1. apiVersion: builtin
  2. kind: AnnotationsTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. annotations:
  6.   app: myApp
  7.   greeting/morning: a string with blanks
  8. fieldSpecs:
  9. - path: metadata/annotations
  10.   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 的设置将无法将其覆盖。

  1. # These labels are added to all configmaps and secrets.
  2. generatorOptions:
  3.   labels:
  4.     fruit: apple
  6. configMapGenerator:
  7. - name: my-java-server-props
  8.   behavior: merge
  9.   files:
  10.   - application.properties
  11.   - more.properties
  12. - name: my-java-server-env-vars
  13.   literals: 
  14.   - JAVA_HOME=/opt/java/jdk
  15.   - JAVA_TOOL_OPTIONS=-agentlib:hprof
  16.   options:
  17.     disableNameSuffixHash: true
  18.     labels:
  19.       pet: dog
  20. - name: dashboards
  21.   files:
  22.   - mydashboard.json
  23.   options:
  24.     annotations:
  25.       dashboard: "1"
  26.     labels:
  27.       app.kubernetes.io/name: "app1"

这里也可以定义一个 key 来为文件设置不同名称。

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

  1. configMapGenerator:
  2. - name: app-whatever
  3.   files:
  4.   - myFileName.ini=whatever.ini

使用插件

Arguments

types.ConfigMapArgs

Example

  1. apiVersion: builtin
  2. kind: ConfigMapGenerator
  3. metadata:
  4.   name: mymap
  5. envs:
  6. - devops.env
  7. - uxteam.env
  8. literals:
  9. - FRUIT=apple
  10. - VEGETABLE=carrot

ImageTagTransformer

使用 kustomization.yaml

字段名称：images

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

  1. containers:
  2. - name: mypostgresdb
  3.   image: postgres:8
  4. - name: nginxapp
  5.   image: nginx:1.7.9
  6. - name: myapp
  7.   image: my-demo-app:latest
  8. - name: alpine-app
  9.   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 中添加以下内容：

  1. images:
  2. - name: postgres
  3.   newName: my-registry/my-postgres
  4.   newTag: v1
  5. - name: nginx
  6.   newTag: 1.8.0
  7. - name: my-demo-app
  8.   newName: my-app
  9. - name: alpine
  10.   digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3

使用插件

Arguments

ImageTag image.Image

FieldSpecs []config.FieldSpec

Example

  1. apiVersion: builtin
  2. kind: ImageTagTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. imageTag:
  6.   name: nginx
  7.   newTag: v2

LabelTransformer

使用 kustomization.yaml

字段名称：commonLabels

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

  1. commonLabels:
  2.   someName: someValue
  3.   owner: alice
  4.   app: bingo

使用插件

Arguments

Labels map[string]string

FieldSpecs []config.FieldSpec

Example

  1. apiVersion: builtin
  2. kind: LabelTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. labels:
  6.   app: myApp
  7.   env: production
  8. fieldSpecs:
  9. - path: metadata/labels
  10.   create: true

NamespaceTransformer

使用 kustomization.yaml

字段名称：namespace

为所有资源添加 namespace。

  1. namespace: my-namespace

使用插件

Arguments

types.ObjectMeta

FieldSpecs []config.FieldSpec

Example

  1. apiVersion: builtin
  2.  kind: NamespaceTransformer
  3.  metadata:
  4.    name: not-important-to-example
  5.    namespace: test
  6.  fieldSpecs:
  7.  - path: metadata/namespace
  8.    create: true
  9.  - path: subjects
  10.    kind: RoleBinding
  11.    group: rbac.authorization.k8s.io
  12.  - path: subjects
  13.    kind: ClusterRoleBinding
  14.    group: rbac.authorization.k8s.io

PatchesJson6902

使用 kustomization.yaml

字段名称：patchesJson6902

patchesJson6902 列表中的每个条目都应可以解析为 kubernetes 对象和将应用于该对象的 JSON patch。

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

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

  1.  [
  2.    {"op": "add", "path": "/some/new/path", "value": "value"},
  3.    {"op": "replace", "path": "/some/existing/path", "value": "new value"}
  4.  ]

也可以使用 YAML 格式表示：

  1. - op: add
  2.   path: /some/new/path
  3.   value: value
  4. - op: replace
  5.   path: /some/existing/path
  6.   value: new value
  1. patchesJson6902:
  2. - target:
  3.     version: v1
  4.     kind: Deployment
  5.     name: my-deployment
  6.   path: add_init_container.yaml
  7. - target:
  8.     version: v1
  9.     kind: Service
  10.     name: my-service
  11.   path: add_service_annotation.yaml

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

  1. patchesJson6902:
  2. - target:
  3.     version: v1
  4.     kind: Deployment
  5.     name: my-deployment
  6.   patch: |-
  7.     - op: add
  8.       path: /some/new/path
  9.       value: value
  10.     - op: replace
  11.       path: /some/existing/path
  12.       value: "new value"

使用插件

Arguments

Target types.PatchTarget

Path string

JsonOp string

Example

  1. apiVersion: builtin
  2. kind: PatchJson6902Transformer
  3. metadata:
  4.   name: not-important-to-example
  5. target:
  6.   group: apps
  7.   version: v1
  8.   kind: Deployment
  9.   name: my-deploy
  10. path: jsonpatch.json

PatchesStrategicMerge

使用 kustomization.yaml

字段名称：patchesStrategicMerge

此列表中的每个条目都应可以解析为 StrategicMergePatch.

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

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

  1. patchesStrategicMerge:
  2. - service_port_8888.yaml
  3. - deployment_increase_replicas.yaml
  4. - deployment_increase_memory.yaml

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

  1. patchesStrategicMerge:
  2. - |-
  3.   apiVersion: apps/v1
  4.   kind: Deployment
  5.   metadata:
  6.     name: nginx
  7.   spec:
  8.     template:
  9.       spec:
  10.         containers:
  11.           - name: nginx
  12.             image: nignx:latest

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

使用插件

Arguments

Paths []types.PatchStrategicMerge

Patches string

Example

  1. apiVersion: builtin
  2. kind: PatchStrategicMergeTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. paths:
  6. - patch.yaml

PatchTransformer

使用 kustomization.yaml

字段名称：patches

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

  1. patches:
  2. - path: patch.yaml
  3.   target:
  4.     group: apps
  5.     version: v1
  6.     kind: Deployment
  7.     name: deploy.*
  8.     labelSelector: "env=dev"
  9.     annotationSelector: "zone=west"
  10. - patch: |-
  11.     - op: replace
  12.       path: /some/existing/path
  13.       value: new value    
  14.   target:
  15.     kind: MyKind
  16.     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

  1. apiVersion: builtin
  2. kind: PatchTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. patch: '[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "nginx:latest"}]'
  6. target:
  7.   name: .*Deploy
  8.   kind: Deployment

PrefixSuffixTransformer

使用 kustomization.yaml

字段名称：namePrefix, nameSuffix

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

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

  1. namePrefix: alices-
  2. nameSuffix: -v2

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

使用插件

Arguments

Prefix string

Suffix string

FieldSpecs []config.FieldSpec

Example

  1. apiVersion: builtin
  2. kind: PrefixSuffixTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. prefix: baked-
  6. suffix: -pie
  7. fieldSpecs:
  8.   - path: metadata/name

ReplicaCountTransformer

使用 kustomization.yaml

字段名称：replicas

修改资源的副本数。

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

  1. kind: Deployment
  2. metadata:
  3.   name: deployment-name
  4. spec:
  5.   replicas: 3

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

  1. replicas:
  2. - name: deployment-name
  3.   count: 5

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

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

  • Deployment
  • ReplicationController
  • ReplicaSet
  • StatefulSet

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

使用插件

Arguments

Replica types.Replica

FieldSpecs []config.FieldSpec

Example

  1. apiVersion: builtin
  2. kind: ReplicaCountTransformer
  3. metadata:
  4.   name: not-important-to-example
  5. replica:
  6.   name: myapp
  7.   count: 23
  8. fieldSpecs:
  9. - path: spec/replicas
  10.   create: true
  11.   kind: Deployment
  12. - path: spec/replicas
  13.   create: true
  14.   kind: ReplicationController

SecretGenerator

使用 kustomization.yaml

字段名称：secretGenerator

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

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

  1. secretGenerator:
  2. - name: app-tls
  3.   files:
  4.   - secret/tls.cert
  5.   - secret/tls.key
  6.   type: "kubernetes.io/tls"
  7. - name: app-tls-namespaced
  8.   # you can define a namespace to generate
  9.   # a secret in, defaults to: "default"
  10.   namespace: apps
  11.   files:
  12.   - tls.crt=catsecret/tls.cert
  13.   - tls.key=secret/tls.key
  14.   type: "kubernetes.io/tls"
  15. - name: env_file_secret
  16.   envs:
  17.   - env.txt
  18.   type: Opaque
  19. - name: secret-with-annotation
  20.   files:
  21.   - app-config.yaml
  22.   type: Opaque
  23.   options:
  24.     annotations:
  25.       app_config: "true"
  26.     labels:
  27.       app.kubernetes.io/name: "app2"

使用插件

Arguments

types.ObjectMeta

types.SecretArgs

Example

  1. apiVersion: builtin
  2. kind: SecretGenerator
  3. metadata:
  4.   name: my-secret
  5.   namespace: whatever
  6. behavior: merge
  7. envs:
  8. - a.env
  9. - b.env
  10. files:
  11. - obscure=longsecret.txt
  12. literals:
  13. - FRUIT=apple
  14. - VEGETABLE=carrot