sealed-secrets 开发者指南从开发环境搭建到 Controller/Kubeseal 构建测试与 git-hooks 规范【免费下载链接】sealed-secretsA Kubernetes controller and tool for one-way encrypted Secrets项目地址: https://gitcode.com/GitHub_Trending/se/sealed-secrets本文以仓库 docs/developer/README.md 为主干结合 controller.md、kubeseal.md、Makefile 及核心源码系统梳理 Sealed Secrets 项目的本地开发流程环境依赖、两大可执行组件的源码布局、完整测试链路单元测试 → 构建镜像 → 部署清单 → 集成测试以及通过 git-hooks 自动化维护文档目录TOC的工程规范。读完本文你将能够在一台装有 Go 与 Docker 的机器上独立完成 controller 与 kubeseal 的编译、在 minikube/kind 上跑通端到端集成测试并掌握仓库文档维护的提交前校验流程。Sealed Secrets 的三大组成部分Sealed Secrets 由三个部分协同工作见 docs/developer/README.md自定义资源CRD名为SealedSecret的 Kubernetes Custom Resource其 API 定义位于 pkg/apis/sealedsecrets/v1alpha1/types.go对应的 CRD 清单为 helm/sealed-secrets/crds/bitnami.com_sealedsecrets.yaml。集群侧 controller / operator负责让SealedSecret对象的当前状态持续与声明式期望状态保持同步。客户端工具 kubeseal使用非对称加密asymmetric crypto对 Secret 加密且只有集群内的 controller 能解密。开发者通常围绕 controller 与 kubeseal 两条主线展开工作两条线都遵循下载源码 → 编译 → 测试的循环。开发前置条件Prerequisites要在本地开发本项目需要预先安装以下工具均来自 docs/developer/README.md 的 Prerequisites 清单Git版本管理。Make项目构建入口仓库根目录的 Makefile 定义了controller、kubeseal、test、integrationtest等全部目标。Go 编程语言项目主体语言go.mod位于仓库根目录。Docker CE用于构建 controller 容器镜像。Kubernetes 集群v1.16运行集成测试所需文档推荐使用 Minikube也可使用 kind。Kubecfg用于将仓库根目录的.jsonnet控制器清单controller.jsonnet、controller-norbac.jsonnet 等渲染为 YAML。Ginkgo集成测试框架对应 Makefile 中的GINKGO ginkgo -p。git-hooks第三方 Git hooks 管理工具用于安装仓库内预置的提交钩子。doctoc为 Markdown 文档自动生成/更新 Table of Contents 的工具。其中 Go、Docker 和集群环境是构建与集成测试的硬性前提Kubecfg、Ginkgo 仅在执行 manifest 渲染与集成测试时使用git-hooks 与 doctoc 服务于文档工程规范。组件一Controller 开发指南controller 的职责是保持SealedSecret对象当前状态与期望状态同步详见 controller.md。controller 对外暴露一个基于 Swagger/OpenAPI v3 规范定义的 API定义文件为 swagger.yml。获取源码与目录布局git clone https://github.com/bitnami/sealed-secrets.git $SEALED_SECRETS_DIRcontroller 源码位于cmd/controller/入口为 cmd/controller/main.go并复用pkg目录下的包。其中关键的实现包括参数绑定cmd/controller/main.go中bindControllerFlags绑定了--key-size、--key-renew-period、--key-ttl、--update-status等核心参数且所有参数支持通过SEALED_SECRETS_*环境变量注入pkg/flagenv与pkg/pflagenv。控制器主体pkg/controller/main.go中的Main()完成密钥注册、密钥轮换调度、informer 启动与 HTTP 服务启动的完整装配。密钥管理pkg/controller/keyregistry.go的KeyRegistry以 RSA 密钥对 X.509 证书为核心数据结构按指纹索引并维护mostRecentKey。密钥持久化pkg/controller/keys.go通过带sealedsecrets.bitnami.com/sealed-secrets-key: active标签的 TLS 类型 Secret 存储私钥与证书。HTTP APIpkg/controller/server.go暴露/healthz、/v1/verify、/v1/rotate、/v1/cert.pem以及:8081上的/metrics。搭建用于测试的 Kubernetes 集群集成测试需要一个 Kubernetes 集群。两种推荐方式方式一minikube复用本地 Docker daemonminikube start eval $(minikube docker-env)方式二kind搭配本地镜像仓库先在本地启动一个 registryexport LOCAL_REGISTRY_PORT5000 export LOCAL_REGISTRY_NAMEkind-registry docker run --rm -d -p 127.0.0.1:${LOCAL_REGISTRY_PORT}:5000 --name ${LOCAL_REGISTRY_NAME} registry:2再创建允许访问该 registry 的 kind 集群cat EOF | kind create cluster --name ${CLUSTER_NAME} --config- kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 containerdConfigPatches: - |- [plugins.io.containerd.grpc.v1.cri.registry.mirrors.localhost:${LOCAL_REGISTRY_PORT}] endpoint [http://${LOCAL_REGISTRY_NAME}:5000] EOF docker network connect kind ${LOCAL_REGISTRY_NAME}一条命令跑完所有 controller 测试Makefile 中的controller-tests目标由test push-controller apply-controller-manifests clean integrationtest串联而成一条命令即可完成单元测试 → 构建并推送镜像 → 应用清单 → 集成测试的完整链路make K8S_CONTEXTmytestk8s-context OSlinux ARCHamd64 controller-tests需要注意K8S_CONTEXT必须设置为指向目标测试集群的kubectlcontext 名称。OS与ARCH必须与测试集群所在节点的操作系统与架构一致例如linux/amd64。对于 kind 本地 registry 的组合需要额外指定REGISTRYmake K8S_CONTEXTkind REGISTRYlocalhost:5000 OSlinux ARCHamd64 controller-tests对于 minikube 则无需REGISTRY本地 Docker daemon 直接可达make K8S_CONTEXTminikube OSlinux ARCHamd64 controller-tests分步执行测试流程1. 构建 controller 二进制make controller该命令对应 Makefile 中的目标controller: $(GO_FILES) $(GO) build -o $ $(GO_FLAGS) -ldflags $(GO_LD_FLAGS) ./cmd/controller产物controller二进制会生成在当前工作目录GO_LD_FLAGS会把main.VERSION注入为当前 commit 或 tag工作区有未提交改动时追加dirty后缀可通过controller -version查看。2. 运行单元测试make test对应目标使用gotestsum生成 JUnit 报告与覆盖率文件test: $(GOTESTSUM) $(GO_FLAGS) --junitfile report.xml --format testname -- -coverprofilecoverage.out $(GO_PACKAGES)GO_PACKAGES ./...即覆盖仓库全部 Go 包包括 pkg/controller、pkg/crypto、pkg/kubeseal 等目录下的测试。3. 构建并推送 controller 镜像minikube 场景实际不会 pushminikube 直接访问本地镜像make K8S_CONTEXTminikube OSlinux ARCHamd64 push-controller使用自定义 registry如 kind 本地仓库时make K8S_CONTEXTkind REGISTRYlocalhost:5000 OSlinux ARCHamd64 push-controllerMakefile 中push-controller会先clean并执行scripts/check-k8s校验集群可达性然后构建controller.image.$(OS)-$(ARCH)。镜像基于 docker/controller.Dockerfile 构建默认镜像名规则为$(REGISTRY)/bitnami/sealed-secrets-controller:latest。当REGISTRYdocker.iominikube 默认场景时跳过实际 push否则执行docker push。4. 构建并应用 controller manifestsmake K8S_CONTEXTminikube apply-controller-manifests或 kind 场景make K8S_CONTEXTkind REGISTRYlocalhost:5000 apply-controller-manifests该目标先用kubecfg将仓库根目录的 controller.jsonnet依赖 kube-fixes.libsonnet 与 schema-v1alpha1.yaml渲染为controller.yaml随后kubectl apply -f controller.yaml部署到集群并通过kubectl rollout status deployment sealed-secrets-controller -n kube-system等待控制器就绪。5. 运行集成测试make integrationtest对应 Makefile 目标integrationtest: kubeseal controller $(GINKGO) -tags integration integration -- -kubeconfig $(KUBECONFIG) -kubeseal-bin $(abspath $) -controller-bin $(abspath $(word 2,$^))集成测试位于 integration/ 目录如 integration/controller_test.go、integration/kubeseal_test.go通过integrationbuild tag 隔离。测试会真实调用kubeseal与controller二进制在integration_suite_test.go中通过-kubeconfig、-kubeseal-bin、-controller-bin等 flag 指定被测产物路径。因此在运行集成测试前测试集群中必须已经安装好 controller。组件二Kubeseal 开发指南kubeseal 是客户端 CLI使用非对称加密对 Secret 加密只有 controller 能解密详见 kubeseal.md。获取源码与目录布局git clone https://github.com/bitnami/sealed-secrets.git $SEALED_SECRETS_DIRkubeseal 源码位于cmd/kubeseal/入口为 cmd/kubeseal/main.go同样复用pkg目录。其核心加密逻辑集中在 pkg/kubeseal/kubeseal.go主要函数包括Seal将输入 Secret 密封为 SealedSecret。EncryptSecretItem配合--raw对单个值加密。ValidateSealedSecret调用 controller 的/v1/verify端点校验可解密性。ReEncryptSealedSecret调用/v1/rotate用最新密钥重新加密。UnsealSealedSecret--recovery-unseal灾难恢复模式的离线解密。构建 kubeseal 二进制make kubeseal对应 Makefile 目标同样支持静态交叉编译如kubeseal-static-linux-amd64产物生成在当前工作目录。运行 kubeseal 测试make test与 controller 共用make test覆盖 cmd/kubeseal/main_test.go 与 pkg/kubeseal/kubeseal_test.go 等测试文件。关联源码controller 与 kubeseal 的核心参数速览为便于开发调试这里结合 cmd/controller/main.go 与 cmd/kubeseal/main.go 汇总两组关键启动参数所有参数均可用SEALED_SECRETS_前缀的环境变量覆盖Controller 常用参数controller -h可查看全部参数默认值说明--key-size4096加密密钥 RSA 位数--key-ttl10 年证书有效期--key-renew-period30 天新密钥生成周期设为 0 关闭自动轮换SIGUSR1 手动轮换仍生效--key-order-priorityCertNotBefore密钥排序依据可选SecretCreationTimestamp--key-cutoff-time空RFC1123 格式截止时间最新密钥更早时生成新密钥--all-namespacestrue是否扫描全部命名空间--additional-namespaces空逗号分隔的额外扫描命名空间--label-selector空过滤 SealedSecret 的标签选择器--rate-limit/--rate-limit-burst2 / 2/v1/verify与/v1/rotate的每秒请求数与突发上限--update-statustruebeta处理时是否更新 status 子资源--watch-for-secretsfalsebeta是否监听外部创建的密钥 Secret--skip-recreatefalse跳过监听托管 Secret 变更以重建它们适用于权限受限环境--old-gc-behaviorfalse回退到旧的 GC 行为controller 自行删除 Secret 而非交给 k8s--listen-addr/--listen-metrics-addr:8080/:8081HTTP 服务与指标服务地址定义于 pkg/controller/server.goKubeseal 常用参数kubeseal --help可查看全部参数默认值说明--cert空指定证书/公钥文件或 URL覆盖--controller-*--controller-namespacekube-systemcontroller 所在命名空间--controller-namesealed-secrets-controllercontroller 名称-o, --formatjson输出格式 json/yaml-f, --secret-file空输入 Secret 文件缺省从 stdin 读取-w, --sealed-secret-file空输出文件.yaml/.yml自动切换 yaml 格式--fetch-certfalse从 controller 抓取证书到 stdout--scopestrict密封范围strict / namespace-wide / cluster-wide--rawfalse直接加密原始值配合--from-file或 stdin--name空--raw且 strict scope 时必填--validatefalse通过/v1/verify校验 SealedSecret 可解密--re-encryptfalse用最新集群密钥重新加密--recovery-unsealfalse灾难恢复模式离线解密--recovery-private-key空--recovery-unseal所需私钥文件可重复指定Controller 的 HTTP 端点由 pkg/controller/server.go 实现其中/v1/cert.pem以 PEM 格式暴露当前公钥证书这正是 kubeseal--fetch-cert的数据来源/v1/verify与/v1/rotate均受基于throttled库的速率限制保护并支持X-Forwarded-For头区分客户端。git-hooks提交前的文档目录校验为避免显而易见的问题流入 main 分支仓库通过 Git hooks 实现了若干校验。Git 原生 hooks 存放在.git目录不随仓库分发因此需要先安装第三方工具git-hooks见前置条件才能将 hooks 纳入版本管理。目前仓库只在pre-commit级别挂载了一个 hookdoc-toc。它使用doctoc为所有使用了该工具的.md与.txt文件自动更新 Table of Contents。hook 脚本位于 githooks/pre-commit/doc-toc其逻辑为以main分支为基准计算待提交文件凡是以.md/.txt结尾的文件都执行doctoc $f重新生成 TOC若工作区因此产生改动则git add --all并打印变更清单从而保证文档目录永远与正文同步。为本仓库配置 git-hooksgit hooks install验证是否配置成功$ git hooks list Git hooks ARE installed in this repository. project hooks pre-commit - doc-toc Contrib hooks如果git hooks list输出中能看到pre-commit - doc-toc说明每次提交都会自动触发文档 TOC 校验与更新。小结Sealed Secrets 的开发者工作流可概括为三条主线编译make controller/make kubeseal、测试make test单元测试 make integrationtest集成测试、部署make push-controllermake apply-controller-manifests并可由make controller-tests一键串联。调试与理解系统时建议沿着 cmd/controller/main.go → pkg/controller/main.go → pkg/controller/keyregistry.go 的调用链阅读配合 cmd/kubeseal/main.go → pkg/kubeseal/kubeseal.go 理解客户端密封逻辑。最后通过 git-hooks doctoc 的配合文档 TOC 的维护成本被压到零——这正是该项目工程化细节的一个缩影。【免费下载链接】sealed-secretsA Kubernetes controller and tool for one-way encrypted Secrets项目地址: https://gitcode.com/GitHub_Trending/se/sealed-secrets创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考