云原生多集群集群管理微服务【免费下载链接】karmadaOpen, Multi-Cloud, Multi-Cluster Kubernetes Orchestration项目地址https://gitcode.com/GitHub_Trending/ka/karmada点击查看免费下载Karmada 是一个开放的多云、多集群 Kubernetes 编排平台其社区通过增强提案Karmada Enhancement Proposal简称 KEP机制来沉淀架构决策、驱动功能演进。本文以仓库中的 docs/proposals/proposal-template/proposal-template.md 为骨架逐节拆解 KEP 模板的完整结构、每个章节的写作目标与评审关注点并辅以仓库中多份真实提案如 configurable-local-value-retention、dispatch-suspension、cleanup-propagated-resources作为对照样例帮助你写出一份可评审、可落地、易于被社区维护者理解的 KEP 文档。模板概述与定位proposal-template.md是 Karmada 社区撰写功能提案的统一起点位于 docs/proposals/proposal-template/ 目录下。模板末尾明确注明这是Kubernetes enhancement proposal template 的简化版本。相比上游 Kubernetes 的 KEP 模板Karmada 版本保留了最核心的决策骨架——Summary、MotivationGoals/Non-Goals、Proposal、Design Details、Test Plan、Alternatives——去掉了大量仅适用于上游大型 SIG 协作的附属字段使其更适合 Karmada 这样聚焦多集群编排的单一仓库社区。整个 docs/proposals/ 目录下近 30 个提案覆盖 caching、调度、故障迁移、HPA、karmada-operator、服务发现等主题均基于该模板撰写因此掌握模板的规范用法是参与 Karmada 社区功能设计的第一步。Front Matter元信息与提案身份模板的第一部分是 YAML front matter用于声明提案的元信息--- title: Your short, descriptive title authors: - robot # Authors github accounts here. reviewers: - robot - TBD approvers: - robot - TBD creation-date: yyyy-mm-dd ---各字段含义如下字段必填说明title是短小、描述性的标题后续在 Proposal 正文的 H1 中再次出现authors是提案作者列表使用 GitHub 账号格式如Robotreviewers是评审人列表通常是相关模块的维护者可先用TBD占位approvers是最终批准人通常是 SIG/子项目的负责人可先用TBD占位creation-date是创建日期格式yyyy-mm-dd从仓库中真实提案看front matter 还可以扩展last-updated、short-desc、status等字段。例如 cleanup-propagated-resources/README.md 中记录了short-desc: Cleanup member cluster resources on unjoin title: Cleanup Member Cluster Resources authors: - huiwq1990 reviewers: - RainbowMango approvers: - creation-date: 2021-07-03 last-updated: 2020-07-03 status: provisional而 docs/proposals/scheduling/521-scheduler-estimator/README.md 中使用了status: implemented表示该提案对应的能力已经落地。这说明 front matter 承担着提案状态追踪的功能帮助社区区分草稿讨论中与已实现的设计。Summary一页说清提案是什么模板对 Summary 的定位非常明确这一节对产出高质量、面向用户文档如 release notes、开发路线图至关重要一个好的摘要至少应有一整段篇幅。写作要点用一段话交代现状背景当前系统是如何工作的存在什么问题点明提案目标要改变什么用户能得到什么收益避免展开实现细节——那是 Design Details 的职责。参照真实提案 configurable-local-value-retention/README.md 的 Summary 写法它先说明Karmada 持续监听成员集群中的已传播资源以确保其处于期望状态再指出成员集群控制器会改动资源如 Kubernetes 会给Service分配clusterIP、给Pod分配nodeName进而引出痛点——内置的 retain 方法不可定制、CRD 资源没有 retain 方法最后一句点明本提案旨在提供一种为任意资源定制 retain 方法的策略。这就是背景 → 问题 → 提案目标的典型三段式。Motivation明确目标与边界Motivation 用于显式列出变更的动机、Goals目标与Non-Goals非目标说明变更为什么重要、对用户有何好处。GoalsGoals 应列出提案具体要达成什么并给出可度量的成功标准。示例来自 configurable-local-value-retention/README.md提供策略支持为任意资源自定义 retain 方法支持覆盖 Kubernetes 内置资源的 retain 方法支持为 CRD 自定义资源定义 retain 方法提供通用的 Karmada 控制器行为定制机制该机制可被其他定制需求复用。Non-GoalsNon-Goals 用于明确本轮不做的事聚焦讨论、防止范围蔓延。同一提案中的 Non-Goals 示例不为 Kubernetes 资源逐一定义具体的 retain 方法不废弃内置 retain 方法——为知名资源保留内置 retain 有助于简化用户配置。再如 dispatch-suspension/README.md 的 Non-Goals 明确排除了开箱即用的金丝雀发布/滚动发布/蓝绿部署能力与按指定集群顺序的自动化发布。写作建议Goals 与 Non-Goals 使用动词 结果的短语形式逐条列出避免长篇大论。Proposal方案主体Proposal 是提案的核心需要给出足够细节让评审者准确理解你要做什么。模板明确指出这一节不应包含 API 设计或具体实现——期望的产出是什么、如何度量成功由这里回答真正的 nitty-gritty细节留给 Design Details 一节。User Stories可选模板要求尽可能详细地描述提案实现后人们能做什么目标是让用户产生真实感而不陷入细节。仓库中的提案普遍以多则 Story 展开dispatch-suspension/README.md 用 4 则 Story 覆盖典型场景运营者希望暂停资源同步以快速定位控制面与成员集群争夺资源导致反复更新的问题管理者希望按集群顺序发布版本通过设置partition实现 StatefulSet 部分实例更新以及希望在控制面保留变更、核对ResourceBinding/Work内容后再放行到成员集群。caching/README.md 则用跨地域部署应用、需要统一入口查看多集群资源分布的场景来驱动需求。每则 Story 建议采用角色 诉求 期望能力的结构并为每个场景明确列出 Karmada 需要提供的能力清单如list/watch/patch pod。Notes/Constraints/Caveats可选用于记录提案中未在上文体现的重要细节、核心概念之间如何关联。此节可选仓库中有多个提案为空或省略说明它服务于有则写、无则不写的原则。Risks and Mitigations模板给出了三组必答问题提案存在哪些风险如何缓解安全性如何评审由谁评审UX 如何评审由谁评审建议纳入 SIG 或子项目之外的相关人员。仓库中的真实风险表述值得借鉴。例如 caching/README.md 明确列出缓存资源通过search/proxyREST API 暴露有权限者可直接访问secret 若被缓存到控制面成员集群 RBAC 可能失效该功能面向管理员而非终端用户。而 dispatch-suspension/README.md 的风险记录是当工作负载处于暂停状态时即使启用 Failover 特性门控故障迁移也会被暂停直到用户取消暂停。Design Details把怎么做讲清楚这是模板中篇幅占比最大、技术深度要求最高的章节需包含足以理解变更的细节可能涉及 API 规范非必须或代码片段凡是对实现方式存在歧义的地方都应在此讨论。仓库中 Design Details 的常见写法1. 给出新的 API 定义。configurable-local-value-retention/README.md 在 Design Details 中直接给出了config.karmada.io组的完整 Go 结构体定义// Config represents the configuration of Karmada. type Config struct { metav1.TypeMeta json:,inline metav1.ObjectMeta json:metadata,omitempty // Spec represents the specification of the desired behavior of Karmada configuration. // required Spec ConfigSpec json:spec } type ConfigSpec struct { // Retentions represents a group of customized retention methods. // optional Retentions []LocalValueRetention json:retentions,omitempty } // LocalValueRetention represents a customized retention method for specific API resource. type LocalValueRetention struct { // APIVersion represents the API version of the target resources. // required APIVersion string json:apiVersion // Kind represents the Kind of the target resources. // required Kind string json:kind // Fields indicates the fields that should be retained. // Each field describes a field in JsonPath format. // optional Fields []string json:fields,omitempty // RetentionLua holds the Lua script that is used to retain runtime values to the desired specification. // optional RetentionLua string json:retentionLua,omitempty }其中Fields以 JsonPath 格式声明需要保留的字段RetentionLua保存 Lua 脚本片段脚本需实现function Retain(desiredObj, runtimeObj)形式并返回保留后的期望规格。提案还坦诚记录了技术选型考量Lua 未必是最优解曾考虑过cue并保留了支持多种脚本的可能性。2. 给出 API 变更与用户用法示例。dispatch-suspension/README.md 的 Design Details 依次展示PropagationPolicy/ClusterPropagationPolicy新增的Suspension结构、透传到ResourceBinding/ClusterResourceBinding再到Work的链路并配以可直接复制的 YAML 示例。例如用户在PropagationPolicy中设置暂停分发apiVersion: policy.karmada.io/v1alpha1 kind: PropagationPolicy metadata: name: nginx-propagation spec: resourceSelectors: - apiVersion: apps/v1 kind: Deployment name: nginx placement: clusterAffinity: clusterNames: - member1 - member2 - member3 suspension: suspendDispatching: true随后展示控制面上Work资源进入暂停状态后的实际形态spec.suspendDispatching: true及状态条件Dispatching并说明系统会通过事件记录分发暂停。3. 给出实现细节与可选设计。cleanup-propagated-resources/README.md 描述了为Cluster新增RemoveStrategy属性支持Needless与Required、为karmadactl join增加remove-strategy标志、在 unjoin 期间按策略处理并讨论执行控制器的行为差异。写作建议Design Details 宜遵循接口先行、示例随后、边界补全的顺序能贴代码就贴代码能配 YAML 就配 YAML让评审者无需脑补。Test Plan模板标注Not required until targeted at a release锁定到某个发布版本前非必需并给出制定测试计划的考量方向除单元测试外是否需要 e2e 与集成测试如何隔离测试、如何与其他组件联测无需罗列全部用例只需说明总体策略并指出实现中棘手、特别难测的部分。configurable-local-value-retention/README.md 的 Test Plan 即按此思路提出根据上述 User Stories 制定 e2e 用例测试可覆盖内置 retain 方法、测试可定制自定义资源并提议提供一个便于用户调试脚本的工具。Karmada 仓库本身的测试体系也为后续验证提供了落点例如 test/e2e/ 下的 e2e 框架与各 suite、以及 pkg/dependenciesdistributor/ 等包中的单元测试。Alternatives记录被否决的路线模板要求说明考虑过哪些其他方案、为何排除——不必像 Proposal 一样详细但应足以表达思路与被否决原因。真实例子configurable-local-value-retention/README.md 的 Alternatives 讨论了脚本语言选型Lua vs cuecleanup-propagated-resources/README.md 记录了 kubefed 提案中有人建议BestEffort策略、但评审者认为需要一个确定性的值因此 Karmada 未采用该策略、改为使用当前的内置行为。这些记录对后来的实现者与评审者极有价值——避免反复讨论已被否决的方案。从模板到真实提案仓库中的写作实践结合仓库中多份已合入的提案可以将模板各章节的最佳实践密度归纳如下章节建议篇幅关键产出Front Matter数行作者、评审人、批准人、日期、状态Summary≥ 1 段现状 → 问题 → 提案目标Motivation / Goals / Non-Goals各数条可度量目标 明确排除项Proposal / User Stories若干场景角色驱动的真实用例Risks and Mitigations数条安全、UX、行为风险与对策Design Details最长API 定义、YAML 示例、实现细节Test Plan策略级e2e/集成/单元测试策略与难点Alternatives数条被否决方案与理由需要说明的是模板中注释建议的标题如Your short, descriptive title需替换为实际提案标题文档格式沿用模板内注释使用的 HTML 注释!-- ... --用于隐藏写作指引正式提交前可清理。提案生命周期与提交路径从模板与仓库实践可以推断出 KEP 的一般生命周期作者起草 → 发起 PR 到 docs/proposals/ 目录 → 社区评审reviewers 评审、approvers 批准→ 状态演进。仓库中可见status: provisional草拟与status: implemented已实现两种状态标记说明 front matter 中的status字段随提案推进而更新。Karmada 的一般贡献流程fork 仓库 → 基于 master 建分支 → 逻辑单元提交 → 发起 PR同样适用于提案文档参与前建议阅读 CONTRIBUTING.md。提案写作属于技术设计讨论的一部分仓库内的真实提案文本、go.mod 对应的实现版本以及 docs/CHANGELOG/ 中的演进记录都可以作为判断该功能是否已实现、实现到什么程度的佐证材料。结语proposal-template.md虽然篇幅不长但它定义了 Karmada 社区技术治理的关键流程一份合格的 KEP应当让评审者在 Summary 快速理解价值、在 Motivation 看到边界、在 Proposal 通过用户故事建立实感、在 Design Details 获得可评审的接口与示例并在 Alternatives 中了解决策过程。以此为骨架参照仓库中 configurable-local-value-retention、dispatch-suspension、cleanup-propagated-resources 等成熟提案的行文密度你就能产出一份专业、完整、可评审的多集群功能设计文档。赞分享云原生多集群集群管理微服务【免费下载链接】karmadaOpen, Multi-Cloud, Multi-Cluster Kubernetes Orchestration项目地址https://gitcode.com/GitHub_Trending/ka/karmada点击查看免费下载相关推荐CANN Runtime 设计文档编写指南从模板到可评审设计的技术规范解析CANN Runtime 设计文档编写指南从模板到可评审设计的技术规范解析 导读 本文以 CANN/runtime 仓库官方提供的 设计文档模板 https:CANNAscend人工智能性能剖析系统编程Microsoft Graph API 设计模式文档模板PatternDescriptionTemplate全解析从模式构思到可评审模式文档的写作指南Microsoft Graph API 设计模式文档模板PatternDescriptionTemplate全解析从模式构思到可评审模式文档的写作指南 导API设计Apache Pulsar PIP 提案流程完全指南从 TEMPLATE.md 到社区合入的设计文档编写规范Apache Pulsar PIP 提案流程完全指南从 TEMPLATE.md 到社区合入的设计文档编写规范 导读 Pulsar Improvement Pr消息队列后端上一篇Flutter PDF开发必备dart_pdf API详解与最佳实践下一篇GitHub520解决GitHub访问问题的DNS优化方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考