★ FEATURED ARTICLE 开发者工具代码生成CLI云原生后端【免费下载链接】kubebuilderKubebuilder - SDK for building Kubernetes APIs using CRDs项目地址https://gitcode.com/gh_mirrors/ku/kubebuilder点击查看免费下载本文是 kubebuilder 仓库根目录 AGENTS.mdAI Agent Guide的深度解析与实战扩展。它以Agent 如何在本仓库高效工作为主线覆盖仓库目录地图、脚手架机制、插件架构、构建/测试/提交流程以及代码与日志规范帮助读者无论是人类开发者还是 AI 编码助手快速定位修改点、遵循仓库纪律并合规地提交贡献。读完本文你将掌握 Kubebuilder 源码的模块边界、插件与模板的扩展方式、make工作流与 PR 规范并能安全地在不触碰生成文件的前提下进行二次开发。项目速览Kubebuilder 是什么根据 AGENTS.md 的定位Kubebuilder 是一套框架 命令行工具CLI用于基于Custom Resource DefinitionsCRDs构建 Kubernetes API。它通过脚手架与抽象层显著加速用 Go 编写的controllers、webhooks 和 APIs的开发。官方速查表如下项目值语言以 go.mod 为准当前为go 1.26.0模块名sigs.k8s.io/kubebuilder/v4二进制产物./bin/kubebuilder核心依赖controller-runtime、controller-tools、Helm、Kustomize用户文档book.kubebuilder.io本仓库 docs/book/ 为 mdBook 源码从源码可以印证其工程底座入口 main.go 只做一件事——调用 internal/cli/cmd/cmd.go 中的cmd.Run()命令层基于spf13/cobra文件系统抽象基于spf13/aferoBDD 测试使用onsi/ginkgo/v2与onsi/gomega详见 go.mod。这些依赖与 AGENTS.md 中的目录说明、测试哲学一一对应。仓库目录地图从入口到各模块AGENTS.md 给出了权威的目录速览结合仓库实际文件可以归纳为以下几条主线pkg/—— 核心实现代码pkg/cli/CLI 命令实现。init、create api、create webhook、edit、root等子命令分别由 pkg/cli/init.go、pkg/cli/api.go、pkg/cli/webhook.go、pkg/cli/edit.go、pkg/cli/root.go 承载。其中 pkg/cli/init.go 还负责默认 PluginBundle 的定义与init子命令的动态装配。pkg/machinery/脚手架引擎包含模板template.go、代码注入器inserter.go、标记处理marker.go、以及基于 afero 的文件系统抽象filesystem.go。pkg/model/资源模型GVK、API、Controller、Webhook与插件执行阶段pkg/model/stage/stage.go。pkg/plugin/插件接口与工具。核心接口在 pkg/plugin/plugin.go插件组合在 pkg/plugin/bundle.go。pkg/plugins/插件实现新增插件放这里。包括 Go 脚手架默认实现 pkg/plugins/golang/v4/、deploy-image 模式插件、Kustomize 清单生成 pkg/plugins/common/kustomize/v2/、可选插件 pkg/plugins/optional/helm、grafana、autoupdate以及外部插件 pkg/plugins/external/。测试与样例数据test/e2e/需要 Kubernetes 集群Kind的端到端测试。仓库实际的 e2e 用例集中在 test/e2e/all/分别覆盖 v4 插件plugin_v4_test.go、Helm 插件plugin_helm_test.go与 deploy-image 插件plugin_deployimage_test.go测试工具类在 test/e2e/utils/test_context.go。testdata/生成的完整示例项目禁止手改包括基本 v4 项目 testdata/project-v4/、多分组项目project-v4-multigroup/、带可选插件的项目project-v4-with-plugins/。docs/book/mdBook 用户文档源码其中**/testdata/是文档配套的示例工程重新生成。入口与版本internal/cli/version/version.go版本信息随 Kubernetes 版本联动更新。常见任务的落点速查AGENTS.md 原表新增插件 →pkg/plugins/category/name/新增模板 →pkg/plugins/plugin/scaffolds/internal/templates/修改 CLI 命令 →pkg/cli/新增脚手架机制 →pkg/machinery/新增测试 →test/e2e/all/plugin_name_test.go或pkg/package/*_test.go铁律不得手改生成文件AGENTS.md 明确划定了三类自动重新生成的内容手工编辑会被 CI 校验覆盖或拒绝路径重新生成命令testdata/make generate-testdatadocs/book/**/testdata/make generate-docs*/dist/chart/Helm 渲染产物make generate-chartsMakefile 中可以看到对应目标generate-testdata会清空testdata/并执行./test/testdata/generate.shgenerate-docs调用./hack/docs/generate.shgenerate-charts则对四个示例工程分别执行kubebuilder edit --pluginshelm/v2-alpha重新生成 Helm chart。这一设计保证了示例永远与当前代码行为一致。文件级修改要求何时重新生成AGENTS.md 给出了改了什么就跑什么的精确对照修改hack/docs/internal/下的文档生成源码 →make install make generate-docs修改pkg/plugins/optional/helm/→make install make generate-charts修改任何 boilerplate/模板文件 →make install make generate其中boilerplate/模板文件指的是定义脚手架模板的 Go 文件通常位于pkg/plugins/**/scaffolds/internal/templates/或用于为脚手架项目生成代码/配置的文件。格式与提交前检查改*.go后 →make lint-fixgolangci-lint 自动修复改*.md后 →make remove-spaces去除行尾空格见 Makefile 的remove-spaces目标PR 前必跑make lint-fix make test-unit开发工作流构建、lint 与测试构建与安装Makefilemake build # 构建到 ./bin/kubebuildergo build --trimpath -o bin/kubebuilder make install # 复制到 $(go env GOBIN)即加入 PATHLint 与格式make lint # 仅检查golangci-lint yamllint make lint-fix # 自动修复 Go 代码测试金字塔AGENTS.md 与 Makefile 一致make test-unit # 快速单元测试./pkg/...、./test/e2e/utils/... make test-integration # 集成测试可能创建临时目录、下载二进制 make test-testdata # 测试所有 testdata 示例工程 make test-e2e-local # 完整 e2e创建 kind 集群可用 SKIP_KIND_CLEANUP1 复用集群 make test # CI 聚合以上全部 license 校验从 Makefile 可看到test-unit实际执行go test -racetest-integration需要 kubebuilder 二进制在 PATH 中并带-tagsintegration与 30 分钟超时test-e2e-local调用 test/e2e/local.sh。这些命令是 CItest/e2e/ci.sh与本地复现同一套质量门禁的基础。提交流程PR 标题与提交信息规范PR 标题格式强制使用 emoji 前缀会进入 release notes格式:emoji: [(plugin/version)]: Description(plugin/version)作用域可选仓库级或纯文档变更可省略。Emoji含义⚠️ (:warning:)破坏性变更✨ (:sparkles:)新功能 (:bug:)缺陷修复 (:book:)文档 (:seedling:)基础设施/测试/重构示例 Resolve nil pointer panic in scaffold generator ✨ (helm/v2-alpha): Add cluster-scoped resource support (go/v4): Update deployment documentation ✨ Update dependencies to latest versions提交信息格式遵循 Conventional Commits 规范格式为type[optional scope]: description作用域通常是插件/版本如helm/v2-alpha、go/v4。类型包括feat、fix、docs、test、refactor、chore、breaking可与其它类型组合。示例fix: Resolve nil pointer panic in scaffold generator feat(helm/v2-alpha): Add cluster-scoped resource support docs(go/v4): Update deployment documentation chore: Update dependencies to latest versionsPre-PR 检查清单AGENTS.md 原清单每个 PR 一个 commit全部 squash为新行为添加/更新测试为新行为添加/更新文档运行make lint-fix运行make install运行make generate运行make test-unit更完整的贡献要求可参阅 CONTRIBUTING.md 与版本/发布策略 VERSIONING.md。核心概念一插件架构插件体系是 Kubebuilder 可扩展性的根基。所有插件实现 pkg/plugin/plugin.go 中定义的接口Plugin—— 基础接口Name()返回 DNS1123 风格的全限定名如go.kubebuilder.io、Version()插件版本注意与项目配置版本不同、SupportedProjectVersions()返回非空的支持的项目配置版本列表Init—— 项目初始化kubebuilder init通过GetInitSubcommand()暴露InitSubcommandCreateAPI—— API 创建kubebuilder create apiCreateWebhook—— Webhook 创建kubebuilder create webhookEdit—— 初始化后的修改kubebuilder editBundle—— 将多个插件组合为一个键Plugins()必须返回扁平化列表不再包含 Bundle同文件还定义了可选的Deprecated弃用警告与Describable一行描述用于 help 输出接口。插件 Bundle 的默认组合由 pkg/cli/init.go 定义的默认 Bundle 为go.kubebuilder.io/v4kustomize.common.kubebuilder.io/v2。从 pkg/plugin/bundle.go 的实现可以看到NewBundleWithOptions会从各插件求取共同支持的项目版本并把嵌套 Bundle 展开为扁平列表插件最终经由pkg/plugin的注册表解析并按顺序执行。外部插件位于 pkg/plugins/external/ 的可执行二进制通过 stdin/stdout 以 JSON 与 CLI 通信实现语言无关的扩展。核心概念二脚手架机制machinery内部/cli/ 之外脚手架引擎位于 pkg/machinery/四个核心抽象AGENTS.md 原文Template—— 基于 Go 模板生成文件Inserter—— 在 marker 处进行代码注入Marker—— 特殊注释如// kubebuilder:scaffold:imports驱动的扩展点Filesystem—— 对 afero 的抽象便于测试替身从 pkg/machinery/scaffold.go 可以看到Scaffold结构体持有afero.Fs、目录/文件权限DefaultDirectoryPermission 0o755、DefaultFilePermission 0o644保证生成文件在共享/容器工作流中可用并通过 injector 为模板注入上下文生成 Go 文件时还使用golang.org/x/tools/imports做格式化与 import 整理。这意味着模板输出即规范代码。核心概念三脚手架生成的项目结构AGENTS.md 特别强调以下文件是Kubebuilder 生成的项目而非 Kubebuilder 源码本身默认由go/v4kustomize/v2插件组合生成go/v4插件生成 Go 代码cmd/main.go—— 入口manager 装配api/v1/*_types.go—— 带kubebuildermarker 的 API 定义create api生成internal/controller/*_controller.go—— Reconcile 逻辑create api生成Dockerfile、Makefile—— 构建与部署自动化kustomize/v2插件生成清单config/—— Kustomize 基础清单CRD、RBAC、manager、webhooksconfig/crd/—— 自定义资源定义create api生成config/samples/—— 示例 CR 清单create api生成PROJECT文件记录插件、资源、domain 与布局的项目配置。可参考仓库自带的完整样例 testdata/project-v4/PROJECT。核心概念四调谐模式Reconciliation Pattern控制器实现Reconcile(ctx, req) (ctrl.Result, error)AGENTS.md 归纳了三条关键语义幂等Idempotent—— 可安全地重复执行电平触发Level-triggered—— 响应当前状态而非事件待办时重新入队Requeue—— 返回ctrl.Result{RequeueAfter: time.Minute}延迟重试这三条语义是 controller-runtime 下所有控制器代码的共同契约也是编写可运维控制器的基本功。测试模式与组织E2E 测试助手使用 test/e2e/utils/test_context.go 中的utils.TestContextAGENTS.md 给出了最小可运行示例ctx : utils.NewTestContext(util.KubebuilderBinName, GO111MODULEon) ctx.Init(--domain, example.com, --repo, example.com/project) ctx.CreateAPI(--group, crew, --version, v1, --kind, Captain) ctx.Make(build, test) ctx.LoadImageToKindCluster()测试分层AGENTS.md 原文单元测试pkg/内*_test.go—— 隔离测试单个包速度快集成测试pkg/内*_integration_test.go—— 无需集群地组合多个组件必须在文件顶部带//go:build integration构建标签可能创建临时目录、下载二进制或脚手架文件如 alpha update、grafana 脚手架、helm chart 生成E2E 测试test/e2e/——仅用于需要 Kubernetes 集群Kind的用例。仓库实际用例在 test/e2e/all/plugin_v4_test.gov4 插件部署、plugin_helm_test.goHelm chart 部署、plugin_deployimage_test.godeploy-image 插件测试哲学测试行为而非实现优先真实组件而非 mock把测试用例当作规格说明Ginkgo 的Describe、It、Context、By统一使用Ginkgo v2 Gomega依赖 kubebuilder 二进制的测试使用utils.NewTestContext(util.KubebuilderBinName, GO111MODULEon)。CLI 参考make install之后可用的核心命令AGENTS.md 原文kubebuilder init --domain example.com --repo github.com/example/myproject kubebuilder create api --group batch --version v1 --kind CronJob kubebuilder create webhook --group batch --version v1 --kind CronJob kubebuilder edit --pluginshelm/v2-alpha kubebuilder alpha generate # 实验性从 PROJECT 文件生成 kubebuilder alpha update # 实验性更新到最新插件版本其中alpha系列实验命令的实现位于 internal/cli/alpha/对应源码中的generate.go、update.go及其测试edit --pluginshelm/v2-alpha正是 Helm chart 自动生成插件pkg/plugins/optional/helm/的启用方式。从 pkg/cli/root.go 还可以看到全局--plugins标志的解析、help 请求处理与插件表格输出逻辑。常见模式一代码风格AGENTS.md 明确避免缩写写context而不是ctx接收者除外使用描述性命名projectConfig而不是pc单/双字母接收者可以接受(c CLI)或(p Plugin)常见模式二日志约定两种截然不同的规范这是本仓库最有特色的纪律按代码运行位置区分日志风格。1. Kubebuilder CLI 工具代码 → Go CLI 最佳实践。适用于pkg/cli/*、pkg/plugins/*、pkg/machinery/*、pkg/config/*、pkg/model/*等即工具自身首词小写句号后句子首字母大写unable to find file. This file is required for...结尾不加标点句间可用句号错误字符串小写fmt.Errorf(something bad)log.Info(writing scaffold for you to edit) log.Warn(unable to find boilerplate file. This file is used to generate the license header) log.Error(failed to read file, file, path) return fmt.Errorf(failed to load config: %w, err)2. 生成的代码模板输出→ Kubernetes 约定。适用于 pkg/plugins/*/scaffolds/internal/templates/ 模板生成的控制器代码运行在集群内首字母大写Starting reconciliation结尾不加句号句间可用句号使用过去时Failed to create Pod而不是Cannot create Pod主动语态指明主语或程序本身作主语时省略指明对象类型Created Deployment而不是Created// 在生成控制器代码的模板文件中 log.Info(Starting reconciliation) log.Info(Created Deployment, name, deploy.Name) log.Error(err, Failed to create Pod, name, name)判断依据就一句话代码跑在哪里——开发机上的 CLI 工具遵循 Go 约定集群内运行的控制器遵循 Kubernetes 约定。搜索技巧AGENTS.md 提供了一组高效的rg检索命令适合快速定位源码rg \\kubebuilder:scaffold --type go # 查找 marker rg type.*Plugin struct pkg/plugins/ # 查找插件实现 rg PluginBundle pkg/cli/ # 查找插件注册 rg func.*SetTemplateDefaults # 查找模板定义 rg func new.*Command pkg/cli/ # 查找 CLI 命令 rg NewTestContext test/e2e/ # 查找 E2E 测试初始化设计哲学AGENTS.md 总结了仓库的五大设计原则理解它们有助于在提交时做出契合社区风格的决策库优先于代码生成Libraries over code generation—— 能用库就用库生成代码难以维护常见场景简单不常见场景可做到Common cases easy, uncommon cases possible—— 80–90% 的用例应当开箱即用电池全配Batteries included—— 项目开箱即可部署与测试禁止复制粘贴No copy-paste—— 重构进库或远程 Kustomize base参考资料速查AGENTS.md 末尾给出的关键资源均可在本仓库内直接查阅Makefile—— 所有自动化目标的权威来源构建/测试命令CONTRIBUTING.md—— CLA、提交前检查清单、PR 要求VERSIONING.md—— 发布流程、版本策略、PR 打标go.mod—— Go 版本与依赖清单pkg/—— 核心代码CLI、插件、脚手架机制test/e2e/—— 需要 Kubernetes 集群的端到端测试testdata/—— 生成的示例项目自动再生成docs/book/—— 用户文档源码book.kubebuilder.io关键代码文件包括 pkg/cli/init.go默认插件 Bundle 定义、pkg/plugin/plugin.go插件接口定义、pkg/machinery/scaffold.go脚手架引擎、test/e2e/utils/test_context.goE2E 测试助手、internal/cli/version/version.go版本信息。脚本方面可关注 test/testdata/generate.sh再生成全部 testdata、hack/docs/generate.sh再生成文档示例与 test/e2e/local.sh本地 Kind e2e。对于希望以 AI Agent 身份或新贡献者身份进入 kubebuilder 仓库的读者这份指南既是地图也是纪律手册按目录地图定位修改点遵守生成文件红线按 Makefile 工作流验证再以规范化的 PR 格式提交即可安全高效地为这一 Kubernetes API 构建工具链贡献力量。赞分享开发者工具代码生成CLI云原生后端【免费下载链接】kubebuilderKubebuilder - SDK for building Kubernetes APIs using CRDs项目地址https://gitcode.com/gh_mirrors/ku/kubebuilder点击查看免费下载相关推荐Security-101 AI Agent 协作指南面向自动化贡献者的仓库结构与开发工作流全解析Security 101 AI Agent 协作指南面向自动化贡献者的仓库结构与开发工作流全解析 Security 101 是一个由 Microsoft 发起网络安全教程文档Apache Airflow 源码仓库协作指南从 monorepo 架构边界到 AI Agent 开发工作流Apache Airflow 源码仓库协作指南从 monorepo 架构边界到 AI Agent 开发工作流 Apache Airflow 仓库根目录的 CL后端任务调度工作流自动化数据编排批处理数据工程流程编排Fresh 框架仓库开发指南Monorepo 结构、架构原理与贡献工作流Deno PreactFresh 框架仓库开发指南Monorepo 结构、架构原理与贡献工作流Deno Preact 导读 本文以 Fresh 官方仓库根目录的 AGENT后端前端上一篇三步打造高复用组件Naive UI 组件封装实践指南下一篇告别卡顿vim-airline状态栏实时动态更新全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
