From 8ce637a004aacb63a0283c22433e5acd8ed1d685 Mon Sep 17 00:00:00 2001 From: guoxudong Date: Wed, 3 Jun 2020 17:12:47 +0800 Subject: [PATCH] add zh doc exec/go plugin --- docs/zh/execPluginGuidedExample.md | 206 ++++++++++++++++++++ docs/zh/goPluginCaveats.md | 66 +++++++ docs/zh/goPluginGuidedExample.md | 300 +++++++++++++++++++++++++++++ docs/zh/plugins.md | 6 +- 4 files changed, 575 insertions(+), 3 deletions(-) create mode 100644 docs/zh/execPluginGuidedExample.md create mode 100644 docs/zh/goPluginCaveats.md create mode 100644 docs/zh/goPluginGuidedExample.md diff --git a/docs/zh/execPluginGuidedExample.md b/docs/zh/execPluginGuidedExample.md new file mode 100644 index 000000000..bea8e014b --- /dev/null +++ b/docs/zh/execPluginGuidedExample.md @@ -0,0 +1,206 @@ +# 60 秒构建一个 Exec 插件 + +本教程只是一个快速开始的示例，完整的插件文档请看：[kustomize 插件](plugins.md) + +本示例将使用 bash 编写了一个傻瓜 _exec_ 插件，用来生成一个 `ConfigMap`。 + +在不破坏当前的设置的情况下，尝试本教程。 + +#### 环境要求 + + * `linux` + * `git` + * `curl` + * `Go 1.13` + + +## 定义一个工作空间 + +``` +DEMO=$(mktemp -d) +``` + +## 编写 kustomization + +新建一个目录来保存所有的配置： + +``` +MYAPP=$DEMO/myapp +mkdir -p $MYAPP +``` + +编写一个 Deployment 配置： + +``` +cat <<'EOF' >$MYAPP/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + replicas: 3 + template: + spec: + containers: + - name: the-container + image: monopole/hello:1 + command: ["/hello", + "--port=8080", + "--date=$(THE_DATE)", + "--enableRiskyFeature=$(ENABLE_RISKY)"] + ports: + - containerPort: 8080 + env: + - name: THE_DATE + valueFrom: + configMapKeyRef: + name: the-map + key: today + - name: ALT_GREETING + valueFrom: + configMapKeyRef: + name: the-map + key: altGreeting + - name: ENABLE_RISKY + valueFrom: + configMapKeyRef: + name: the-map + key: enableRisky +EOF +``` + +编写一个 service 配置： + +``` +cat <$MYAPP/service.yaml +kind: Service +apiVersion: v1 +metadata: + name: the-service +spec: + type: LoadBalancer + ports: + - protocol: TCP + port: 8666 + targetPort: 8080 +EOF +``` + +现在为您要编写的插件创建一个配置文件。 + +这个配置文件的内容也是 k8s 资源对象。其中 `apiVersion` 和 `kind` 字段的值用于在文件系统中查找插件代码（稍后会对此进行更多介绍）。 + +``` +cat <<'EOF' >$MYAPP/cmGenerator.yaml +apiVersion: myDevOpsTeam +kind: SillyConfigMapGenerator +metadata: + name: whatever +argsOneLiner: Bienvenue true +EOF +``` + +最后在 kustomization 文件中引用以上所有内容： + +``` +cat <$MYAPP/kustomization.yaml +commonLabels: + app: hello +resources: +- deployment.yaml +- service.yaml +generators: +- cmGenerator.yaml +EOF +``` + +检查这些文件 + +``` +ls -C1 $MYAPP +``` + +## 为插件创建目录 + +插件必须位于特定的目录，以便 Kustomize 能够找到它们。 + +该示例将使用临时目录： + +``` +PLUGIN_ROOT=$DEMO/kustomize/plugin +``` + +在上面定义的插件配置 `$MYAPP/cmGenerator.yaml` 中指定： + +> ``` +> apiVersion: myDevOpsTeam +> kind: SillyConfigMapGenerator +> ``` + +这意味着该插件必须位于以下目录中： + +``` +MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator + +mkdir -p $MY_PLUGIN_DIR +``` + +插件的目录结构为： `apiVersion 的 value/小写 kind 的 value`。 + +插件拥有自己的目录不但可以保存插件代码，还可以保存在测试以及任何可能需要的补充数据文件。 + +## 编写插件 + +插件有 _exec_ 和 _Go_ 两种. + +编写一个 _exec_ 插件，将其安装到正确的目录，文件名必须与插件的类型匹配（在本例中为 `SillyConfigMapGenerator`）： + +``` +cat <<'EOF' >$MY_PLUGIN_DIR/SillyConfigMapGenerator +#!/bin/bash +# Skip the config file name argument. +shift +today=`date +%F` +echo " +kind: ConfigMap +apiVersion: v1 +metadata: + name: the-map +data: + today: $today + altGreeting: "$1" + enableRisky: "$2" +" +EOF +``` + +根据定义，_exec_ 插件必须是可执行的： + +``` +chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator +``` + +## 安装 kustomize + +根据[文档](INSTALL.md)安装 kustomize: + +``` +curl -s "https://raw.githubusercontent.com/\ +kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash +mkdir -p $DEMO/bin +mv kustomize $DEMO/bin +``` + +## 检查这个目录 + +``` +tree $DEMO +``` + +## 使用插件构建 APP: + +``` +XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP +``` + +之前如果您已经设置了 `PLUGIN_ROOT=$HOME/.config/kustomize/plugin`，则无需在 _kustomize_ 命令前使用 `XDG_CONFIG_HOME`。 diff --git a/docs/zh/goPluginCaveats.md b/docs/zh/goPluginCaveats.md new file mode 100644 index 000000000..548f1dffc --- /dev/null +++ b/docs/zh/goPluginCaveats.md @@ -0,0 +1,66 @@ +[plugin package]: https://golang.org/pkg/plugin +[Go modules]: https://github.com/golang/go/wiki/Modules +[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format +[tensorflow plugin]: https://www.tensorflow.org/guide/extend/op + +# Go plugin 注意事项 + +_Go 插件_ 是由 Go [plugin package] 描述的编译器，需要特殊的构建标志，不能单独运行，必须加载到正在运行的 Go 程序中。 + +> 用 Go 编写的普通程序可以作为 _exec 插件_，但是不能作为 _Go 插件_。 + +Go 插件允许运行 kustomize 扩展，而无需在每次运行时将资源分配到子流程或从子流程中解封所有资源数据。Go 插件 API 确保一定程度的一致性，以避免混淆下游转换器。 + +Go 插件的工作方式与 [plugin package] 中所述的相同，但与 _plugin_ 一词相关的常见概念不同。 + +## The skew problem + +Go 插件编译会创建一个 [ELF] 格式的 `.so` 文件，根据定义，该文件不包含有关目标代码来源的信息。 + +主程序 ELF 和插件 ELF 的编译条件（软件包依赖项的版本 `GOOS`，`GOARCH`）之间的偏移会导致插件加载失败，并带有无用的错误消息。 + +Exec 插件也会缺乏出处，但不会因编译不正确而失败。 + +在任何情况下，共享插件的最好方法是使用某种 _捆绑包_（git repo URL、git 存档文件、tar 包等），其中包含可在下解包的源代码，测试和相关数据 `$XDG_CONFIG_HOME/kustomize/plugin`。 + +对于 Go 插件，使用共享插件的最终用户 _必须同时编译 kustomize 和 plugin_。 + +这意味着一次性运行 + +``` +# Or whatever is appropriate at time of reading +GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api +``` + +然后使用一个正常的开发周期 + +``` +go build -buildmode plugin \ + -o ${wherever}/${kind}.so ${wherever}/${kind}.go +``` + +并根据需要调整路径和发行版本标记（例如 `v3.0.0`）。 + +为了进行比较，可以参考编写 [tensorflow plugin] 必须做的事情。 + +## 为什么支持 Go 插件？ + +### 安全 + +Go 插件开发者可以操作与原生 kustomize 操作相同的 API，可确保某些语义、变量和检查等一致。通过stdin/stdout 处理此问题的 exec 插件子流程将使下游转换器和使用者解决问题变得更容易。 + +关键点：如果插件通过 kustomize 提供的文件 `Loader` 接口读取文件，则会受到 kustomize 文件加载限制的约束。当然，除了代码审核之外，没有什么可以阻止 Go 插件导入 io 包并执行其所需的任何操作。 + +### Debugging + +Go 插件开发者可以在功能测试中运行插件时，在 _本地_ 调试插件，并在插件内部和其他位置设置断点。 + +为了获得两全其美的方式（共享性和安全性），开发人员可以编写一个 `.go` 程序作为 _exec 插件_，但可以通过处理该程序 `go generate` 来发出 Go 插件（反之亦然）。 + +### 贡献单元化 + +所有内置的生成器和转换器本身都是 Go 插件。这意味着 kustomize 维护者可以将贡献的插件升级为内置插件，而无需更改代码（超出常规代码审阅要求的范围）。 + +### 围绕生态系统发展 + +工具可以简化 Go 插件的 _共享_，但是这需要大量的 Go 插件的创作，而这又会导致围绕共享插件的混乱。[Go modules] 一旦被更广泛地采用，将解决共享插件最大的难题：含糊不清的插件 vs 主机依赖性。 diff --git a/docs/zh/goPluginGuidedExample.md b/docs/zh/goPluginGuidedExample.md new file mode 100644 index 000000000..0c212f860 --- /dev/null +++ b/docs/zh/goPluginGuidedExample.md @@ -0,0 +1,300 @@ +# 60 秒构建一个 Go 插件 + +[SopsEncodedSecrets repository]: https://github.com/monopole/sopsencodedsecrets +[Go plugin]: https://golang.org/pkg/plugin +[Go plugin caveats]: goPluginCaveats.md + +本教程只是一个快速开始的示例，完整的插件文档请看：[kustomize 插件](plugins.md) + +请务必阅读 [Go plugin 注意事项](goPluginCaveats.md)。 + +该示例使用 Go 插件，`SopsEncodedSecrets` 该插件位于 [sopsencodedsecrets repository]中。这是一个进程内的 Go 插件，而不是恰巧用 Go 编写的 exec 插件（这是 Go 作者的另一种选择）。 + +在不破坏当前的设置的情况下，尝试本教程。 + +#### 环境要求 + +* `linux` +* `git` +* `curl` +* `Go 1.13` + +用于加密 + +* gpg + +或 + +* Google cloud (gcloud) 安装 +* 具有 KMS 权限的 Google帐户 + +## 定义一个工作空间 + +```shell +# 将这些目录分开，以免造成 DEMO 目录的混乱。 +DEMO=$(mktemp -d) +tmpGoPath=$(mktemp -d) +``` + +## 安装 kustomize + +需要安装 kustomize v3.0.0，并且必须对其进行 _编译_（而不是从 release 页面下载二进制文件）： + +```shell +GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize +``` + +## 为插件创建目录 + +kustomize 插件完全由其配置文件和源代码确定。 + +Kustomize 插件的配置文件的格式与 kubernetes 资源对象相同，这就意味着在配置文件中 `apiVersion`，`kind` 和 `metadata` 都是[必须的字段](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)。 + +因为配置文件名出现在 kustomization 文件的 `generatorsor` 或 `transformers` 字段中，kustomize 会读取配置文件，然后在以下位置找到 Go 插件的目标代码： + +> ```shell +> $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so +> ``` + +`lKind` 必须是小写字母的，然后将插件加载并提供其配置，插件的输出将成为整个 `kustomize build` 程序的一部分 。 + +同一插件在一个 kustomize 构建中可能会多次使用不同的配置文件。此外，kustomize 可能会先自定义 config 数据，然后再发送给插件。由于这些原因，插件不能自己去读取配置文件，而需要通过 kustomize 来读取配置。 + +该示例将在如下临时目录中存放其使用的插件： + +```shell +PLUGIN_ROOT=$DEMO/kustomize/plugin +``` + +并在下面的命令行中临时设置 `XDG_CONFIG_HOME`。 + +### What apiVersion and kind? + +在 kustomize 插件的开发时，插件代码不关心也不知道配置文件中的 `apiVersion` 或 `kind`。 + +插件会检查这些字段，但是剩下的字段提供了实际的配置数据，在这一点上，成功解析其他字段对于插件很重要。 + +本示例使用一个名为 _SopsEncodedSecrets_ 的插件，其位于 [SopsEncodedSecrets repository] 中。 + +我们选择安装插件到 + +```shell +apiVersion=mygenerators +kind=SopsEncodedSecrets +``` + +### 定义插件的主目录 + +按照惯例，存放插件代码和补充数据，测试，文档等的目录名称必须是 kind 的小写形式。 + +```shell +lKind=$(echo $kind | awk '{print tolower($0)}') +``` + +### 下载 SopsEncodedSecrets 插件 + +在这种情况下，存储库名称已经与小写字母的 kind 匹配，因此我们只需克隆存储库并自动获取正确的目录名称即可： + +```shell +mkdir -p $PLUGIN_ROOT/${apiVersion} +cd $PLUGIN_ROOT/${apiVersion} +git clone git@github.com:monopole/sopsencodedsecrets.git +``` + +记住这个目录： + +```shell +MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind} +``` + +### 尝试测试插件 + +插件可能会自己带有测试文件。因此可以通过如下方式： + +```shell +cd $MY_PLUGIN_DIR +go test SopsEncodedSecrets_test.go +``` + +构建对象代码以供 kustomize 使用： + +```shell +cd $MY_PLUGIN_DIR +GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go +``` + +此步骤可能会成功，但是由于依赖关系 [skew]，kustomize 最终可能无法加载该插件。 + +[skew]: /docs/plugins/README.md#caveats + +在加载失败时 + + * 确保使用相同版本的Go (_go1.13_)，在相同的 `$GOOS`(_linux_)和 `$GOARCH`(_amd64_) 上构建插件，用于构建本演示中使用的 [kustomize](#安装-kustomize)。 + + * 修改插件中的依赖文件 `go.mod` 以匹配 kustomize 使用的版本。 + +缺乏工具和元数据来实现自动化，就不会有一个完整的 Go 插件生态。 + +Kustomize 采用了 Go 插件架构，可以轻松的接受新的生成器和转换器（只需编写一个插件），并确保本机操作（也已作为插件构建和测试）是分段的、可排序的和可重用的，而不是奇怪的插入在整体代码中。 + +## 编写 kustomization + +新建一个 kustomization 目录存放你的配置： + +```shell +MYAPP=$DEMO/myapp +mkdir -p $MYAPP +``` + +为 SopsEncodedSecrets 插件编写一个配置文件。 + +插件可以通过 `apiVersion` 和 `kind` 找到： + +```shell +cat <$MYAPP/secGenerator.yaml +apiVersion: ${apiVersion} +kind: ${kind} +metadata: + name: mySecretGenerator +name: forbiddenValues +namespace: production +file: myEncryptedData.yaml +keys: +- ROCKET +- CAR +EOF +``` + +插件可以在 `myEncryptedData.yaml` 中找到更多的数据。 + +编写一个引用插件配置的 kustomization 文件： + +```shell +cat <$MYAPP/kustomization.yaml +commonLabels: + app: hello +generators: +- secGenerator.yaml +EOF +``` + +现在生成真实的加密数据了。 + +### 确保您已安装加密工具 + +我们将使用 [sops](https://github.com/mozilla/sops) 对文件进行编码。选择 GPG 或 Google Cloud KMS 作为加密提供者以继续。 + +#### GPG + +尝试这个命令： + +```shell +gpg --list-keys +``` + +如果返回 list，则您已经成功创建了密钥。如果不是，请尝试从 sops 导入测试密钥。 + +```shell +curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import +SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A" +``` + +#### Google Cloude KMS + +尝试这个命令： + +```shell +gcloud kms keys list --location global --keyring sops +``` + +如果成功了，想必你已经创建了密钥，并将其放置在一个名为 sops 的钥匙圈中。如果没有，那就这样做： + +```shell +gcloud kms keyrings create sops --location global +gcloud kms keys create sops-key --location global \ + --keyring sops --purpose encryption +``` + +通过如下方法，获取你的 keyLocation： + +```shell +keyLocation=$(\ + gcloud kms keys list --location global --keyring sops |\ + grep GOOGLE | cut -d " " -f1) +echo $keyLocation +``` + +### 安装 `sops` + +```shell +GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops +``` + +### 用你的私钥创建加密数据 + +创建需要加密的原始数据： + +```shell +cat <$MYAPP/myClearData.yaml +VEGETABLE: carrot +ROCKET: saturn-v +FRUIT: apple +CAR: dymaxion +EOF +``` + +将数据加密插入到插件要读取的文件中： + +使用 PGP + +```shell +$tmpGoPath/bin/sops --encrypt \ + --pgp $SOPS_PGP_FP \ + $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml +``` + +或者使用 GCP KMS + +```shell +$tmpGoPath/bin/sops --encrypt \ + --gcp-kms $keyLocation \ + $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml +``` + +查看文件 + +```shell +tree $DEMO +``` + +结果如下： + +> ```shell +> /tmp/tmp.0kIE9VclPt +> ├── kustomize +> │   └── plugin +> │   └── mygenerators +> │   └── sopsencodedsecrets +> │   ├── go.mod +> │   ├── go.sum +> │   ├── LICENSE +> │   ├── README.md +> │   ├── SopsEncodedSecrets.go +> │   ├── SopsEncodedSecrets.so +> │   └── SopsEncodedSecrets_test.go +> └── myapp +> ├── kustomization.yaml +> ├── myClearData.yaml +> ├── myEncryptedData.yaml +> └── secGenerator.yaml +> ``` + +## 使用插件构建您的应用： + +```shell +XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP +``` + +这将生成一个 kubernetes secret，并对名称 `ROCKET` 和 `CAR` 的数据进行加密。 + +之前如果您已经设置了 `PLUGIN_ROOT=$HOME/.config/kustomize/plugin`，则无需在 _kustomize_ 命令前使用 `XDG_CONFIG_HOME`。 diff --git a/docs/zh/plugins.md b/docs/zh/plugins.md index 1ed88fe65..ee2fb416f 100644 --- a/docs/zh/plugins.md +++ b/docs/zh/plugins.md @@ -2,8 +2,8 @@ 快速开始： -* [60 秒构建一个 exec 插件](../plugins/execPluginGuidedExample.md) -* [60 秒构建一个 Go 插件](../plugins/goPluginGuidedExample.md) +* [60 秒构建一个 exec 插件](execPluginGuidedExample.md) +* [60 秒构建一个 Go 插件](goPluginGuidedExample.md) Kustomize 提供一个插件框架，允许用户开发自己的 _生成器_ 和 _转化器_。 @@ -196,7 +196,7 @@ data: ### Go 插件 -请务必阅读 [Go plugin 注意事项](../plugins/goPluginCaveats.md)。 +请务必阅读 [Go plugin 注意事项](goPluginCaveats.md)。 [Go 插件]: https://golang.org/pkg/plugin/