Merge pull request #1611 from sunny0826/zh

add zh doc transformerconfigs.md validationTransformer.md
2026-05-17 18:25:26 +00:00 · 2019-12-12 09:04:33 -08:00
parent 57059b74f5 92dcc02ff1
commit d5b44461b9
4 changed files with 381 additions and 3 deletions
--- a/examples/zh/README.md
+++ b/examples/zh/README.md
@@ -38,11 +38,11 @@ go get sigs.k8s.io/kustomize/v3/cmd/kustomize

  - transformer 插件:

-    * [validation transformer](../validationTransformer/README.md) - 通过 transformer 验证资源。
+    * [validation transformer](validationTransformer.md) - 通过 transformer 验证资源。

  - 定制内建 transformer 配置

-    * [transformer configs](../transformerconfigs/README.md) - 自定义 transformer 配置。
+    * [transformer configs](transformerconfigs.md) - 自定义 transformer 配置。

 多 Variant 示例

--- a/examples/zh/chart.md
+++ b/examples/zh/chart.md
@@ -6,7 +6,7 @@
 [_minecraft_]: https://github.com/helm/charts/tree/master/stable/minecraft
 [插件]: ../../docs/plugins

-kustomize 并不会读取 [Helm charts] ，但可以使用 generator ß来访问 [Helm charts] 。
+kustomize 并不会读取 [Helm charts] ，但可以使用 generator 来访问 [Helm charts] 。

 使用 [last mile] 模式来结合 kustomize 和 helm ，使用一个 inflated chart 作为基础，然后使用 kustomize 在部署到集群的途中进行修改。

