Go 插件示例

Go 插件示例

本教程只是一个快速开始的示例,完整的插件文档请看:kustomize 插件

请务必阅读 Go 插件注意事项

该示例使用 Go 插件 SopsEncodedSecrets,该插件位于 sopsencodedsecrets repository中。这是一个进程内的 Go 插件,而不是恰巧用 Go 编写的 exec 插件(这是 Go 作者的另一种选择)。

尝试本教程不会破坏你的当前设置。

环境要求

  • linux
  • git
  • curl
  • Go 1.13

用于加密

  • gpg

  • Google cloud (gcloud) 安装
  • 具有 KMS 权限的 Google帐户

创建一个工作空间/目录

  1. # 将这些目录分开,以免造成 DEMO 目录的混乱。
  2. DEMO=$(mktemp -d)
  3. tmpGoPath=$(mktemp -d)

安装 kustomize

需要安装 kustomize v3.0.0,并且必须对其进行 编译(而不是从 release 页面下载二进制文件):

  1. GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize

为插件创建目录

kustomize 插件完全由其配置文件和源代码确定。

Kustomize 插件的配置文件的格式与 kubernetes 资源对象相同,这就意味着在配置文件中 apiVersionkindmetadata 都是必须的字段

因为配置文件名出现在 kustomization 文件的 generatorsortransformers 字段中,kustomize 会读取配置文件,然后在以下位置找到 Go 插件的目标代码:

  1. $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so

lKind 必须是小写字母的,然后将插件加载并提供其配置,插件的输出将成为整个 kustomize build 程序的一部分 。

同一插件在一个 kustomize 构建中可能会多次使用不同的配置文件。此外,kustomize 可能会先自定义 config 数据,然后再发送给插件。由于这些原因,插件不能自己去读取配置文件,而需要通过 kustomize 来读取配置。

该示例将在如下临时目录中存放其使用的插件:

  1. PLUGIN_ROOT=$DEMO/kustomize/plugin

并在下面的命令行中临时设置 XDG_CONFIG_HOME

使用什么 apiVersion 和 kind

在 kustomize 插件的开发时,插件代码不关心也不知道配置文件中的 apiVersionkind

插件会检查这些字段,但是剩下的字段提供了实际的配置数据,在这一点上,成功解析其他字段对于插件很重要。

本示例使用一个名为 SopsEncodedSecrets 的插件,其位于 SopsEncodedSecrets repository 中。

我们选择安装插件到

  1. apiVersion=mygenerators
  2. kind=SopsEncodedSecrets

定义插件的主目录

按照惯例,存放插件代码和补充数据,测试,文档等的目录名称必须是 kind 的小写形式。

  1. lKind=$(echo $kind | awk '{print tolower($0)}')

下载 SopsEncodedSecrets 插件

在这种情况下,存储库名称已经与小写字母的 kind 匹配,因此我们只需克隆存储库并自动获取正确的目录名称即可:

  1. mkdir -p $PLUGIN_ROOT/${apiVersion}
  2. cd $PLUGIN_ROOT/${apiVersion}
  3. git clone git@github.com:monopole/sopsencodedsecrets.git

记住这个目录:

  1. MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind}

尝试测试插件

插件可能会自己带有测试文件。因此可以通过如下方式:

  1. cd $MY_PLUGIN_DIR
  2. go test SopsEncodedSecrets_test.go

构建对象代码以供 kustomize 使用:

  1. cd $MY_PLUGIN_DIR
  2. GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go

此步骤可能会成功,但是由于依赖关系 skew,kustomize 最终可能无法加载该插件。

在加载失败时

  • 确保使用相同版本的Go (go1.13),在相同的 $GOOS(linux)和 $GOARCH(amd64) 上构建插件,用于构建本演示中使用的 kustomize

  • 修改插件中的依赖文件 go.mod 以匹配 kustomize 使用的版本。

缺乏工具和元数据来实现自动化,就不会有一个完整的 Go 插件生态。

