Kubernetes kube-addon-manager 版本演进全解析：从 CHANGELOG 透视集群插件管理器的核心机制

导读：kube-addon-manager 是 Kubernetes 集群中负责把 cluster/addons/ 下的内置插件（DNS、metrics-server、dashboard 等）声明式地创建并持续治理到集群里的"插件管家"。本文以 cluster/addons/addon-manager/CHANGELOG.md 为骨架，逐段还原其从 v1 到 v9.1.8 的演进主线，并结合同目录下的 README.md、kube-addons.sh、Makefile 等源码，讲清 Reconcile / EnsureExists 双模式、kubectl apply --prune 治理、多主 HA 下的 leader election 与镜像发布流程。读完你将掌握 addon-manager 的功能边界、版本化行为差异及其在集群中的实际部署与运维方式。

一、addon-manager 是什么：先理解它管什么、怎么管

kube-addon-manager 是运行在 control plane（典型为 kube-system 命名空间下的一个 Pod）上的控制器脚本集合。它的工作目录即 manifest 源目录 $ADDON_PATH（默认 /etc/kubernetes/addons），通过 kube-addons-main.sh 启动一个周期性的 apply 循环，对目录内的 YAML/JSON 模板文件做持续治理。

1.1 两类插件治理模式

根据 README.md 与 kube-addons.sh 中对 addonmanager.kubernetes.io/mode 标签的解析，addon 被划分为两个类别：

模式标签值	语义	行为保证
addonmanager.kubernetes.io/mode=Reconcile	声明式收敛（周期性 reconcile）	被删除会重建；被用户直接改动会在一轮周期内被模板字段"纠正"回原状；manifest 文件从 $ADDON_PATH 删除后，对应资源会被 prune 掉
addonmanager.kubernetes.io/mode=EnsureExists	仅确保存在（只检查不覆盖）	同名字资源不存在时按模板创建/重建；用户后续修改会被保留；manifest 文件被删除时不会删除已存在的资源

对应源码函数为 reconcile_addons / ensure_addons：reconcile 走 kubectl apply（带 --prune=true），ensure 走 kubectl create（幂等地容忍 AlreadyExists）。

说明：kubernetes.io/cluster-service=true 是仅面向 Addon Manager 的已弃用标签。目前带该标签但未带 EnsureExists 的 addon 仍按 Reconcile 类处理，但未来可能不再被尊重；$ADDON_PATH 下的资源必须带上述两类标签之一，否则会被忽略（见 README.md）。

1.2 主循环与启动前置条件

kube-addons-main.sh 中：进程启动后先等待 kube-system 命名空间的默认 ServiceAccount 就绪（v9.1.6 清理的就是这段等待逻辑），随后先创建 /etc/kubernetes/admission-controls 下定义的资源，最后进入以 ADDON_CHECK_INTERVAL_SEC（默认 60 秒，见 kube-addons.sh）为周期的循环——若被选举为 leader 则执行 ensure_addons 与 reconcile_addons，否则休眠等待。

二、沿着 CHANGELOG 看八年的能力演进

CHANGELOG 记录了从 2016 年 5 月的 v1 到 2025 年 3 月的 v9.1.8 共 40 余次发版。这些条目并非孤立版本号，而是 addon-manager 架构决策的编年史。下面按四条技术主线重组解读，最后附完整版本时间线。

2.1 主线一：从"启动脚本"走向"声明式 gitops 式管理"（v1 → v6.0 → v6.1）

• v1：addon-manager 首次以 Pod 形式运行（"Run kube-addon-manager in a pod"），标志其成为集群内一等公民组件。
• v2：移除废弃的 kubectl 命令并支持 DaemonSet；v5 加入 PetSet（StatefulSet 前身）支持；v5.1 修复非命名空间对象的处理；v5.2 加入 ConfigMap 支持并升级 kubectl 至 v1.4.4。
• v6.0（2016-11）是分水岭：全面切换为 kubectl apply——addon 治理从"启动时创建一次"进化为"以模板为期望状态的持续声明"，后续所有 reconcile/prune 能力都建立在这一决策之上。
• v6.1 顺理成章地"支持清理旧 Deployment"，即 prune 语义的雏形。

2.2 主线二：双模式与标签体系的定型（v6.4 系列）

• v6.4-alpha.3：引入 "ensure exist" 类 addon，并使用 addon-manager 专属标签——即今天的 addonmanager.kubernetes.io/mode。
• v6.4-beta.1：规定 EnsureExists 类 addon 先于 Reconcile 类创建，避免依赖冲突。
• 这一阶段同期还铺垫了两个依赖项：v6.4-alpha.1 升级 kubectl 以支持可选 ConfigMap；v6.4-alpha.2 跟进 HPA 由 extensions/v1beta1 迁往 autoscaling/v1 的 API 组变更，说明 addon-manager 的 kubectl 版本始终紧跟 API 演进。