--- a/examples/zh/transformerconfigs.md
+++ b/examples/zh/transformerconfigs.md
@@ -0,0 +1,171 @@
+# 自定义 transformer 配置
+
+Kustomize 通过对原始资源集进行一系列转换来创建新资源。Kustomize 提供以下默认的 transformers ：
+
+- annotations
+- images
+- labels
+- name reference
+- namespace
+- prefix/suffix
+- variable reference
+
+transformer 配置的 `fieldSpec` 列表，用来确定哪些资源类型和这些类型的 transformer 可以修改哪些字段。
+
+## FieldSpec
+
+FieldSpec 是一种表示资源中字段路径的类型。
+
+```yaml
+group: some-group
+version: some-version
+kind: some-kind
+path: path/to/the/field
+create: false
+```
+
+如果 `create` 设置为 `true`，表示如果尚未找到该路径，则 transformer 将在资源中创建该路径。这对于 label 和 annotation 转换器最有用，因为在转换之前可能未设置 label 或 annotation 的路径。
+
+## Images transformer
+
+默认的 images transformer 会更新包含 `containers` 和 `initcontainers` 子路径的路径中找到的指定镜像的键值 。如果找到，则更新 `image` 的 `newName`，`newTag` 和 `digest` 等字段。该 `name` 字段应与 `image` 资源中的键值匹配。
+
+kustomization.yaml 示例：
+
+```yaml
+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:25a0d4
+```
+可以通过创建 `images` 包含 `path` 和 `kind` 字段的列表来自定义镜像 transformer 配置。[镜像 transformer 教程](image.md) 展示了如何指定默认镜像 transformer 和自定义镜像 transformer 配置。
+
+## Prefix/suffix transformer
+
+prefix/suffix transformer 为所有资源的 `metadata/name` 字段添加前缀/后缀。默认的 prefix transformer 配置如下：
+
+```yaml
+namePrefix:
+- path: metadata/name
+```
+
+kustomization.yaml 示例：
+
+```yaml
+
+namePrefix:
+  alices-
+
+nameSuffix:
+  -v2
+```
+
+## Labels transformer
+
+labels transformer 将 labels 添加到所有资源的 `metadata/labels` 字段。它还将 labels 添加到 `spec/selector` 和 `spec/selector/matchLabels` 字段以及所有 Deployment 资源中的字段。
+
+示例：
+
+```yaml
+commonLabels:
+- path: metadata/labels
+  create: true
+
+- path: spec/selector
+  create: true
+  version: v1
+  kind: Service
+
+- path: spec/selector/matchLabels
+  create: true
+  kind: Deployment
+```
+
+kustomization.yaml 示例:
+
+```yaml
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+```
+
+## Annotations transformer
+
+annotations transformer 可以：
+
+- 将 annotations 添加到所有资源的 `metadata/annotations` 字段
+- 将 annotations 添加到Deployment，ReplicaSet，DaemonSet，StatefulSet，Job 和 CronJob 等资源的 `spec/template/metadata/annotations`
+- 将 annotations 添加到CronJob 资源的 `spec/jobTemplate/spec/template/metadata/annotations`字段。
+
+kustomization.yaml 示例：
+
+```yaml
+commonAnnotations:
+  oncallPager: 800-555-1212
+```
+
+## Name reference transformer
+
+Name reference transformer 的配置不同于其他所有的 transformer。`nameReferences` 列表代表一种可以用作其他类型资源中的引用的所有可能字段。一个 `nameReference` 包含一个类型如 ConfigMap 以及 `fieldSpecs` 列表，其中 `ConfigMap` 其他资源被引用。下面是一个例子：
+
+```yaml
+kind: ConfigMap
+version: v1
+fieldSpecs:
+- kind: Pod
+  version: v1
+  path: spec/volumes/configMap/name
+- kind: Deployment
+  path: spec/template/spec/volumes/configMap/name
+- kind: Job
+  path: spec/template/spec/volumes/configMap/name
+```
+
+Name reference transformer 的配置为 `nameReferences` 列表包含 ConfigMap，Secret，Service，Role和ServiceAccount等资源。下面是一个示例配置：
+
+```yaml
+nameReference:
+- kind: ConfigMap
+  version: v1
+  fieldSpecs:
+  - path: spec/volumes/configMap/name
+    version: v1
+    kind: Pod
+  - path: spec/containers/env/valueFrom/configMapKeyRef/name
+    version: v1
+    kind: Pod
+  # ...
+- kind: Secret
+  version: v1
+  fieldSpecs:
+  - path: spec/volumes/secret/secretName
+    version: v1
+    kind: Pod
+  - path: spec/containers/env/valueFrom/secretKeyRef/name
+    version: v1
+    kind: Pod
+```
+
+## Customizing transformer configurations
+
+除默认 transformers 外，您还可以创建自定义的 transformers 配置。通过调用将默认的 transformers 配置保存到本地目录`kustomize config save -d`，然后修改和使用这些配置。本教程显示了如何创建自定义 transformers 配置：
+
+- [support a CRD type](../transformerconfigs/crd/README.md)
+- 添加额外的字段以进行变量替换
+- 添加额外的字段以供名称参考
+
+## Supporting escape characters in CRD path
+
+```yaml
+metadata:
+  annotations:
+    foo.k8s.io/bar: baz
+```
+Kustomize 支持在路径中转义特殊字符，例如： `metadata/annotations/foo.k8s.io\/bar`
--- a/examples/zh/validationTransformer.md
+++ b/examples/zh/validationTransformer.md
@@ -0,0 +1,207 @@
+# 通过 transformer 验证资源
+
+[kubeval]: https://github.com/instrumenta/kubeval
+[插件]: ../../docs/plugins
+
+kustomize 不会验证其输入或输出是否符合资源要求。
+
+而另一个工具 [kubeval] 提供了验证 k8s 资源的功能，例如：
+
+```shell
+$ kubeval my-invalid-rc.yaml
+The document my-invalid-rc.yaml contains an invalid ReplicationController
+--> spec.replicas: Invalid type. Expected: integer, given: string
+```
+
+可以创建一个 Kustomize transformer [插件] 通过运行 [kubeval] 来进行验证资源。
+
+创建一个工作空间：
+
+<!-- @makeWorkplace @test -->
+```bash
+DEMO_HOME=$(mktemp -d)
+mkdir -p $DEMO_HOME/valid
+mkdir -p $DEMO_HOME/invalid
+PLUGINDIR=$DEMO_HOME/kustomize/plugin/someteam.example.com/v1/validator
+mkdir -p $PLUGINDIR
+```
+
+## 创建 transformer 插件
+
+根据操作系统下载 [kubeval] 的二进制文件并将其添加到 $PATH。
+
+<!-- @downloadKubeval @test -->
+```bash
+OS=`uname | sed -e 's/Linux/linux/' -e 's/Darwin/darwin/'`
+wget https://github.com/instrumenta/kubeval/releases/download/0.9.2/kubeval-${OS}-amd64.tar.gz
+tar xf kubeval-${OS}-amd64.tar.gz
+export PATH=$PATH:`pwd`
+```
+
+transformer 插件将执行逻辑如下：
+
+- 从 stdin 中读取资源并传递到 transformer 插件。
+- transformer 插件的配置文件作为第一个参数传入。
+- transformer 插件的工作目录是 kustomization 所在目录。
+- 转换后的资源由插件写入 stdout 。
+- transformer 返回值为0，则转化成功；如果 transformer 插件的返回值不为0，则 kustomize 认为转化期间存在错误。
+
+我们可以写一个 bash 脚本作为用于验证资源的 transformer 插件，该脚本执行 [kubeval] 二进制文件并返回正确的输出和退出码。
+<!-- @writePlugin @test -->
+```bash
+cat <<'EOF' > $PLUGINDIR/Validator
+#!/bin/bash
+
+if ! [ -x "$(command -v kubeval)" ]; then
+  echo "Error: kubeval is not installed."
+  exit 1
+fi
+
+temp_file=$(mktemp)
+output_file=$(mktemp)
+cat - > $temp_file
+
+kubeval $temp_file > $output_file
+
+if [ $? -eq 0 ]; then
+    cat $temp_file
+    rm $temp_file $output_file
+    exit 0
+fi
+
+cat $output_file
+rm $temp_file $output_file
+exit 1
+
+EOF
+chmod +x $PLUGINDIR/Validator
+```
+
+## 使用 transformer 插件
+
+创建一个包含有效 ConfigMap 和 transformer 插件的 Kustomization。
+
+<!-- @writeKustomization @test -->
+```bash
+cat <<'EOF' >$DEMO_HOME/valid/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm
+data:
+  foo: bar
+EOF
+
+cat <<'EOF' >$DEMO_HOME/valid/validation.yaml
+apiVersion: someteam.example.com/v1
+kind: Validator
+metadata:
+  name: notImportantHere
+EOF
+
+cat <<'EOF' >$DEMO_HOME/valid/kustomization.yaml
+resources:
+- configmap.yaml
+
+transformers:
+- validation.yaml
+EOF
+```
+
+创建一个包含无效 ConfigMap 和 transformer 插件的 Kustomization。
+
+<!-- @writeKustomization @test -->
+```bash
+cat <<'EOF' >$DEMO_HOME/invalid/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm
+data:
+- foo: bar
+EOF
+# ConfigMap 的 data 字段需要传入的数据类型为 object，这里传入一个 array
+
+cat <<'EOF' >$DEMO_HOME/invalid/validation.yaml
+apiVersion: someteam.example.com/v1
+kind: Validator
+metadata:
+  name: notImportantHere
+EOF
+
+cat <<'EOF' >$DEMO_HOME/invalid/kustomization.yaml
+resources:
+- configmap.yaml
+
+transformers:
+- validation.yaml
+EOF
+```
+
+目录结构如下：
+
+```bash
+/tmp/tmp.fAYMfLZJs4
+├── invalid
+│   ├── configmap.yaml
+│   ├── kustomization.yaml
+│   └── validation.yaml
+├── kustomize
+│   └── plugin
+│       └── someteam.example.com
+│           └── v1
+│               ├── kubeval
+│               └── Validator
+└── valid
+    ├── configmap.yaml
+    ├── kustomization.yaml
+    └── validation.yaml
+```
+
+定义一个 helper 函数在正确的的环境和插件标记运行 kustomize 。
+
+<!-- @defineKustomizeBd @test -->
+```bash
+function kustomizeBd {
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build \
+    --enable_alpha_plugins \
+    $DEMO_HOME/$1
+}
+```
+
+构建有效的 variant
+
+<!-- @buildValid @test -->
+```bash
+kustomizeBd valid
+```
+输出的 ConfigMap 内容为：
+
+```yaml
+apiVersion: v1
+data:
+  foo: bar
+kind: ConfigMap
+metadata:
+  name: cm
+```
+
+构建无效的 variant
+
+```bash
+kustomizeBd invalid
+```
+
+可以查看到输出错误日志为：
+
+```shell
+data: Invalid type. Expected: object, given: array
+```
+
+## 清理
+
+<!-- @cleanup @test -->
+```shell
+rm -rf $DEMO_HOME
+```