ingress-nginx 的 KEPKubernetes Enhancement Proposal流程从提案模板到社区共识【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读本文以 docs/enhancements/README.md 为核心系统讲解 Ingress NGINX Controller 项目如何借鉴 Kubernetes 社区的 KEPKubernetes Enhancement Proposal机制来规划、沟通与沉淀大型功能改动。你将了解KEP 的适用场景与收益、完整的提案文件结构元数据、Summary、Motivation、Proposal、Design Details 等、标准模板的填写步骤以及项目内三份真实 KEP动态 SSL、可用区感知路由、容器拆分是如何一步步演变为实际功能的。读完本文你可以直接照搬该模板为 ingress-nginx 的社区协作提出自己的结构化提案。KEP 是什么为什么 ingress-nginx 要采用它KEPKubernetes Enhancement Proposal是 Kubernetes 社区用于提出、沟通并协调新工作的标准方式。ingress-nginx 作为 Kubernetes 生态中最常用的入口控制器之一其功能演进往往牵涉数据面NGINX、控制面Go Controller与 Lua 脚本等多个模块因此项目官方在 docs/enhancements/README.md 中明确宣布采纳该机制。文档明确指出 KEP 的定位不是强制要求KEP 仅在改动范围广泛、影响项目大部分模块时才需要但强烈鼓励使用长此以往在同一个地方积累丰富 KEP 集合会让社区更容易追踪正在发生的事并形成结构化的历史档案。使用 KEP 的收益README 从KEP 使用者角度列出了核心收益在可被搜索引擎检索到的 Kubernetes 生态站点上获得曝光KEP 之间可交叉索引方便用户找到关联提案及其当前状态提供明确的、带 approvers 与 reviewers 的决策流程让决策更结构化、更可追溯、更经得起时间检验。该项目明确表示其灵感来源于 IETF RFC、Python PEP 和 Rust RFC——即以公开、编号、可版本化文档承载技术决策的成熟社区治理模式。开始一个 KEP标准模板与填表步骤KEP 的起点是 YYYYMMDD-kep-template.md 模板。文件命名规则为YYYYMMDD-my-title.md其中YYYYMMDD是提案首次起草的日期标题全部小写空格与标点替换为-如20190724-only-dynamic-ssl.md。完整的 KEP 文件结构模板给出了一个 KEP 文档应包含的全部章节从源码目录看每个章节在真实 KEP 中都被逐段落实章节作用模板要求YAML Front Matter元数据区记录 title、authors、reviewers、approvers、editor、creation-date、last-updated、status、see-also、replaces、superseded-byTable of Contents目录用!-- toc --/!-- /toc --包裹由脚本自动生成Summary摘要至少一段话可直接复用到 release notes 或开发路线图Motivation动机说明为何重要、对用户的价值可拆分 Goals 与 Non-GoalsProposal提案正文可选 User Stories、Implementation Details/Notes/Constraints、Risks and MitigationsDesign Details设计细节关键是 Test Plan直到针对某个 release 时才强制要求Implementation History实施历史记录 KEP 生命周期中的重大里程碑Drawbacks / Alternatives可选记录为什么不实现与其他方案Metadata 元数据区详解模板开头的 YAML 块是 KEP 工具化的关键支撑各字段含义如下--- title: KEP Template authors: - janedoe reviewers: - TBD - alicedoe approvers: - TBD - oscardoe editor: TBD creation-date: yyyy-mm-dd last-updated: yyyy-mm-dd status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced see-also: - /docs/enhancements/20190101-we-heard-you-like-keps.md replaces: - /docs/enhancements/20181231-replaced-kep.md superseded-by: - /docs/enhancements/20190104-superseding-kep.md ---其中status字段定义了 KEP 的完整生命周期状态机provisional草案、implementable可实施、implemented已实施、deferred推迟、rejected拒绝、withdrawn撤回、replaced被取代。see-also、replaces、superseded-by用于建立 KEP 之间的关联关系配合模板中的交叉索引收益使用。五步走模板推荐的启动流程模板给出了明确的起步步骤复制模板创建YYYYMMDD-my-title.md填写 overview 章节即 Summary 和 Motivation建议先在 issue 中预热想法创建 PR指派给赞助该流程的成员创建 issue填写 enhancement 跟踪 issue 的全部字段尽早合并先只提交 Overview 部分后续 PR 增量补充细节——凡是标记为provisional的内容都视为进行中的工作文档允许变更。同时坚持单主题 PR让讨论保持聚焦。目录TOC的自动化维护模板要求 TOC 使用codelt;!-- toc --rt;lt;!-- /toc --rt;/code标签包裹即!-- toc --注释并通过 hack/update-toc.sh 自动生成。该脚本的核心逻辑是go install ./vendor/github.com/tallclair/mdtoc grep --include*.md -rl docs/enhancements/* -e !-- toc -- | xargs mdtoc --inplace即用mdtoc工具扫描docs/enhancements/下所有含!-- toc --标记的 Markdown 文件并原地更新目录——这也解释了为何三份真实 KEP 中都能看到自动生成的 TOC。三份真实 KEP 拆解提案如何落地为代码docs/enhancements/目录下已有三份按模板撰写的真实 KEP它们分别对应项目演进中的三个关键决策可以作为撰写自己 KEP 的最佳实践范本。案例一20190724-only-dynamic-ssl.md —— 移除静态 SSL 配置模式这份 KEP 的元数据完整展示了 approvers/reviewers 的分工作者aledbf评审与审批ElvinEfendistatus: implementable表明已进入可实施阶段。其核心论证链条Summary自 0.19.0 起可用 Lua 实现无需 reload 的 SSL 证书配置0.24.0 起动态模式成为默认Motivation静态配置意味着 reload而 reload 影响绝大多数用户Goals废弃--enable-dynamic-certificates标志、清理代码库Non-Goals不改变证书认证相关功能Proposal移除静态 SSL 配置将ssl_certificate与ssl_certificate_key指令从各 server 块移到http段以避免日志报错Alternatives保留双实现。这份 KEP 体现了用一个提案解决一个明确问题的最小化范例——目标、非目标、方案与替代方案一目了然。案例二20190815-zone-aware-routing.md —— 可用区感知路由这是内容最详实的一份 KEP完整示范了 Proposal 章节应有的工程深度。背景是跨可用区inter-zone流量会产生额外成本与延迟提案目标是让 ingress-nginx 优先把请求转发到同可用区zone-local的 endpoint。其核心设计要点控制器通过 downward API 将节点名注入为环境变量启动时查询 API 获取节点详情并从failure-domain.beta.kubernetes.io/zone注解提取当前 Pod 所在可用区控制器监听节点 create/update 事件在内存维护节点名 → 可用区映射生成 endpoints 时通过.subsets.addresses[i].nodeName关联可用区备选方案是启动时全量拉取节点建表、缺失时按需查询以减少对 API server 的 watch 压力在 Lua 侧为每个 backend 初始化两个 balancer 实例全量 endpoints 与仅当前可用区 endpoints优先使用 zonal balancer不存在时回退到通用 balancer可用区故障时依赖就绪探针失效使该 backend 无可用 endpoint从而自然回退特性通过 ConfigMap 开关启用便于出现问题后回滚。该提案明确列出了 Goalsbest-effort 选择 zone-local endpoint、不影响 canary 功能、无可用区 endpoint 时仍可正常工作、Non-Goals假设 endpoint 分布足以消化本可用区流量仅依赖failure-domain.beta.kubernetes.io/zone不支持其他场景以及 Drawbacks对 Kubernetes API server 增加负载。这一 KEP 提出的设计方向与当前仓库源码中的可用区相关处理逻辑存在对应关系——在 internal/ingress/controller/endpointslices.go、internal/ingress/controller/controller.go 及模板生成代码 internal/ingress/controller/template/template.go 中均可检索到 zone 相关字段的处理痕迹可以作为追踪该特性演进起点的索引。案例三20231001-split-containers.md —— 容器拆分提案这份 KEP 面向镜像架构演进其内容格式略有不同未使用标准 YAML 元数据更接近设计草稿重点规划了控制面与数据面的拆分一个容器只放 NGINX 相关文件不挂载 ServiceAccount另一个容器只放控制器文件最小化 Go 程序SA 只挂载到控制器NGINX 容器内需要一个极小的 HTTP 监听器仅负责启动、停止与 reload NGINX明确了 NGINX 容器的端口规划公网 HTTP/HTTPS 端口 80/443Lua 配置端口 10246HTTP与 10247Stream3333临时为 Dataplane 控制器的 HTTP server提供/reloadPOSTconfig参数指定待替换的临时 nginx.conf 路径与/testPOSTconfig参数指定待测试的配置文件路径给出了挂载空 ServiceAccount 的 Pod 示例 YAML、NGINX 配置映射目录清单Lua 脚本、日志、pid、GeoIP、SSL、auth、Modsecurity、OTEL/Opentracing 配置等以及可移除文件清单与模块清单。从源码看该 KEP 的落地痕迹非常清晰仓库中确实存在独立的 Dataplane 入口 cmd/dataplane/main.go其启动流程为解析 flagsingressflags.ParseFlags、创建必填目录、初始化 Prometheus 注册表与指标收集器、创建controller.NewNGINXController并通过ngx.Start()启动 NGINX 控制器逻辑而 internal/ingress/controller/config/config.go 中的ListenPorts结构体精确刻画了运行所需端口集合// ListenPorts describe the ports required to run the // NGINX Ingress controller type ListenPorts struct { HTTP int json:HTTP HTTPS int json:HTTPS Health int json:Health Default int json:Default SSLProxy int json:SSLProxy }在 internal/ingress/controller/controller.go 中这些端口被逐一用于启动监听。可见 KEP 文档中规划的端口与目录拆分最终演化为当前仓库中cmd/dataplane与internal/ingress/controller的模块化实现。撰写高质量 KEP 的实践要点综合 README、模板与三份真实案例可以提炼出以下可复用的写作准则先用 Summary 定调Summary 是 release notes 与路线图的素材来源应在实现前写好避免实现者分心Goals 与 Non-Goals 缺一不可Non-Goals 明确范围外内容能有效聚焦讨论并推进进度参考 zone-aware routing 对 canary 特性的排除Proposal 落到实现细节真实 KEP 会具体到端口号、Lua 模块加载时机如init_by_lua阶段、API 调用方式与回滚策略尽早合并、增量完善先合并 Overview后续 PR 补充细节provisional状态即活文档用 Implementation History 记录里程碑包括 Summary/Motivation 合并表示被接受、Proposal 合并表示设计达成一致、实现启动日期、首次随哪个 release 发布、何时 GA 或退役Test Plan 到 release 阶段再补全模板明确注明该节直到针对某个 release 时才需要但需考虑 e2e、集成测试与单测的总体策略并遵循 Kubernetes 测试指南善用可选章节Drawbacks为什么不该实现与 Alternatives其他可行方案用于记录决策上下文避免后人重复讨论。从提案到共识KEP 在项目协作中的定位从仓库整体看KEP 机制是 ingress-nginx 社区治理的一部分提案docs/enhancements/→ 代码实现internal/、cmd/→ 测试验证test/e2e/→ 版本发布changelog/、charts/ingress-nginx/changelog/形成完整闭环。三份 KEP 恰好覆盖了项目演进的三个典型层次——功能废弃动态 SSL、行为增强可用区路由、架构重构容器拆分说明这套流程既能承载小范围决策也能承载影响整个镜像与部署模型的大改动。对于想要参与 ingress-nginx 社区贡献的开发者最直接的上手路径是先在 issue 中预热想法 → 复制 YYYYMMDD-kep-template.md 为YYYYMMDD-你的标题.md→ 完成 Summary 与 Motivation → 尽早创建 PR随后增量补充 Proposal、Design Details 与 Implementation History。这样你的设计决策就能像 RFC 一样成为这个社区可检索、可追溯、经得起时间检验的公共档案。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 13:01:49 · 阅读 1.2k ingress-nginx 的 KEP（Kubernetes Enhancement Proposal）流程：从提案模板到社区共识
ingress-nginx 的 KEPKubernetes Enhancement Proposal流程从提案模板到社区共识【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读本文以 docs/enhancements/README.md 为核心系统讲解 Ingress NGINX Controller 项目如何借鉴 Kubernetes 社区的 KEPKubernetes Enhancement Proposal机制来规划、沟通与沉淀大型功能改动。你将了解KEP 的适用场景与收益、完整的提案文件结构元数据、Summary、Motivation、Proposal、Design Details 等、标准模板的填写步骤以及项目内三份真实 KEP动态 SSL、可用区感知路由、容器拆分是如何一步步演变为实际功能的。读完本文你可以直接照搬该模板为 ingress-nginx 的社区协作提出自己的结构化提案。KEP 是什么为什么 ingress-nginx 要采用它KEPKubernetes Enhancement Proposal是 Kubernetes 社区用于提出、沟通并协调新工作的标准方式。ingress-nginx 作为 Kubernetes 生态中最常用的入口控制器之一其功能演进往往牵涉数据面NGINX、控制面Go Controller与 Lua 脚本等多个模块因此项目官方在 docs/enhancements/README.md 中明确宣布采纳该机制。文档明确指出 KEP 的定位不是强制要求KEP 仅在改动范围广泛、影响项目大部分模块时才需要但强烈鼓励使用长此以往在同一个地方积累丰富 KEP 集合会让社区更容易追踪正在发生的事并形成结构化的历史档案。使用 KEP 的收益README 从KEP 使用者角度列出了核心收益在可被搜索引擎检索到的 Kubernetes 生态站点上获得曝光KEP 之间可交叉索引方便用户找到关联提案及其当前状态提供明确的、带 approvers 与 reviewers 的决策流程让决策更结构化、更可追溯、更经得起时间检验。该项目明确表示其灵感来源于 IETF RFC、Python PEP 和 Rust RFC——即以公开、编号、可版本化文档承载技术决策的成熟社区治理模式。开始一个 KEP标准模板与填表步骤KEP 的起点是 YYYYMMDD-kep-template.md 模板。文件命名规则为YYYYMMDD-my-title.md其中YYYYMMDD是提案首次起草的日期标题全部小写空格与标点替换为-如20190724-only-dynamic-ssl.md。完整的 KEP 文件结构模板给出了一个 KEP 文档应包含的全部章节从源码目录看每个章节在真实 KEP 中都被逐段落实章节作用模板要求YAML Front Matter元数据区记录 title、authors、reviewers、approvers、editor、creation-date、last-updated、status、see-also、replaces、superseded-byTable of Contents目录用!-- toc --/!-- /toc --包裹由脚本自动生成Summary摘要至少一段话可直接复用到 release notes 或开发路线图Motivation动机说明为何重要、对用户的价值可拆分 Goals 与 Non-GoalsProposal提案正文可选 User Stories、Implementation Details/Notes/Constraints、Risks and MitigationsDesign Details设计细节关键是 Test Plan直到针对某个 release 时才强制要求Implementation History实施历史记录 KEP 生命周期中的重大里程碑Drawbacks / Alternatives可选记录为什么不实现与其他方案Metadata 元数据区详解模板开头的 YAML 块是 KEP 工具化的关键支撑各字段含义如下--- title: KEP Template authors: - janedoe reviewers: - TBD - alicedoe approvers: - TBD - oscardoe editor: TBD creation-date: yyyy-mm-dd last-updated: yyyy-mm-dd status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced see-also: - /docs/enhancements/20190101-we-heard-you-like-keps.md replaces: - /docs/enhancements/20181231-replaced-kep.md superseded-by: - /docs/enhancements/20190104-superseding-kep.md ---其中status字段定义了 KEP 的完整生命周期状态机provisional草案、implementable可实施、implemented已实施、deferred推迟、rejected拒绝、withdrawn撤回、replaced被取代。see-also、replaces、superseded-by用于建立 KEP 之间的关联关系配合模板中的交叉索引收益使用。五步走模板推荐的启动流程模板给出了明确的起步步骤复制模板创建YYYYMMDD-my-title.md填写 overview 章节即 Summary 和 Motivation建议先在 issue 中预热想法创建 PR指派给赞助该流程的成员创建 issue填写 enhancement 跟踪 issue 的全部字段尽早合并先只提交 Overview 部分后续 PR 增量补充细节——凡是标记为provisional的内容都视为进行中的工作文档允许变更。同时坚持单主题 PR让讨论保持聚焦。目录TOC的自动化维护模板要求 TOC 使用codelt;!-- toc --rt;lt;!-- /toc --rt;/code标签包裹即!-- toc --注释并通过 hack/update-toc.sh 自动生成。该脚本的核心逻辑是go install ./vendor/github.com/tallclair/mdtoc grep --include*.md -rl docs/enhancements/* -e !-- toc -- | xargs mdtoc --inplace即用mdtoc工具扫描docs/enhancements/下所有含!-- toc --标记的 Markdown 文件并原地更新目录——这也解释了为何三份真实 KEP 中都能看到自动生成的 TOC。三份真实 KEP 拆解提案如何落地为代码docs/enhancements/目录下已有三份按模板撰写的真实 KEP它们分别对应项目演进中的三个关键决策可以作为撰写自己 KEP 的最佳实践范本。案例一20190724-only-dynamic-ssl.md —— 移除静态 SSL 配置模式这份 KEP 的元数据完整展示了 approvers/reviewers 的分工作者aledbf评审与审批ElvinEfendistatus: implementable表明已进入可实施阶段。其核心论证链条Summary自 0.19.0 起可用 Lua 实现无需 reload 的 SSL 证书配置0.24.0 起动态模式成为默认Motivation静态配置意味着 reload而 reload 影响绝大多数用户Goals废弃--enable-dynamic-certificates标志、清理代码库Non-Goals不改变证书认证相关功能Proposal移除静态 SSL 配置将ssl_certificate与ssl_certificate_key指令从各 server 块移到http段以避免日志报错Alternatives保留双实现。这份 KEP 体现了用一个提案解决一个明确问题的最小化范例——目标、非目标、方案与替代方案一目了然。案例二20190815-zone-aware-routing.md —— 可用区感知路由这是内容最详实的一份 KEP完整示范了 Proposal 章节应有的工程深度。背景是跨可用区inter-zone流量会产生额外成本与延迟提案目标是让 ingress-nginx 优先把请求转发到同可用区zone-local的 endpoint。其核心设计要点控制器通过 downward API 将节点名注入为环境变量启动时查询 API 获取节点详情并从failure-domain.beta.kubernetes.io/zone注解提取当前 Pod 所在可用区控制器监听节点 create/update 事件在内存维护节点名 → 可用区映射生成 endpoints 时通过.subsets.addresses[i].nodeName关联可用区备选方案是启动时全量拉取节点建表、缺失时按需查询以减少对 API server 的 watch 压力在 Lua 侧为每个 backend 初始化两个 balancer 实例全量 endpoints 与仅当前可用区 endpoints优先使用 zonal balancer不存在时回退到通用 balancer可用区故障时依赖就绪探针失效使该 backend 无可用 endpoint从而自然回退特性通过 ConfigMap 开关启用便于出现问题后回滚。该提案明确列出了 Goalsbest-effort 选择 zone-local endpoint、不影响 canary 功能、无可用区 endpoint 时仍可正常工作、Non-Goals假设 endpoint 分布足以消化本可用区流量仅依赖failure-domain.beta.kubernetes.io/zone不支持其他场景以及 Drawbacks对 Kubernetes API server 增加负载。这一 KEP 提出的设计方向与当前仓库源码中的可用区相关处理逻辑存在对应关系——在 internal/ingress/controller/endpointslices.go、internal/ingress/controller/controller.go 及模板生成代码 internal/ingress/controller/template/template.go 中均可检索到 zone 相关字段的处理痕迹可以作为追踪该特性演进起点的索引。案例三20231001-split-containers.md —— 容器拆分提案这份 KEP 面向镜像架构演进其内容格式略有不同未使用标准 YAML 元数据更接近设计草稿重点规划了控制面与数据面的拆分一个容器只放 NGINX 相关文件不挂载 ServiceAccount另一个容器只放控制器文件最小化 Go 程序SA 只挂载到控制器NGINX 容器内需要一个极小的 HTTP 监听器仅负责启动、停止与 reload NGINX明确了 NGINX 容器的端口规划公网 HTTP/HTTPS 端口 80/443Lua 配置端口 10246HTTP与 10247Stream3333临时为 Dataplane 控制器的 HTTP server提供/reloadPOSTconfig参数指定待替换的临时 nginx.conf 路径与/testPOSTconfig参数指定待测试的配置文件路径给出了挂载空 ServiceAccount 的 Pod 示例 YAML、NGINX 配置映射目录清单Lua 脚本、日志、pid、GeoIP、SSL、auth、Modsecurity、OTEL/Opentracing 配置等以及可移除文件清单与模块清单。从源码看该 KEP 的落地痕迹非常清晰仓库中确实存在独立的 Dataplane 入口 cmd/dataplane/main.go其启动流程为解析 flagsingressflags.ParseFlags、创建必填目录、初始化 Prometheus 注册表与指标收集器、创建controller.NewNGINXController并通过ngx.Start()启动 NGINX 控制器逻辑而 internal/ingress/controller/config/config.go 中的ListenPorts结构体精确刻画了运行所需端口集合// ListenPorts describe the ports required to run the // NGINX Ingress controller type ListenPorts struct { HTTP int json:HTTP HTTPS int json:HTTPS Health int json:Health Default int json:Default SSLProxy int json:SSLProxy }在 internal/ingress/controller/controller.go 中这些端口被逐一用于启动监听。可见 KEP 文档中规划的端口与目录拆分最终演化为当前仓库中cmd/dataplane与internal/ingress/controller的模块化实现。撰写高质量 KEP 的实践要点综合 README、模板与三份真实案例可以提炼出以下可复用的写作准则先用 Summary 定调Summary 是 release notes 与路线图的素材来源应在实现前写好避免实现者分心Goals 与 Non-Goals 缺一不可Non-Goals 明确范围外内容能有效聚焦讨论并推进进度参考 zone-aware routing 对 canary 特性的排除Proposal 落到实现细节真实 KEP 会具体到端口号、Lua 模块加载时机如init_by_lua阶段、API 调用方式与回滚策略尽早合并、增量完善先合并 Overview后续 PR 补充细节provisional状态即活文档用 Implementation History 记录里程碑包括 Summary/Motivation 合并表示被接受、Proposal 合并表示设计达成一致、实现启动日期、首次随哪个 release 发布、何时 GA 或退役Test Plan 到 release 阶段再补全模板明确注明该节直到针对某个 release 时才需要但需考虑 e2e、集成测试与单测的总体策略并遵循 Kubernetes 测试指南善用可选章节Drawbacks为什么不该实现与 Alternatives其他可行方案用于记录决策上下文避免后人重复讨论。从提案到共识KEP 在项目协作中的定位从仓库整体看KEP 机制是 ingress-nginx 社区治理的一部分提案docs/enhancements/→ 代码实现internal/、cmd/→ 测试验证test/e2e/→ 版本发布changelog/、charts/ingress-nginx/changelog/形成完整闭环。三份 KEP 恰好覆盖了项目演进的三个典型层次——功能废弃动态 SSL、行为增强可用区路由、架构重构容器拆分说明这套流程既能承载小范围决策也能承载影响整个镜像与部署模型的大改动。对于想要参与 ingress-nginx 社区贡献的开发者最直接的上手路径是先在 issue 中预热想法 → 复制 YYYYMMDD-kep-template.md 为YYYYMMDD-你的标题.md→ 完成 Summary 与 Motivation → 尽早创建 PR随后增量补充 Proposal、Design Details 与 Implementation History。这样你的设计决策就能像 RFC 一样成为这个社区可检索、可追溯、经得起时间检验的公共档案。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考