External Secrets Operator 开发环境搭建完全指南从 Go、Helm 到 Tilt 的本地开发工具链【免费下载链接】external-secretsExternal Secrets Operator reads information from a third-party service like AWS Secrets Manager and automatically injects the values as Kubernetes Secrets.项目地址: https://gitcode.com/GitHub_Trending/ex/external-secrets本文是围绕 External Secrets OperatorESO项目docs/introduction/prerequisites.md编写的开发环境准备指南涵盖在 Linux/macOS 上搭建 ESO 贡献与调试环境所需的全部工具Go、Helm、yq、jq、Docker、kubectl、ctlptl Kind 以及 Tilt。读完本文你将理解每个工具在 ESO 开发流程中的具体作用、推荐版本要求与安装方式并能从零构建出一个支持热重载的本地 Kubernetes 开发集群直接运行make tilt-up进入 ESO 的迭代开发循环。一、为什么需要准备开发环境External Secrets Operator 是一个用 Go 编写的 Kubernetes Operator其核心能力是从 AWS Secrets Manager、HashiCorp Vault、Azure Key Vault 等第三方服务读取机密并自动注入为 Kubernetes Secret。要参与该项目的开发、编译与测试你的机器上必须安装一套完整的工具链——它们分别负责代码编译Go、资源编排Kubernetes、kubectl、镜像构建Docker、清单生成Helm、配置处理yq/jq以及本地热重载开发ctlptl Kind Tilt。支持的操作系统ESO 的开发环境优先面向 Unix 系操作系统Linux 与 macOS。项目中的自动化脚本与命令均基于 bash 编写Makefile 也明确设置了SHELL : /usr/bin/env bash见 Makefile因此大部分make目标都依赖 bash 语义。能否在 Windows 上开发可以但有明显限制。由于 ESO 的开发环境未针对 Windows 优化Make、Tilt 以及各类 shell 脚本在 Windows 上可能产生兼容性问题。项目中的构建、清单生成等自动化流程均以 Unix 环境为前提Windows 上通常需要借助 WSLWindows Subsystem for Linux等适配手段才能顺畅运行且官方文档明确说明不覆盖 Windows 上的安装与配置因其复杂度高且未经充分测试。因此本文所有操作均以 Linux/macOS 为例。二、安装 GoGolangGo 在 ESO 中的作用GoGolang由 Google 的 Robert Griesemer、Rob Pike 和 Ken Thompson 设计以高效、易学、适合构建快速可扩展应用著称。在 ESO 中Go 是核心代码的开发语言整个 Operator 的控制器逻辑、Provider 实现、API 类型定义如 apis/externalsecrets/v1与生成器generators/v1均由 Go 编写。没有 Go 环境你将无法编译、运行或贡献源码。版本要求原文档记录的版本要求如下请务必结合当前仓库实际版本核对项目版本要求最低版本Go 1.20 或更高推荐版本文档撰写时Go 1.24.1需要特别说明的是当前仓库的 go.mod 已声明go 1.26.6说明项目随 Go 版本演进持续升级。因此在开始前请务必执行go version检查本地版本并确保不低于仓库go.mod中声明的版本否则单元测试等流程可能失败。安装方式Go 的官方安装程序覆盖各主流平台请查阅官方安装文档https://go.dev/doc/install按操作系统选择对应安装包。安装完成后建议配置GOPATH与PATH并运行go version验证。三、安装 HelmHelm 在 ESO 中的作用Helm 是 Kubernetes 的包管理器。在 ESO 项目中Helm 用于简化 Operator 在 Kubernetes 中的安装与管理把复杂的配置和部署过程自动化。项目的官方发行渠道即为 Helm Chart位于 deploy/charts/external-secrets用户通常通过helm install一键部署 ESO。版本要求与安装推荐版本Helm 3使用 Helm 3 的最新版本即可。安装方式请查阅 Helm 官方安装指南https://helm.sh/docs/intro/install/。在 ESO 开发中的典型用法安装 Helm 后你可以通过以下方式验证环境并与仓库中的自动化流程衔接# 验证安装 helm version # 从仓库本地 Chart 生成部署清单Makefile 中 manifests 目标的核心逻辑 helm dependency build deploy/charts/external-secrets helm template external-secrets deploy/charts/external-secrets \ -f deploy/manifests/helm-values.yaml bin/deploy/manifests/external-secrets.yaml在 Makefile 中manifests目标正是通过helm template将 Chart 渲染为 Tilt 部署所需的external-secrets.yaml可见 Helm 是本地开发链路的前置依赖。此外仓库还使用helm-unittest对 Chart 进行单元测试见 docs/contributing/devguide.md相关命令为make helm.test。四、安装 yqyq 在 ESO 中的作用yq 是一个用于读取、修改和写入 YAML 文件的命令行工具。ESO 的配置大量使用 YAMLChart、CRD、清单文件yq 被用于自动化编辑 YAML 配置方便开发与实现调整。版本要求与安装推荐版本yq v4.44.3 或更高mikefarah/yq 实现。安装方式请查阅 yq 官方仓库https://github.com/mikefarah/yqmacOS 可用brew install yqLinux 可直接下载二进制或通过包管理器安装。在 ESO 构建流程中的实际调用yq 深度嵌入了 Makefile 的自动化流程。例如helm.build相关目标会使用 yq 读取 Chart 元数据见 Makefilechartversion$(yq .version ./deploy/charts/external-secrets/Chart.yaml) chartappversion$(yq .appVersion ./deploy/charts/external-secrets/Chart.yaml) chartname$(yq .name ./deploy/charts/external-secrets/Chart.yaml)同时docs/contributing/devguide.md 明确指出许多make命令都依赖 yq且要求 4.2X.X 或更高版本。版本过低会导致构建脚本解析 Chart.yaml 失败务必按推荐版本安装。五、安装 jqjq 在 ESO 中的作用jq 是用于处理与转换 JSON 数据的命令行工具。ESO 与外部机密服务交互时大量涉及 JSON如 Provider 返回的机密负载、多架构镜像清单等jq 能够高效地过滤与变换这些信息。版本要求与安装推荐版本jq 1.6 或更高。安装方式请查阅 jq 官方文档https://stedolan.github.io/jq/主流 Linux 发行版与 macOSHomebrew均可直接安装。在 ESO 中的实际应用在 Makefile 的镜像发布流程中jq 被用于解析多架构 manifest 列表.tagmanifest提取各平台的镜像 digest 并组装--amend参数jq -r if typearray then .[] | select(.Descriptor.platform.architecture ! unknown) | .Descriptor.digest else .Descriptor.digest end .tagmanifest这验证了 jq 在发布与清单处理场景中的必要性——缺少 jq镜像 tag 合并等步骤将无法执行。六、Kubernetes 与本地集群Kubernetes 在 ESO 中的作用Kubernetes 是自动化部署、扩缩与容器应用管理的开源平台为 ESO 提供了运行 Operator 的基础设施。ESO 作为一个 Operator运行在集群内并监听ExternalSecret、SecretStore等 CRD因此本地必须有一个可用的 Kubernetes 集群用于开发与测试。要使用 Kubernetes需要先安装并配置若干工具本节后续将依次说明。更完整的 Kubernetes 概念可参考其官方文档https://kubernetes.io/docs/home/。七、安装 DockerDocker 在 ESO 中的作用Docker 用于构建容器镜像并在隔离环境中运行服务。ESO 的 Operator 以容器镜像形式分发基础镜像见 Dockerfile采用gcr.io/distroless/static并以 UID 65534 的非 root 用户运行本地开发时则需要 Docker 来构建镜像、运行 Kind 集群节点与本地容器镜像仓库。安装方式请查阅 Docker 官方文档https://docs.docker.com/get-docker/完成安装。关键配置让 Docker 免 sudo 运行Docker 默认需要 root 权限执行。为简化使用官方建议将当前用户加入docker组从而免去sudo。Linux 上的配置步骤如下# 1. 创建 docker 组若不存在 sudo groupadd docker # 2. 将当前用户加入 docker 组 sudo usermod -aG docker $USER # 3. 无需注销即可应用组变更 newgrp docker # 4. 验证免 sudo 运行 docker run hello-world若上述命令无报错输出说明配置成功。此步骤是后续创建本地 registry 与 Kind 集群的前提。八、安装 kubectlkubectl 在 ESO 中的作用kubectl 是管理 Kubernetes 集群的命令行工具用于执行集群命令、管理资源与调试应用。在 ESO 开发中你需要用它来应用配置如安装 CRD、部署清单、查看ExternalSecret等资源的运行状态。版本要求与安装版本要求安装与所用 Kubernetes 版本兼容的 kubectl通常直接使用最新稳定版即可。安装方式请查阅 kubectl 官方文档https://kubernetes.io/docs/tasks/tools/。版本兼容性提示仓库的 e2e 测试环境使用 Kubernetes 1.33.x见 Makefile 的KUBERNETES_VERSION : 1.33.x本地开发集群如 Kind版本宜与之接近避免 kubectl 与 API Server 版本差距过大导致兼容问题。九、安装 ctlptl 并创建带本地镜像仓库的 Kind 集群ctlptl 与 Kind 在 ESO 中的作用ctlptlControl Plane Tool用于管理本地 Kubernetes 开发集群可简化 KindKubernetes in Docker集群的创建与本地容器仓库的配置。Kind使用 Docker 容器充当集群节点实现一条命令起一个本地集群。在 ESO 开发中ctlptl Kind 组合用于创建本地集群并接入本地镜像仓库供开发期间存放 Docker 镜像。安装 ctlptl版本要求使用 ctlptl 的最新可用版本。安装方式请查阅 ctlptl 官方安装指南https://github.com/tilt-dev/ctlptl/blob/main/INSTALL.mdmacOS 可用brew install tilt-dev/tap/ctlptl。创建带本地镜像仓库的 Kind 集群依次执行以下命令# 1. 创建本地容器镜像仓库kind-registry监听 localhost:5000 docker run -d --restartalways -p 5000:5000 --name kind-registry registry:2 # 2. 使用 ctlptl 创建 Kind 集群并连接到本地仓库 ctlptl create cluster kind --registrykind-registry # 3. 验证集群运行状态 kubectl cluster-info --context kind-kind # 4. 列出 ctlptl 管理的所有集群 ctlptl get clusters命令 2 会创建一个已配置使用localhost:5000本地仓库的 Kind 集群。仓库中的 e2e/kind.yaml 给出了 Kind 集群节点拓扑的参考1 个 control-plane 2 个 worker如需自定义节点角色可参照修改。十、安装 TiltTilt 在 ESO 中的作用Tilt 是加速 Kubernetes 开发循环的工具能够自动化构建、部署与监控使代码变更近乎实时地反映到本地集群中。对 ESO 这种需要频繁改动控制器逻辑的项目Tilt 能极大缩短改代码 → 看效果的反馈周期。安装要求前置条件先安装好 Docker、kubectl、Kind 与 ctlptl。推荐版本最新可用版本。安装方式请查阅 Tilt 官方安装指南https://docs.tilt.dev/install.html。macOS 可使用brew install tilt-dev/tap/tiltLinux 可使用官方安装脚本。Tilt 在 ESO 项目中的实际配置仓库根目录的 Tiltfile 展示了 Tilt 的完整使用方式其核心逻辑包括启动时校验检查kubectl是否在 PATH 中缺失则直接fail见 Tiltfile读取部署清单解析bin/deploy/manifests/external-secrets.yaml由helm template生成将 CRD 通过kubectl apply --server-side先行安装其余 Deploymentexternal-secrets、external-secrets-webhook、external-secrets-cert-controller交给 Tilt 管理本地编译 热重载在本地执行CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -tags all_providers生成二进制见 Tiltfile再通过docker_build_with_restart将新二进制热替换进运行中的容器实现近乎即时的更新可选调试模式在tilt-settings.json/yaml中开启debug.enabled后Tilt 会改用 Delve 调试镜像并通过 30000 端口提供远程调试见 Tiltfile。启动 Tilt 开发环境在完成前述所有工具安装后进入仓库根目录执行make tilt-up该命令见 Makefile会先下载 Tilt版本锁定为 0.33.21见 Makefile并生成当前变更对应的部署清单到bin/deploy/manifests/external-secrets.yaml随后启动tilt up。在 Tilt 界面中按空格键即可观察所有 Pod 的启动过程与日志输出详见 docs/contributing/devguide.md 的 Using Tilt 一节。十一、工具清单速查表工具在 ESO 开发中的职责版本要求安装参考Go编译 Operator 核心代码、运行测试≥ 1.20推荐与 go.mod 声明版本一致当前为 1.26.6go.dev 官方安装文档Helm 3渲染/安装 Operator 的 Chart 清单Helm 3 最新版helm.sh 官方指南yq自动化读取/改写 YAML如 Chart.yaml 元数据v4.44.3mikefarah/yq 仓库jq处理 JSON如多架构镜像 manifest1.6stedolan.github.io/jqDocker构建镜像、运行 Kind 节点与本地 registry最新稳定版需配置免 sudodocs.docker.comkubectl管理集群、应用清单、查看资源状态与集群版本兼容仓库 e2e 用 1.33.xkubernetes.io 官方文档ctlptl创建/管理 Kind 集群与本地 registry最新版ctlptl 官方安装指南Kind以 Docker 容器运行本地 Kubernetes 集群随 ctlptl 自动管理见创建 Kind 集群一节Tilt热重载开发构建、部署、监控一体化最新版仓库 Makefile 锁定 0.33.21docs.tilt.dev十二、验证环境就绪完成全部安装后可依次执行以下命令做一次环境体检go version # 验证 Go 版本 helm version # 验证 Helm 3 yq --version # 验证 yq ≥ 4.44.3 jq --version # 验证 jq ≥ 1.6 docker run hello-world # 验证 Docker 免 sudo kubectl version --client # 验证 kubectl ctlptl get clusters # 验证 ctlptl 与集群全部通过后即可进入 ESO 的开发主流程。常用命令包括详见 docs/contributing/devguide.mdmake build # 构建 Operator 二进制 make test # 运行单元测试依赖 envtest需下载 KUBEBUILDER_ASSETS make lint # 运行 golangci-lint 静态检查 make tilt-up # 启动 Tilt 热重载开发环境至此你已经拥有了一套完整的 External Secrets Operator 本地开发环境可以开始编译、测试并为该项目贡献代码了。【免费下载链接】external-secretsExternal Secrets Operator reads information from a third-party service like AWS Secrets Manager and automatically injects the values as Kubernetes Secrets.项目地址: https://gitcode.com/GitHub_Trending/ex/external-secrets创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
