Kubebuilder v2 与 v3 对比（Legacy：从 v2.0.0+ 布局到 3.0.0+）

本文覆盖从 v2 迁移到 v3 时的所有破坏性变更。

更多（含非破坏性）变更详情可参考 controller-runtime、 controller-tools 以及 kb-releases 的发布说明。

共同变化（Common changes）

v3 项目使用 Go modules，且要求 Go 1.18+；不再支持使用 Dep 管理依赖。

Kubebuilder

  • 引入对插件的初步支持。详见可扩展 CLI 与脚手架插件：Phase 1、 Phase 1.5 与 Phase 2 的设计文档；亦可参考插件章节。

  • PROJECT 文件采用了新布局，记录更多资源信息，以便插件在脚手架时做出合理决策。

    另外，PROJECT 文件本身也引入版本：version 字段表示 PROJECT 文件版本；layout 字段表示脚手架与主插件版本。

  • gcr.io/kubebuilder/kube-rbac-proxy 镜像版本从 0.5.0 升级到 0.11.0（该组件默认开启，用于保护 manager 的请求），以解决安全问题。详情见 kube-rbac-proxy。

新版 go/v3 插件要点（TL;DR）

更多细节见 kubebuilder 发布说明，核心高亮如下：

  • 生成的 API/清单变化：

    • 生成的 CRD 使用 apiextensions/v1（apiextensions/v1beta1 在 Kubernetes 1.16 中已弃用）
    • 生成的 Webhook 使用 admissionregistration.k8s.io/v1（v1beta1 在 Kubernetes 1.16 中已弃用）
    • 使用 Webhook 时，证书管理切换为 cert-manager.io/v1（v1alpha2 在 Cert-Manager 0.14 中弃用，参见文档）

  • 代码变化：

    • manager 的 --metrics-addr 与 enable-leader-election 现更名为 --metrics-bind-address 与 --leader-elect，与 Kubernetes 核心组件命名保持一致。详见 #1839
    • 默认添加存活/就绪探针，使用 healthz.Ping
    • 新增以 ComponentConfig 方式创建项目的选项，详见增强提案与教程
    • Manager 清单默认使用 SecurityContext 以提升安全性，详见 #1637

  • 其他：

    • 支持 controller-tools v0.9.0（go/v2 为 v0.3.0，更早为 v0.2.5）
    • 支持 controller-runtime v0.12.1（go/v2 为 v0.6.4，更早为 v0.5.0）
    • 支持 kustomize v3.8.7（go/v2 为 v3.5.4，更早为 v3.1.0）
    • 自动下载所需的 Envtest 二进制
    • 最低 Go 版本升至 1.18（此前为 1.13）

迁移到 Kubebuilder v3

若希望升级到最新脚手架特性，请参考以下指南，获得最直观的步骤：

通过手动更新文件

若希望在不改变现有脚手架的前提下使用最新 Kubebuilder CLI，可参考下述“仅更新 PROJECT 版本并切换插件版本”的手动步骤。

该方式复杂、易错且不保证成功；并且不会获得默认脚手架文件中的改进与修复。

你仍可通过 go/v2 插件继续使用旧布局（不会把 controller-runtime 与 controller-tools 升至 go/v3 所用的版本，以避免破坏性变更）。本文也提供了如何手动修改文件以切换到 go/v3 插件与依赖版本的说明。