网络云原生网络安全【免费下载链接】calicoCloud native networking and network security项目地址https://gitcode.com/gh_mirrors/cal/calico点击查看免费下载本文是 Calico 仓库中 charts/CLAUDE.md 的完整展开。该文档面向所有修改charts/目录的贡献者定义了三条核心纪律编辑 chart 模板后必须通过make gen-manifests重新生成manifests/目录该目录绝不允许手改任何改变用户安装/升级方式的 chart 改动必须与手写的安装文档在同一 PR 内同步更新防止 README 静默漂移AI 辅助贡献必须遵循仓库的 AI 政策。读完本文你将掌握 Calico 的 Helm 生成流水线如何运转、manifests/目录与 chart 模板之间的契约关系以及提交 chart 改动时需要满足的完整检查清单。生成流水线make gen-manifests是唯一入口charts/CLAUDE.md开篇即给出铁律编辑 chart 模板之后必须从仓库根目录运行make gen-manifests。它负责重新生成manifests/目录而该目录“otherwise entirely generated”——即其中的每个文件都是生成产物永远不要手工编辑。chart 改动必须与重新生成的 manifests 一起提交二者是一体的变更单元。Makefile 中的目标定义在仓库根目录 Makefile 中可以看到该目标的真实定义generate: $(MAKE) gen-semaphore-yaml $(MAKE) gen-deps-files $(MAKE) protobuf ... $(MAKE) -C operator gen-files $(MAKE) gen-manifests $(MAKE) -C e2e gen-test-set $(MAKE) fix-changed gen-manifests: bin/helm bin/yq cd ./manifests ./generate.sh关键信息Makefilegen-manifests依赖两个本地工具bin/helm和bin/yq由 Makefile 负责构建到bin/目录不依赖系统级安装的版本它实际执行的是manifests/generate.sh脚本在完整的make generate流程中gen-manifests排在 operator 的gen-files之后注释解释了原因“Before the manifests, which take the operators CRDs from its own tree”——manifest 生成需要先拿到 operator 树中生成好的 CRD 副本。generate.sh 干了什么manifests/generate.sh 是流水线的核心它完整展示了“chart 模板 → manifests 文件”的映射关系。脚本开头的环境变量处理已经说明了一切HELM${HELM:-../bin/helm} YQ${YQ:-../bin/yq} defaultCalicoVersion$($YQ .version ../charts/calico/values.yaml) CALICO_VERSION${PRODUCT_VERSION:-$defaultCalicoVersion} defaultRegistry$($YQ .node.registry ../charts/calico/values.yaml) REGISTRY${REGISTRY:-$defaultRegistry} defaultOperatorVersion$($YQ .tigeraOperator.version ../charts/tigera-operator/values.yaml) OPERATOR_VERSION${OPERATOR_VERSION:-$defaultOperatorVersion}即charts/calico/values.yaml中的.version和.node.registry是全局版本与镜像仓库的单一事实来源读取后通过--set传回 Helm 渲染。脚本随后依次生成tigera-operator.yaml手写 Namespace 头 helm template渲染 operator chart--no-hooks并关闭installation.enabled、apiServer、whisker、goldmane等子功能crds.yaml对charts/calico/crds/*.yaml逐个执行helm template --include-crds --show-only注释注明这是 “Calico the Hard Way” 文档使用的 CRD 清单v1_crd_projectcalico_org.yaml拼接operator/pkg/crds/operator下的 operator CRD 与crd.projectcalico.org.v1chart 的templates/calico/*.yaml并维护遗留的operator-crds.yaml副本v3_projectcalico_org.yaml与v3_projectcalico_org-v1beta1.yaml同一份 v3 bundle 用--api-versions admissionregistration.k8s.io/v1|v1beta1/MutatingAdmissionPolicy渲染两次以兼容不同 Kubernetes 版本上 MutatingAdmissionPolicy 的 API 版本差异1.36 起为 v11.34/1.35 为 v1beta1calico-*.yaml系列遍历charts/values/下每个 overlay 文件helm -n kube-system template ../charts/calico -f overlay渲染出 manifests/calico.yaml、manifests/calico-vxlan.yaml 等发布产物ocp/目录与tigera-operator-ocp-upgrade.yamlOpenShift 专用清单随后用 sed 统一替换静态 manifest 中的镜像与版本号。从源码结构看脚本最后一部分对“静态”manifest 做sed替换镜像版本是唯一不经过 Helm 渲染的修正步骤也解释了为什么“不要手改 manifests”——任何手工改动都会在下次生成时被覆盖或与契约不符。charts/calico不是面向用户的 chart仓库的 .github/instructions/helm-charts.instructions.md 明确了一点常被误解的事实charts/calico永远不会被任何人用 Helm 安装。它存在的唯一意义就是作为make gen-manifests的模板源渲染出manifests/calico*.yaml供用户消费。由此推导出两条重要结论渲染产物就是全部契约评审charts/calico的改动时直接阅读manifests/的 diff而不是想象“用户会怎么用这个 chart”——没有 Helm upgrade 路径需要保留也没有面向用户的安装文档需要同步values.yaml的键是内部接口charts/calico/values.yaml中的键可以被重命名或重构只要同一 PR 更新所有仓库内消费者即可。这些消费者包括manifests/generate.sh读取.version与.node.registry并通过--set回传若干键根 Makefilehelm package与 release 目标读取.versionhack/check-images-availability.sh读取.version与.node.registrycharts/values/下的 overlay 文件合并到默认值之上并按路径引用这些键。只有三个 chart 会被打包发布同样是这份 instructions 文档和根 Makefile 共同确认整个charts/目录中只有三个 chart 会被helm package打包发布产物落入$(CHART_DESTINATION)默认./bintigera-operator→tigera-operator-GIT_VERSION.tgzprojectcalico.org.v3→projectcalico.org.v3-GIT_VERSION.tgzcrd.projectcalico.org.v1→crd.projectcalico.org.v1-GIT_VERSION.tgzMakefile中每个 chart 目标的依赖都包含$(shell find ./charts/chart -type f)意味着 chart 内任何文件变动都会触发重新打包且--version与--app-version均取GIT_VERSION。README 的静默漂移两个手写文档charts/CLAUDE.md特别警告用户实际阅读的安装与升级说明位于两个手写README 中没有任何自动机制能发现它们过期charts/tigera-operator/README.mdoperator chart 的 Installing / Upgrading 全流程charts/crd.projectcalico.org.v1/README.md独立发布的 CRD chart 的安装/升级说明。“手写”意味着它们不会随模板渲染自动更新charts/CLAUDE.md原话是 “nothing catches them going stale”。漂移的真实代价v3.32 事故.github/instructions/helm-charts.instructions.md 记录了一次真实的事故issue #12860Calico v3.32 将 CRD 从 operator chart 中拆出、迁移到独立的crd.projectcalico.org.v1chart但 operator 的 README 仍写着直接helm installoperator chart 的旧步骤导致按文档安装的集群缺少 CRD、安装损坏。这正是“README 静默漂移”最恶劣的形态——chart 改动改变了用户的安装步骤文档却没有跟上。必须同步 README 的改动类型charts/CLAUDE.md与 instructions 文档共同列举了会改变用户安装/升级方式的改动出现任何一种都必须在同一 PR 更新对应 README在 chart 之间移动资源尤其是 CRDv3.32 事故即属此类增加或删除某个手动前置步骤例如创建tigera-operatornamespace、预置FelixConfiguration重命名 chart 或仓库改变 namespace 处理方式v3.23 起改为由用户自行创建 namespace、chart 安装在tigera-operatornamespace修改文档中写明的 values 键或示例命令。对照 charts/tigera-operator/README.md 的实际内容可以看到这些步骤在文档中的真实形态helm repo add projectcalico→helm template calico-crds projectcalico/crd.projectcalico.org.v1 | kubectl apply --server-side -f -安装 CRD→ 可选预置 Calico 自定义资源如FelixConfiguration注意 v3 API 用projectcalico.org/v3否则用 CRD 组crd.projectcalico.org/v1→kubectl create namespace tigera-operator→helm install calico projectcalico/tigera-operator --namespace tigera-operator。任何一步被 chart 改动影响README 就必须同步。豁免情形instructions 文档同时给出豁免规则避免无意义地阻塞模板重构只要改动不改变任何文档化的步骤就无需更新 README。典型豁免包括README 从未提及的 values 默认值调整、纯模板化重构templating-only refactor、生成的 CRD 内容更新generated-CRD content bump。拿不准时就更新文档。charts/calico则永远豁免于该规则——理由正是前文没有任何用户通过 Helm 安装它安装文档无从漂移但它仍然需要把重新生成的manifests/提交进同一 PR。提交 checklist一个 chart PR 的完整形态综合上述纪律一个触碰charts/目录的 PR 应当同时满足重新生成运行make gen-manifests依赖bin/helm、bin/yq确认manifests/中的 diff 与模板改动一一对应且没有手工编辑痕迹同步文档若改动影响用户安装/升级路径在同一 PR 更新 charts/tigera-operator/README.md 与 charts/crd.projectcalico.org.v1/README.md 中的对应章节保留内部接口契约若改了charts/calico/values.yaml的键同步更新所有仓库内消费者manifests/generate.sh、根 Makefile、hack/check-images-availability.sh、charts/values/overlay评审以 manifests diff 为准对charts/calico的改动评审者应读manifests/的渲染结果而非 chart 本身。instructions 文档还描述了 Copilot 代码评审的流程自动化评审对 PR 分支只读无法自行推送文档修正当它按上述规则发现 README 缺失更新时会在评论中附上可直接粘贴的copilot提示词例如copilot update charts/tigera-operator/README.md Installing section to cover the new CRD install step — users must apply the crd.projectcalico.org.v1 chart before installing the operator chart.评审者或作者将该提示投入新的 PR 评论Copilot 编码代理即可检出并推送修正提交。AI 辅助贡献披露、无共同作者、可解释charts/CLAUDE.md的最后一条纪律指向仓库根目录的 AI_POLICY.md。这份政策为包括 chart 改动在内的所有贡献设置了底线作者对每一行负责PR 的提交者拥有其中的每一行无论由人还是由 agent 写出“这是 AI 生成的”不能作为对评审反馈的回答必须在 PR 描述中披露一行即可例如 “This PR was written in part with the assistance of generative AI.”严禁添加Co-Authored-By:、Assisted-By:等 AI 共同作者 trailer——项目的 CLA 是人类之间的协议无法签署 CLA 的共同作者会阻塞 PR评审发生在人与人之间作者必须能用自己的话解释改动内容与动机若不能评审者有权关闭 PR用 agent 起草回复可以把整个评审线程交给 agent 不行理解后再提交提交前通读完整 diff包括非自己编写的部分、运行覆盖改动的测试并为新行为补测试、确认生成文件来自make generate而非手工编辑、核对改动是否符合相关组件的设计文档。政策特别提醒agent 容易发明“看似正确但不断言任何东西”的测试或通过放宽断言来“修复”测试审阅测试 diff 时要格外仔细评审机器人意见仅供参考bot 评论是建议性的最终批准与合并仍由人类维护者完成作者有权反对并说明理由。这些规则同样适用于文档类改动——包括 README 同步与 AI 辅助的 chart 补丁因此与本文前述的生成与同步纪律构成同一套提交流程。总结Calico 的 Helm 生态围绕“生成”与“契约”两个词组织make gen-manifests是唯一合法的 manifests 写入入口manifests/的 diff 是评审charts/calico改动的唯一依据三个发布型 charttigera-operator、projectcalico.org.v3、crd.projectcalico.org.v1的安装文档是手写的必须靠 PR 纪律防止漂移v3.32 的 CRD 拆分事故就是漂移的代价AI 辅助贡献则被 AI_POLICY.md 约束为披露、无共同作者、作者可解释。无论是修改模板、移动 CRD 还是调整 values 键提交前对照 .github/instructions/helm-charts.instructions.md 的更新规则逐一核验即可避免制造下一个“文档与 chart 脱节”的线上事故。赞分享网络云原生网络安全【免费下载链接】calicoCloud native networking and network security项目地址https://gitcode.com/gh_mirrors/cal/calico点击查看免费下载相关推荐SpacetimeDB 模板工具链解析README 生成、模板元数据同步与 builtWith 自动推导SpacetimeDB 模板工具链解析README 生成、模板元数据同步与 builtWith 自动推导 导读 本篇文章围绕 SpacetimeDB 仓库中的数据库关系型数据库后端lightweight-charts 插件 README 模板全解析从脚手架生成到 npm 发布lightweight charts 插件 README 模板全解析从脚手架生成到 npm 发布 本文以 create lwc plugin 插件脚手架 ht前端图表库金融科技数据可视化Pika与云原生集成Helm Charts与Kubernetes Operator终极指南Pika与云原生集成Helm Charts与Kubernetes Operator终极指南 Pika作为奇虎360基础架构团队开发的高性能NoSQL数据库完数据库KV存储后端上一篇图片转PDF工具下一篇【亲测免费】 FPGA设计辅助工具Visio FPGA模板创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考