viaductoss/ksops Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

KSOPS - 一个灵活的Kustomize插件，用于SOPS加密资源

![Dependabot Status]([***] !测试与构建

• 背景
• 概述
• 依赖要求
• 使用示例
• 生成器选项
• 开发与测试
• Argo CD集成 🤖

背景

在Viaduct，我们通过GitOps模式管理Kubernetes资源；然而，我们未能找到与我们技术栈兼容的解决方案，用于通过GitOps范式管理密钥。因此，我们开发了KSOPS，将kustomize与SOPS连接，并与Argo CD集成，以与管理其他Kubernetes清单相同的方式安全管理密钥。

概述

KSOPS（即kustomize-SOPS）是一个用于SOPS加密资源的kustomize插件。它可用于解密任何Kubernetes资源，但最常用于解密加密的Kubernetes Secrets和ConfigMaps。作为kustomize插件，KSOPS允许您以管理其他Kubernetes清单相同的方式管理、构建和应用加密清单。

依赖要求

• Go
• 使用Go构建的kustomize（详见下文kustomize Go插件注意事项）
• SOPS
• gpg

使用示例

1. 下载KSOPS

bash
# export GO111MODULE=on
go get -u github.com/viaduct-ai/kustomize-sops
# 进入根目录
cd $GOPATH/src/github.com/viaduct-ai/kustomize-sops

2. 通过Go安装（或重新安装）最新版kustomize

bash
# KSOPS基于最新版kustomize构建
# 如需更改版本，更新安装脚本中的目标版本，并确保KSOPS测试仍能通过
# 如需使用低于kustomize v3.3.0的版本，请使用KSOPS v1.0或go-1.12版本！
make kustomize

3. 设置kustomize插件路径

bash
# 不要忘记在.bashrc/.zshrc中定义XDG_CONFIG_HOME
echo "export XDG_CONFIG_HOME=\$HOME/.config" >> $HOME/.bashrc
source $HOME/.bashrc

4. 构建并安装KSOPS插件

bash
make install

5. 导入测试PGP密钥

为简化本地开发和测试，我们使用PGP测试密钥。如需导入密钥，运行以下命令：

bash
make import-test-keys

如果您正在按照本教程操作，请在后续步骤前运行此命令。运行make test时也会自动导入PGP密钥。

详见SOPS文档。

6. 通过.sops.yaml配置SOPS

本示例和测试中，KSOPS依赖.sops.yaml中定义的SOPS创建规则。为提高加密密钥的可读性，建议使用以下加密正则表达式仅加密data和stringData值，使非敏感字段（如密钥名称）保持未加密状态，便于人工阅读。

注意：仅当您希望在此示例中使用密钥管理服务而非上一步导入的默认PGP密钥时，才需要修改.sops.yaml。

yaml
creation_rules:
  - encrypted_regex: '^(data|stringData)

### 7. 创建资源

```bash
# 创建本地Kubernetes密钥
cat <<EOF > secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  username: YWRtaW4=
  password: MWYyZDFlMmU2N2Rm
EOF

8. 加密资源

bash
# 使用SOPS CLI加密
# 在.sops.yaml中指定SOPS配置
sops -e secret.yaml > secret.enc.yaml

9. 定义KSOPS kustomize生成器

bash
# 创建KSOPS生成器配置
cat <<EOF > secret-generator.yaml
apiVersion: viaduct.ai/v1
kind: ksops
metadata:
  # 指定名称
  name: example-secret-generator
files:
  - ./secret.enc.yaml
EOF

10. 创建kustomization.yaml

了解kustomize插件

bash
cat <<EOF > kustomization.yaml
generators:
  - ./secret-generator.yaml
EOF

11. 使用kustomize构建 🔑

bash
# 使用kustomize构建以验证
kustomize build --enable_alpha_plugins .

故障排除

kustomize Go插件注意事项

kustomize Go插件详细示例

检查清单

• 验证ksops.so是否位于kustomize插件路径中
  • $XDG_CONFIG_HOME/kustomize/plugin/viaduct.ai/v1/ksops/ksops.so
• 检查kustomize可执行文件是否由Go构建
  • which kustomize
  • kustomize version
• 检查go.mod中的Go版本与构建kustomize所用的Go版本是否匹配
• 检查go.mod中指定的kustomize版本与已安装的kustomize版本是否匹配
  • kustomize version

查看现有问题

您遇到的问题可能已有解决方案。

[***]

生成器选项

KSOPS支持与kustomize执行插件相同的基于注解的生成器选项。支持的注解包括：

• kustomize.config.k8s.io/needs-hash
• kustomize.config.k8s.io/behavior

详见kustomize执行插件生成器选项文档。

开发与测试

在开发或测试KSOPS前，请确保所有外部依赖要求已正确安装。

bash
# 设置开发环境
make setup

开发

KSOPS在ksops.go中实现了kustomize插件API。

KSOPS的逻辑设计简洁：给定SOPS加密的Kubernetes清单列表，它会遍历每个文件并通过SOPS decrypt库解密。KSOPS不对加密资源的结构做任何假设，依赖kustomize进行清单验证。KSOPS要求加密密钥可访问，这在CI/CD中使用KSOPS时需特别注意。

测试

测试KSOPS需执行以下步骤：

1. 在.sops.yaml中配置加密密钥及其他SOPS配置
2. 将KSOPS构建为Go插件
3. 将Go插件复制到kustomize插件路径
4. 生成加密测试文件
5. 运行Go测试

除设置.sops.yaml外，make test命令会处理其他所有步骤。定义.sops.yaml后，从仓库根目录运行以下命令测试KSOPS：

bash
make test

Argo CD集成 🤖

将KSOPS与CI/CD流水线集成后功能更强大。通过结合KSOPS与Argo CD，您可以使用与管理其他Kubernetes清单相同的GitOps模式管理Kubernetes密钥。如需集成KSOPS和Argo CD，需更新Argo CD配置映射，并创建策略合并补丁或自定义Argo CD构建。部署Argo CD + KSOPS构建时，不要忘记注入必要的凭据（如AWS凭据）！

KSOPS Docker镜像

通过Argo CD配置映射启用Kustomize插件

目前，如需允许Argo CD使用kustomize插件，必须使用enable_alpha_plugins标志。这可通过Argo CD配置映射中的kustomize.buildOptions设置实现。

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  labels:
    app.kubernetes.io/name: argocd-cm
    app.kubernetes.io/part-of: argocd
data:
  kustomize.buildOptions: "--enable_alpha_plugins"

KSOPS Repo Server补丁

将KSOPS与Argo CD集成的最简单方法是对Argo CD repo server部署应用策略合并补丁。以下补丁使用初始化容器构建KSOPS和kustomize，并通过卷挂载注入KSOPS插件和覆盖kustomize可执行文件。

yaml
# argo-cd-repo-server-ksops-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
spec:
  template:
    spec:
      # 1. 定义emptyDir卷以存放自定义二进制文件
      volumes:
        - name: custom-tools
          emptyDir: {}
      # 2. 使用初始化容器下载/复制自定义二进制文件到emptyDir
      initContainers:
        - name: install-ksops
          # 匹配Argo CD Go版本
          image: viaductoss/ksops:v2.1.2-go-1.14
          command: ["/bin/sh", "-c"]
          args:
            - echo "安装KSOPS中...";
              export PKG_NAME=ksops;
              mv ${PKG_NAME}.so /custom-tools/;
              mv $GOPATH/bin/kustomize /custom-tools/;
              echo "完成。";
          volumeMounts:
            - mountPath: /custom-tools
              name: custom-tools
      # 3. 将自定义二进制文件卷挂载到bin目录（覆盖现有版本）
      containers:
        - name: argocd-repo-server
          volumeMounts:
            - mountPath: /usr/local/bin/kustomize
              name: custom-tools
              subPath: kustomize
              # 确保与XDG_CONFIG_HOME=/.config环境变量匹配
            - mountPath: /.config/kustomize/plugin/viaduct.ai/v1/ksops/ksops.so
              name: custom-tools
              subPath: ksops.so
          # 4. 设置XDG_CONFIG_HOME环境变量，使kustomize能检测到插件
          env:
            - name: XDG_CONFIG_HOME
              value: /.config
        ## 如使用AWS或GCP KMS，不要忘记包含解密密钥所需的凭据！
        #  - name: AWS_ACCESS_KEY_ID
        #    valueFrom:
        #      secretKeyRef:
        #        name: argocd-aws-credentials
        #        key: accesskey
        #  - name: AWS_SECRET_ACCESS_KEY
        #    valueFrom:
        #      secretKeyRef:
        #        name: argocd-aws-credentials
        #        key: secretkey

自定义Argo CD集成KSOPS的Dockerfile

或者，为获得更多控制权和更快的Pod启动时间，可构建自定义Docker镜像。

Dockerfile
ARG ARGO_CD_VERSION="v1.5.5"
# 始终匹配Argo CD Dockerfile的Go版本！
# [***]
ARG KSOPS_VERSION="v2.1.2-go-1.14"

#--------------------------------------------#
#--------构建KSOPS和Kustomize----------------#
#--------------------------------------------#

FROM viaductoss/ksops:$KSOPS_VERSION as ksops-builder

#--------------------------------------------#
#--------构建自定义Argo镜像------------------#
#--------------------------------------------#

FROM argoproj/argocd:$ARGO_CD_VERSION

# 切换到root用户以执行安装操作
USER root

# 设置kustomize主目录
ENV XDG_CONFIG_HOME=$HOME/.config
ENV KUSTOMIZE_PLUGIN_PATH=$XDG_CONFIG_HOME/kustomize/plugin/

ARG PKG_NAME=ksops

# 用Go构建的版本覆盖默认kustomize可执行文件
COPY --from=ksops-builder /go/bin/kustomize /usr/local/bin/kustomize

# 将插件复制到kustomize插件路径
COPY --from=ksops-builder /go/src/github.com/viaduct-ai/kustomize-sops/*  $KUSTOMIZE_PLUGIN_PATH/viaduct.ai/v1/${PKG_NAME}/

# 切换回非root用户
USER argocd
   # 指定kms/pgp等加密密钥
   # 本教程使用本地PGP密钥进行加密
   # 生产环境请勿使用
   pgp: 'FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4'
   # 可选：配置使用提供商的密钥存储
   # kms: XXXXXX
   # gcp_kms: XXXXXX

7. 创建资源

CODE_TOKEN_6

8. 加密资源

CODE_TOKEN_7

9. 定义KSOPS kustomize生成器

CODE_TOKEN_8

10. 创建kustomization.yaml

了解kustomize插件

CODE_TOKEN_9

11. 使用kustomize构建 🔑

CODE_TOKEN_10

故障排除

kustomize Go插件注意事项

kustomize Go插件详细示例

检查清单

• 验证__CODE_TOKEN_24__是否位于kustomize插件路径中
  • CODE_TOKEN_25
• 检查kustomize可执行文件是否由Go构建
  • CODE_TOKEN_26
  • CODE_TOKEN_27
• 检查__CODE_TOKEN_28__中的Go版本与构建kustomize所用的Go版本是否匹配
• 检查__CODE_TOKEN_29__中指定的kustomize版本与已安装的kustomize版本是否匹配
  • CODE_TOKEN_30

查看现有问题

您遇到的问题可能已有解决方案。

[***]

生成器选项

__CODE_TOKEN_31__支持与kustomize执行插件相同的基于注解的生成器选项。支持的注解包括：

• CODE_TOKEN_32
• CODE_TOKEN_33

详见kustomize执行插件生成器选项文档。

开发与测试

在开发或测试__CODE_TOKEN_34__前，请确保所有外部依赖要求已正确安装。 CODE_TOKEN_11

开发

__CODE_TOKEN_35__在__CODE_TOKEN_36__中实现了kustomize插件API。

__CODE_TOKEN_37__的逻辑设计简洁：给定SOPS加密的Kubernetes清单列表，它会遍历每个文件并通过SOPS decrypt库解密。__CODE_TOKEN_38__不对加密资源的结构做任何假设，依赖kustomize进行清单验证。__CODE_TOKEN_39__要求加密密钥可访问，这在CI/CD中使用__CODE_TOKEN_40__时需特别注意。

测试

测试__CODE_TOKEN_41__需执行以下步骤：

1. 在__CODE_TOKEN_42__中配置加密密钥及其他SOPS配置
2. 将__CODE_TOKEN_43__构建为Go插件
3. 将Go插件复制到kustomize插件路径
4. 生成加密测试文件
5. 运行Go测试

除设置__CODE_TOKEN_44__外，CODE_TOKEN_45__命令会处理其他所有步骤。定义__CODE_TOKEN_46__后，从仓库根目录运行以下命令测试__CODE_TOKEN_47：

CODE_TOKEN_12

Argo CD集成 🤖

将__CODE_TOKEN_48__与CI/CD流水线集成后功能更强大。通过结合__CODE_TOKEN_49__与Argo CD，您可以使用与管理其他Kubernetes清单相同的GitOps模式管理Kubernetes密钥。如需集成__CODE_TOKEN_50__和Argo CD，需更新Argo CD配置映射，并创建策略合并补丁或自定义Argo CD构建。部署Argo CD + __CODE_TOKEN_51__构建时，不要忘记注入必要的凭据（如AWS凭据）！

KSOPS Docker镜像

通过Argo CD配置映射启用Kustomize插件

目前，如需允许Argo CD使用kustomize插件，必须使用__CODE_TOKEN_52__标志。这可通过Argo CD配置映射中的__CODE_TOKEN_53__设置实现。

CODE_TOKEN_13

KSOPS Repo Server补丁

将__CODE_TOKEN_54__与Argo CD集成的最简单方法是对Argo CD repo server部署应用策略合并补丁。以下补丁使用初始化容器构建__CODE_TOKEN_55__和kustomize，并通过卷挂载注入__CODE_TOKEN_56__插件和覆盖kustomize可执行文件。

CODE_TOKEN_14

自定义Argo CD集成KSOPS的Dockerfile

或者，为获得更多控制权和更快的Pod启动时间，可构建自定义Docker镜像。

CODE_TOKEN_57`Dockerfile ARG ARGO_CD_VERSION="v1.5.5"

始终匹配Argo CD Dockerfile的Go版本！

[***]

ARG KSOPS_VERSION="v2.1.2-go-1.14"

#--------------------------------------------# #--------构建KSOPS和Kustomize----------------# #--------------------------------------------#

FROM viaductoss/ksops:$KSOPS_VERSION as ksops-builder

#--------------------------------------------# #--------构建自定义Argo镜像------------------# #--------------------------------------------#

FROM argoproj/argocd:$ARGO_CD_VERSION

切换到root用户以执行安装操作

USER root

设置kustomize主目录

ENV XDG_CONFIG_HOME=$HOME/.config ENV KUSTOMIZE_PLUGIN_PATH=$XDG_CONFIG_HOME/kustomize/plugin/

ARG PKG_NAME=ksops

用Go构建的版本覆盖默认kustomize可执行文件

COPY --from=ksops-builder /go/bin/kustomize /usr/local/bin/kustomize

将插件复制到kustomize插件路径

COPY --from=ksops-builder /go/src/github.com/viaduct-ai/kustomize-sops/* $KUSTOMIZE_PLUGIN_PATH/viaduct.ai/v1/${PKG_NAME}/

切换回非root用户

USER argocd