kubernetes-sigs/controller-runtime

项目介绍

controller-runtime 是一组用于编写 Kubernetes 控制器的 Go 库。它把 informer、工作队列和客户端等细节封装成 manager、controller 和 builder 等抽象，开发者不必自己拼接底层组件。Kubebuilder 和 Operator SDK 都基于它构建，新项目通常先用这两个脚手架生成骨架，再依赖 controller-runtime README。

它主要面向编写 Operator 或自定义控制器、需要持续调和 Kubernetes 资源的团队，也适合需要随 Kubernetes 版本稳定升级客户端层的项目。

快速使用

新控制器建议从 Kubebuilder 快速入门开始，它会生成已接入 controller-runtime 的工程 Kubebuilder 快速入门。直接使用该库时，先添加模块：

go get sigs.k8s.io/controller-runtime

然后按官方示例创建 manager 与 controller，可参考创建 manager、创建 controller和使用 builder 编写基础控制器。仓库的 examples 目录提供了完整程序 示例。运行控制器需要可访问的 Kubernetes 集群及其凭据，manager 会使用标准 kubeconfig 或集群内配置。

版本与兼容性约束

controller-runtime 保持零主版本号。每个 Kubernetes 次版本会对应发布一个次版本，次版本之间允许存在破坏性变更，补丁版本则不做破坏性修改 VERSIONING.md。每个次版本只针对特定的 client-go 次版本测试；与其他 client-go 或 k8s.io/* 次版本混用可能碰巧可用，但不受支持和测试 兼容性表。

最低 Go 版本取自身 Go 依赖中最高的最低版本，通常与对应 k8s.io/* 依赖一致，具体对应关系可查看 go.mod go.mod。例如 v0.26 对应 k8s.io/* v0.38，要求 Go 1.27。

贡献代码时，PR 必须标记为缺陷修复、向后兼容功能或破坏性变更，仓库为每类改动提供了模板 README。

HotRepo 点评

在 2026 年 11 月 5 日的 Go 语言日榜中，该项目记录到 2,984 个 Star、1,333 个 Fork，当日 Star 无变化，位列 Go 榜第 15 名。这组数字反映的是成熟存量而非增长故事：它作为 Kubebuilder 和 Operator SDK 底层运行时，是 Operator 项目依赖它的原因，选用时更应关注 Kubernetes 与 Go 的版本搭配，而不是 Star 走势。