Kustomize 采用了 Go 插件架构,可以轻松的接受新的生成器和转换器(只需编写一个插件),并确保本机操作(也已作为插件构建和测试)是分段的、可排序的和可重用的,而不是奇怪的插入在整体代码中。

编写 kustomization

新建一个 kustomization 目录存放你的配置:

  1. MYAPP=$DEMO/myapp
  2. mkdir -p $MYAPP

为 SopsEncodedSecrets 插件编写一个配置文件。

插件可以通过 apiVersionkind 找到:

  1. cat <<EOF >$MYAPP/secGenerator.yaml
  2. apiVersion: ${apiVersion}
  3. kind: ${kind}
  4. metadata:
  5. name: mySecretGenerator
  6. name: forbiddenValues
  7. namespace: production
  8. file: myEncryptedData.yaml
  9. keys:
  10. - ROCKET
  11. - CAR
  12. EOF

插件可以在 myEncryptedData.yaml 中找到更多的数据。

编写一个引用插件配置的 kustomization 文件:

  1. cat <<EOF >$MYAPP/kustomization.yaml
  2. commonLabels:
  3. app: hello
  4. generators:
  5. - secGenerator.yaml
  6. EOF

接下来生成真实的加密数据。

确保您已安装加密工具

我们将使用 sops 对文件进行编码。选择 GPG 或 Google Cloud KMS 作为加密提供者以继续。

GPG

尝试这个命令:

  1. gpg --list-keys

如果返回 list,则您已经成功创建了密钥。如果不是,请尝试从 sops 导入测试密钥。

  1. curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import
  2. SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A"

Google Cloude KMS

尝试这个命令:

  1. gcloud kms keys list --location global --keyring sops

如果成功了,想必你已经创建了密钥,并将其放置在一个名为 sops 的钥匙圈中。如果没有,那就这样做:

  1. gcloud kms keyrings create sops --location global
  2. gcloud kms keys create sops-key --location global \
  3. --keyring sops --purpose encryption

通过如下方法,获取你的 keyLocation:

  1. keyLocation=$(\
  2. gcloud kms keys list --location global --keyring sops |\
  3. grep GOOGLE | cut -d " " -f1)
  4. echo $keyLocation

安装 sops

  1. GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops

用你的私钥创建加密数据

创建需要加密的原始数据:

  1. cat <<EOF >$MYAPP/myClearData.yaml
  2. VEGETABLE: carrot
  3. ROCKET: saturn-v
  4. FRUIT: apple
  5. CAR: dymaxion
  6. EOF

将数据加密插入到插件要读取的文件中:

使用 PGP

  1. $tmpGoPath/bin/sops --encrypt \
  2. --pgp $SOPS_PGP_FP \
  3. $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml

或者使用 GCP KMS

  1. $tmpGoPath/bin/sops --encrypt \
  2. --gcp-kms $keyLocation \
  3. $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml

查看文件

  1. tree $DEMO

结果如下:

  1. /tmp/tmp.0kIE9VclPt
  2. ├── kustomize
  3. └── plugin
  4. └── mygenerators
  5. └── sopsencodedsecrets
  6. ├── go.mod
  7. ├── go.sum
  8. ├── LICENSE
  9. ├── README.md
  10. ├── SopsEncodedSecrets.go
  11. ├── SopsEncodedSecrets.so
  12. └── SopsEncodedSecrets_test.go
  13. └── myapp
  14. ├── kustomization.yaml
  15. ├── myClearData.yaml
  16. ├── myEncryptedData.yaml
  17. └── secGenerator.yaml

使用插件构建您的应用

  1. XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP

这将生成一个 kubernetes secret,并对名称 ROCKETCAR 的数据进行加密。

之前如果您已经设置了 PLUGIN_ROOT=$HOME/.config/kustomize/plugin,则无需在 kustomize 命令前使用 XDG_CONFIG_HOME