zh example:chart,secret generator plugin

2026-06-14 02:20:53 +00:00 · 2019-09-10 10:19:18 +08:00
parent 9ee35c9afb
commit 281f932814
3 changed files with 410 additions and 3 deletions
--- a/examples/zh/README.md
+++ b/examples/zh/README.md
@@ -32,13 +32,13 @@ go get sigs.k8s.io/kustomize/v3/cmd/kustomize

  - generator 插件:

-    * [last mile helm](../chart.md) - 对 helm chart 进行 last mile 修改。
+    * [last mile helm](chart.md) - 对 helm chart 进行 last mile 修改。

-    * [secret generation](../secretGeneratorPlugin.md) - 生成 Secret。
+    * [secret generation](secretGeneratorPlugin.md) - 生成 Secret。

  - transformer 插件:

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

  - 定制内建 transformer 配置

--- a/examples/zh/chart.md
+++ b/examples/zh/chart.md
@@ -0,0 +1,214 @@
+# 使用 kustomize 定义 helm chart
+
+[last mile]: https://testingclouds.wordpress.com/2018/07/20/844/
+[stable chart]: https://github.com/helm/charts/tree/master/stable
+[Helm charts]: https://github.com/helm/charts
+[_minecraft_]: https://github.com/helm/charts/tree/master/stable/minecraft
+[插件]: ../../docs/plugins
+
+kustomize 并不会读取 [Helm charts] ，但可以使用[插件]来访问 [Helm charts] 。
+
+使用 [last mile] 模式来结合 kustomize 和 helm ，使用一个 inflated chart 作为基础，然后使用 kustomize 在部署到集群的途中进行修改。
+
+以下示例中使用的插件编码仅适用于 [stable chart] 仓库中的 chart。该示例虽然使用 [_minecraft_] ，但可以应用于任何 chart。
+
+假设 `helm` 已在你的 `$PATH` 中，建立一个工作空间：
+
+<!-- @makeWorkplace @helmtest -->
+```bash
+DEMO_HOME=$(mktemp -d)
+mkdir -p $DEMO_HOME/base
+mkdir -p $DEMO_HOME/dev
+mkdir -p $DEMO_HOME/prod
+```
+
+## 使用远程 chart
+
+定义 _development_ variant（环境）。
+
+这可能涉及许多 kustomizations（参见其他示例），但在本示例中，将 `dev-` 名称前缀添加到所有资源：
+
+<!-- @writeKustDev @helmtest -->
+```bash
+cat <<'EOF' >$DEMO_HOME/dev/kustomization.yaml
+namePrefix:  dev-
+resources:
+- ../base
+EOF
+```
+
+同上，使用 `namePrefix: prod-` 定义生产 variant ：
+
+<!-- @writeKustProd @helmtest -->
+```bash
+cat <<'EOF' >$DEMO_HOME/prod/kustomization.yaml
+namePrefix:  prod-
+resources:
+- ../base
+EOF
+```
+
+这两个 variants 指向同一个 base。
+
+定义这个 base：
+
+<!-- @writeKustDev @helmtest -->
+```bash
+cat <<'EOF' >$DEMO_HOME/base/kustomization.yaml
+generators:
+- chartInflator.yaml
+EOF
+```
+
+base 指向一个名为 `chartInflator.yaml` 的生成配置文件。
+
+此文件允许指定 [stable chart] 的名称及其他内容，例如 values 文件的路径，默认为 `values.yaml` 。
+
+创建配置文件 `chartInflator.yaml`，指定 chart 名称为 _minecraft_：
+
+<!-- @writeGeneratorConfig @helmtest -->
+```bash
+cat <<'EOF' >$DEMO_HOME/base/chartInflator.yaml
+apiVersion: someteam.example.com/v1
+kind: ChartInflator
+metadata:
+  name: notImportantHere
+chartName: minecraft
+EOF
+```
+
+因为这个特定的 YAML 文件列在 kustomization文件的 `generators:` 字段中，所以它被视为生成器插件（由 _apiVersion_ 和 _kind_ 字段标识）与配置插件的其他字段之间的绑定。
+
+将插件下载到 `DEMO_HOME` 并赋予其执行权限：
+
+<!-- @installPlugin @helmtest -->
+```bash
+plugin=plugin/someteam.example.com/v1/chartinflator/ChartInflator
+curl -s --create-dirs -o \
+"$DEMO_HOME/kustomize/$plugin" \
+"https://raw.githubusercontent.com/\
+kubernetes-sigs/kustomize/master/$plugin"
+
+chmod a+x $DEMO_HOME/kustomize/$plugin
+```
+
+检查目录布局：
+
+<!-- @tree -->
+```bash
+tree $DEMO_HOME
+```
+
+将会得到类似的东西：
+
+> ```bash
+> /tmp/whatever
+> ├── base
+> │   ├── chartInflator.yaml
+> │   └── kustomization.yaml
+> ├── dev
+> │   └── kustomization.yaml
+> ├── kustomize
+> │   └── plugin
+> │       └── someteam.example.com
+> │           └── v1
+> │               └── chartinflator
+> │                  └── ChartInflator
+> └── prod
+>    └── kustomization.yaml
+> ```
+
+运行 kustomize 定义一个 helper function 来传入正确的环境和常见标志：
+
+<!-- @defineKustomizeIt @helmtest -->
+```
+function kustomizeIt {
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build --enable_alpha_plugins \
+    $DEMO_HOME/$1
+}
+```
+
+最终构建 `prod` variant。这里要注意的是，所有资源名称现在都具有 `prod-` 前缀：
+
+<!-- @doProd @helmtest -->
+```bash
+clear
+kustomizeIt prod
+```
+
+比较 `dev` 和 `prod`：
+
+<!-- @doCompare -->
+```bash
+diff <(kustomizeIt dev) <(kustomizeIt prod) | more
+```
+
+在 base上 运行 kustomize 查看未修改但已 inflated 的 chart。这里的每次调用都是重新下载并 re-inflating chart。
+
+<!-- @showBase @helmtest -->
+```bash
+kustomizeIt base
+```
+
+## 使用本地 chart
+
+上面的示例由于未在配置中指定本地 chart 的主目录，则使用 kustomize 构建将 chart 的新副本 fetche 到临时目录。
+
+要禁止 fetche ，请明确指定 chart home ，并确保图表已存在。
+
+要进行演示，并且不会干扰您现有的 helm 环境，请执行以下操作：
+
+<!-- @helmInit @helmtest -->
+```bash
+helmHome=$DEMO_HOME/dothelm
+chartHome=$DEMO_HOME/base/charts
+
+function doHelm {
+  helm --home $helmHome $@
+}
+
+# 在新位置创建 helm 配置文件。
+# 初始化命令比较复杂
+doHelm init --client-only >& /dev/null
+```
+
+现在下载 chart ； 可以再次使用的 [_minecraft_] （也可以使用其他的 chart ）：
+
+<!-- @fetchChart @helmtest -->
+```bash
+doHelm fetch --untar \
+    --untardir $chartHome \
+    stable/minecraft
+```
+
+使用 tree 查看更多信息；helm 配置数据和完成的 chart 副本：
+
+<!-- @tree -->
+```bash
+tree $DEMO_HOME
+```
+
+将 `chartHome` 字段添加到生成器的配置文件中，以便可以查找本地 chart：
+
+<!-- @modifyGenConfig @helmtest -->
+```bash
+echo "chartHome: $chartHome" >>$DEMO_HOME/base/chartInflator.yaml
+```
+
+更改 values 文件，用来展示本地 chart 的更改：
+
+<!-- @valueChange @helmtest -->
+```
+sed -i 's/CHANGEME!/SOMETHINGELSE/' $chartHome/minecraft/values.yaml
+sed -i 's/LoadBalancer/NodePort/' $chartHome/minecraft/values.yaml
+```
+
+最后进行构建：
+
+<!-- @finalProd @helmtest -->
+```bash
+kustomizeIt prod
+```
+
+观察从变化 `LoadBalancer` 到 `NodePort`，并更改编码的密码。
--- a/examples/zh/secretGeneratorPlugin.md
+++ b/examples/zh/secretGeneratorPlugin.md
@@ -0,0 +1,193 @@
+[ConfigMaps]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#configmap-v1-core
+[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
+[Go plugin]: https://golang.org/pkg/plugin
+[Secrets]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#secret-v1-core
+[base64]: https://tools.ietf.org/html/rfc4648#section-4
+[configuration directory]: https://wiki.archlinux.org/index.php/XDG_Base_Directory#Specification
+[grpc]: https://grpc.io
+[tag]: https://github.com/kubernetes-sigs/kustomize/releases
+[v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3
+[`exec.Command`]: https://golang.org/pkg/os/exec/#Command
+
+# 生成 Secrets
+
+## Secret 是什么？
+
+Kubernetes 的 [ConfigMaps] 和 [Secrets] 都是key:value map，但 [Secrets] 的内容更为敏感，比如：密码或者 ssh 秘钥。
+
+Kubernetes 开发者以各种方式工作，Secrets 保存的信息相比 ConfigMaps、Deployments 等的配置信息需要更谨慎的隐藏。
+
+## 创建一个工作空间
+
+<!-- @establishBase @testAgainstLatestRelease -->
+```bash
+DEMO_HOME=$(mktemp -d)
+```
+
+## 来自本地文件的 Secret
+
+kustomize 可以通过三种不同的方式生成来自本地文件的 Secret 。
+
+ * 从 _env_ 文件中获取（`NAME = VALUE`，每行一个）
+ * 使用文件内容来生成一个 secret
+ * 从 kustomization.yaml 文件获取 secret
+
+这里有一个示例结合所有的三种方式：
+
+创建一个包含一些短密码的 env 文件：
+
+<!-- @makeEnvFile @testAgainstLatestRelease -->
+```bash
+cat <<'EOF' >$DEMO_HOME/foo.env
+ROUTER_PASSWORD=admin
+DB_PASSWORD=iloveyou
+EOF
+```
+
+创建一个长密码的文本文件：
+
+<!-- @makeLongSecretFile @testAgainstLatestRelease -->
+```bash
+cat <<'EOF' >$DEMO_HOME/longsecret.txt
+Lorem ipsum dolor sit amet,
+consectetur adipiscing elit,
+sed do eiusmod tempor incididunt
+ut labore et dolore magna aliqua.
+EOF
+```
+
+并创建一个参考上面的 kustomization.yaml 文件，并且另外定义一些文字 KV 对：
+
+<!-- @makeKustomization1 @testAgainstLatestRelease -->
+```bash
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+secretGenerator:
+- name: mysecrets
+  envs:
+  - foo.env
+  files:
+  - longsecret.txt
+  literals:
+  - FRUIT=apple
+  - VEGETABLE=carrot
+EOF
+```
+
+生成 Secret ：
+
+<!-- @build1 @testAgainstLatestRelease -->
+```bash
+result=$(kustomize build $DEMO_HOME)
+echo "$result"
+# Spot check the result:
+test 1 == $(echo "$result" | grep -c "FRUIT: YXBwbGU=")
+```
+
+将会得到类似的内容：
+
+> ```yaml
+> apiVersion: v1
+> kind: Secret
+> metadata:
+>   name: mysecrets-hfb5df789h
+> type: Opaque
+> data:
+>   FRUIT: YXBwbGU=
+>   VEGETABLE: Y2Fycm90
+>   ROUTER_PASSWORD: YWRtaW4=
+>   DB_PASSWORD: aWxvdmV5b3U=
+>   longsecret.txt: TG9yZW0gaXBzdW0gZG9sb3Igc2l0I... (elided)
+> ```
+
+资源名称的前缀为 `mysecrets`（在 kustomization.yaml 中指定），后跟其内容的哈希值。
+
+使用 base64 解码器确认这些值的原始版本。
+
+这三种方法共同的问题是声明的 secrets 必须保存磁盘上。
+
+这会增加额外的安全问题：对本地存储的 secrets 文件的查看、安装和删除权限的控制等。
+
+## 来自任何地方的 Secret
+
+一般的替代方案是在[插件](../docs/plugins)中生成 secrets 。
+
+然后，这些值可以通过经过身份验证和授权的 RPC 进入密码保险库服务。
+
+[sgp]: ../plugin/someteam.example.com/v1/secretsfromdatabase
+
+这里有一个[secret 生成插件][sgp]，它假装从数据库中拉取 map 中的值。
+
+下载
+
+<!-- @copyPlugin @testAgainstLatestRelease -->
+```bash
+repo=https://raw.githubusercontent.com/kubernetes-sigs/kustomize
+pPath=plugin/someteam.example.com/v1/secretsfromdatabase
+dir=$DEMO_HOME/kustomize/$pPath
+
+mkdir -p $dir
+
+curl -s -o $dir/SecretsFromDatabase.go \
+  ${repo}/master/$pPath/SecretsFromDatabase.go
+```
+
+进行构建
+
+<!-- @compilePlugin @xtest -->
+```bash
+go build -buildmode plugin \
+  -o $dir/SecretsFromDatabase.so \
+  $dir/SecretsFromDatabase.go
+```
+
+创建一个配置文件：
+
+<!-- @makeConfiguration @testAgainstLatestRelease -->
+```bash
+cat <<'EOF' >$DEMO_HOME/secretFromDb.yaml
+apiVersion: someteam.example.com/v1
+kind: SecretsFromDatabase
+metadata:
+  name: mySecretGenerator
+name: forbiddenValues
+namespace: production
+keys:
+- ROCKET
+- VEGETABLE
+EOF
+```
+
+创建一个引用此插件的新 kustomization.yaml 文件：
+
+<!-- @makeKustomization2 @testAgainstLatestRelease -->
+```bash
+cat <<'EOF' >$DEMO_HOME/kustomization.yaml
+generators:
+- secretFromDb.yaml
+EOF
+```
+
+最终生成 secret ，设置 `XDG_CONFIG_HOME` 以便可以在 `$DEMO_HOME` 中找到该插件：
+
+<!-- @build2 @xtest -->
+```bash
+result=$( \
+  XDG_CONFIG_HOME=$DEMO_HOME \
+  kustomize build --enable_alpha_plugins $DEMO_HOME )
+echo "$result"
+# Spot check the result:
+test 1 == $(echo "$result" | grep -c "FRUIT: YXBwbGU=")
+```
+
+将会得到类似的内容：
+
+> ```yaml
+> apiVersion: v1
+> kind: Secret
+> metadata:
+>   name: mysecrets-bdt27dbkd6
+> type: Opaque
+> data:
+>  FRUIT: YXBwbGU=
+>  VEGETABLE: Y2Fycm90
+> ```