2.3 主线三：多主 HA 与 leader election（v6.5 → v9.0.2/v9.1.4 修复）

• v6.5 起支持 HA masters：多 master 场景下若每个节点都跑 addon-manager，必须保证只有一个在执行 reconcile，否则会互相"打架"。
• 源码实现可参考 is_leader 函数：它复用 kube-controller-manager 的 Lease（leases.v1.coordination.k8s.io kube-controller-manager），比对 holderIdentity 与自身 HOSTNAME 前缀来决定是否执行；通过 ADDON_MANAGER_LEADER_ELECTION（默认 true）可关闭该机制（见 kube-addons.sh）。
• v9.0.2（PR 80575）与 v9.1.4（issue 98966）分别修复了 leader election 中的缺陷——HA 支持并非一次到位，两次 bugfix 恰好说明该路径是生产环境踩坑高发区。

2.4 主线四：prune 白名单机制的完整闭环（v8.7 → v9.0 → v9.1.0 → v9.1.7）

• v8.7：支持传入额外 --prune-whitelist 资源。
• v9.0：改经 apps/v1 API 清理 workload 资源，对齐当时 extensions/v1beta1 的废弃进程。
• v9.1.0：支持覆盖默认白名单（新增 KUBECTL_PRUNE_WHITELIST_OVERRIDE 环境变量）。
• v9.1.7：正式以 --prune-allowlist 取代已废弃的 --prune-whitelist。

当前默认白名单（15 类资源）定义在 kube-addons.sh：core/v1 的 ConfigMap、Endpoints、Namespace、PersistentVolumeClaim、PersistentVolume、Pod、ReplicationController、Secret、Service；batch/v1 的 Job、CronJob；apps/v1 的 DaemonSet、Deployment、ReplicaSet、StatefulSet；以及 networking.k8s.io/v1 的 Ingress。附加白名单由 KUBECTL_EXTRA_PRUNE_WHITELIST 提供，二者合并后经 generate_prune_allowlist_flags 生成 kubectl 参数。

2.5 完整版本时间线（原文全量继承）

版本	日期	关键变更
v1	2016-05-05	以 Pod 形式运行 kube-addon-manager
v2	2016-05-20	移除废弃 kubectl 命令；支持 DaemonSet
v3	2016-06-19	addon-manager 版本升至 v3
v4	2016-06-21	增大 addon 检查间隔
v5	2016-06-24	增加 PetSet 支持
v5.1	2016-07-04	修复非命名空间对象的处理方式
v5.2	2016-10-26	增加 ConfigMap 支持；kubectl 升至 v1.4.4
v6.0	2016-11-18	全面改用 kubectl apply
v6.1	2016-11-29	支持清理旧的 Deployment
v6.2	2017-01-12	kubectl 升级至稳定版
v6.3	2017-01-27	arm 基础镜像切至 armhf/busybox，使用 qemu v2.7 模拟
v6.4-alpha.1	2017-02-01	kubectl v1.6.0-alpha.1，支持可选 ConfigMap
v6.4-alpha.2	2017-02-16	kubectl 升级，HPA 改用 autoscaling/v1
v6.4-alpha.3	2017-02-24	引入 EnsureExists 类 addon 及专属标签
v6.4-beta.1	2017-03-08	EnsureExists 类先于 Reconcile 类创建
v6.4-beta.2	2017-06-12	kubectl v1.6.4；刷新基础镜像
v6.5	2017-10-15	支持 HA masters
v8.4	2017-11-30	kubectl v1.8.4
v8.6	2018-02-20	支持非 kube-system 命名空间下的资源 reconcile/ensure；kubectl v1.9.3
v8.7	2018-09-04	支持额外 --prune-whitelist 资源；kubectl v1.10.7
v8.8	2018-10-01	使用 debian-base:0.3.2
v8.9	2018-10-19	使用 debian-base:0.4.0；kubectl v1.11.3
v9.0	2019-01-16	经 apps/v1 API prune workload 资源；kubectl v1.13.2
v9.0.1	2019-04-10	使用 debian-base:v1.0.0
v9.0.2	2019-08-01	修复 leader election 缺陷（PR 80575）
v9.1.0	2020-05-13	支持覆盖默认白名单资源列表
v9.1.1	2020-05-19	修复 kube-addons.sh 与 kubectl 权限
v9.1.2	2020-08-06	修复 start_addon 覆盖 mode=EnsureExists 资源的问题
v9.1.3	2020-11-30	kubectl v1.19.3
v9.1.4	2021-02-10	kubectl v1.20.2；修复 leader election 缺陷（issue 98966）
v9.1.5	2021-04-19	基础镜像更新至 debian-base:v1.0.1
v9.1.6	2022-02-24	清理 ServiceAccount 等待检查逻辑（PR 108313）
v9.1.7	2023-05-15	kubectl v1.27.1；以 --prune-allowlist 替代废弃的 --prune-whitelist
v9.1.8	2025-03-03	kubectl v1.32.2；基础镜像 debian-base:bookworm-v1.0.4

从表可见三个长期节奏：kubectl 随 release 定期升级（v1.4.4 → v1.32.2）；基础镜像从 debian-base 演进到 bookworm 世代；每次行为修复都精准针对双模式语义或 HA 选举。

三、用源码与测试验证"版本化行为"

3.1 双模式差异的可执行证据

cluster/addons/addon-manager/kube-addons-test.sh 是面向真实集群的集成测试，直接对应 CHANGELOG 中反复强调的行为语义，可运行 make test（见 Makefile）验证：

• test_create_resource_reconcile：证明 Reconcile 资源被用户 kubectl edit 修改后会被模板重新写回（测试先把模板从 100m 改成 50m 并确认集群更新，再手工改成 600m 并确认被还原）。
• test_create_resource_ensureexists：证明 EnsureExists 资源不会被模板更新覆盖（用户手工改 600m 被保留），但被删除后会按模板重建。
• test_create_multiresource：证明同一 manifest 中混排两类模式时各自遵循上述语义。

v9.1.2 修复的正是 start_addon 曾错误覆盖 EnsureExists 资源的问题——当前 create_resource_from_string / reconcile_resource_from_string / ensure_resource_from_string 中对 apply 用 -l ...=Reconcile、对 create 用 -l ...=EnsureExists 的分流实现，正是那次修复沉淀下来的稳定形态。

3.2 部署形态与运行参数

生产环境中的实际 Pod 清单见 cluster/gce/manifests/kube-addon-manager.yaml：镜像 registry.k8s.io/addon-manager/kube-addon-manager:v9.1.8，以 hostNetwork 运行并挂载 /etc/kubernetes/addons（只读）、/var/log（写日志）以及 addon-manager 专属 kubeconfig；容器内通过环境变量注入 KUBECTL_PRUNE_WHITELIST_OVERRIDE、KUBECTL_EXTRA_PRUNE_WHITELIST 与 KUBECTL_OPTS。镜像内容见 Dockerfile：debian-base 之上仅放入 kube-addons.sh、kube-addons-main.sh 与 kubectl 二进制，CMD 即 /opt/kube-addons-main.sh。

四、多架构镜像发布与版本协同

Makefile 目前维护 VERSION=v9.1.8、KUBECTL_VERSION=v1.32.2，与 CHANGELOG 最新条目一致（基础镜像在 Makefile 中已迭代至 bookworm-v1.0.6，高于 CHANGELOG 记录的 v1.0.4，属文档记录之后的后续构建变更）。发布流程见 README.md：

1. 修改源码后递增 Makefile 中 VERSION，必要时同步递增 KUBECTL_VERSION；
2. 先构建 amd64 镜像并在集群实测；
3. 再逐架构推送：make push ARCH=amd64|arm|arm64|ppc64le|s390x。

非 amd64 架构构建会先调用 register.sh 注册 qemu 用户态模拟器（CHANGELOG v6.3 最早引入 arm/qemu 支持）。amd64 的 push 目标额外执行"旧命名镜像"的 tag/推送以保证向后兼容。

五、结论与排障建议

• 版本即行为契约：部署 addon 前先确认其模式标签——期望"模板即真理、删除即清理"用 Reconcile，期望"允许用户自由编辑、仅兜底重建"用 EnsureExists；这两类语义的边界正是 v9.1.2 等修复的焦点。
• prune 白名单是安全阀：--prune 只作用于 allowlist 内的资源类型；自定义 CRD 或特殊资源需通过 KUBECTL_EXTRA_PRUNE_WHITELIST / KUBECTL_PRUNE_WHITELIST_OVERRIDE 显式纳入，否则不会被误删，见 kube-addons.sh。
• HA 场景务必校验 leader 身份：addon-manager 依赖 kube-controller-manager 的 Lease 判主，若发现多 master 下重复 reconcile，可先检查对应 kube-controller-manager Lease 的 holderIdentity 与各节点 HOSTNAME 前缀是否匹配（v9.0.2、v9.1.4 两处修复均为该路径历史坑位）。
• 一切以 $ADDON_PATH 为期望源：对 Reconcile 类 addon 的直接 kubectl edit 是徒劳的，主循环会在下一个周期内将其还原——这也解释了为何 CHANGELOG 反复强调 manifest 才是唯一事实来源。