2. 集群注册与生命周期管理

在多集群治理中，Fleet 的价值并不只是“把多个集群列在一起”，而是让每个成员集群从接入那一刻起就具备可识别、可授权、可追踪、可升级、可退出的完整生命周期。集群注册是这条生命周期的起点，它决定了后续策略分发、可观测采集、故障定位和容量治理能否可靠进行。本节围绕接入流程、引导凭证、元数据、纳管与注销、版本与节点池生命周期五个关键环节展开，重点说明实际落地时应该准备什么、系统内部发生了什么、以及如何判断接入是否成功。

一、集群接入流程：从“陌生节点”到“受管成员”

Fleet 的集群接入通常不是一次简单的 API 调用，而是一个由引导凭证驱动的双向信任建立过程。以常见的 Fleet 实现为例，接入流程可以拆解为以下阶段：

1. 创建注册令牌（Registration Token）：由 Fleet 控制面生成一个有时效性的引导凭证，通常包含令牌值、有效期、可注册的集群数量上限以及允许的标签范围。令牌本身不直接等同于集群身份，而是“允许某个代理发起注册”的入场券。
2. 在目标集群部署 Fleet Agent：Agent 以 Deployment 或 DaemonSet 形式运行在目标集群中，启动时读取令牌，向 Fleet 控制面发起注册请求。请求中携带集群名称、API Server 地址、CA 证书指纹、Agent 版本等基础信息。
3. 控制面校验并签发集群身份：控制面验证令牌有效性、是否超限、是否过期，然后为该集群生成唯一的集群 ID 和客户端证书。此后 Agent 使用该证书进行双向 TLS 通信，令牌不再参与后续通信。
4. 建立长连接与心跳：Agent 与控制面建立 gRPC 或 WebSocket 长连接，周期性上报心跳、资源摘要和健康状态。控制面据此将集群标记为 Ready 或 NotReady。
5. 元数据落库与标签绑定：控制面将集群元数据写入注册表，并根据 Agent 上报的标签或管理员预设的标签，将集群归入相应的 ClusterGroup，为后续策略选择提供依据。

判断接入是否成功，不能只看 Agent Pod 是否 Running。更可靠的判断依据是：控制面中集群状态是否为 Ready、最近一次心跳时间是否在阈值内（例如 60 秒）、集群 ID 是否稳定不变、以及是否已出现在预期的 ClusterGroup 中。如果 Agent 日志中出现 token expired 或 registration rejected，说明引导凭证环节失败，需要重新签发令牌，而不是反复重启 Agent。

二、引导凭证：安全接入的“一次性钥匙”

引导凭证是集群接入阶段最容易被忽视、也最容易出问题的部分。它的核心设计原则是：短期有效、一次使用、最小权限、可审计。在实际生产中，建议为每个批次或每个环境签发独立令牌，而不是所有集群共用一个长期令牌。例如，可以为生产环境签发一个有效期为 2 小时、最多允许 10 个集群注册的令牌，为测试环境签发另一个令牌。这样即使令牌泄露，影响范围也可控。

令牌通常以 Secret 形式存在于控制面，Agent 通过环境变量或挂载文件读取。注册成功后，Agent 应主动清除本地令牌文件，避免残留。控制面在令牌使用次数达到上限或超过有效期后，应自动将其标记为失效。如果注册失败，需要区分是令牌问题、网络问题还是证书问题：令牌问题通常表现为 401 Unauthorized 或 token expired；网络问题表现为连接超时；证书问题则表现为 TLS 握手失败。不同错误对应不同的修复路径，不能一概而论。

三、集群元数据：让集群“可被理解”

集群注册完成后，控制面需要保存一组稳定的元数据，用于后续的策略选择、容量统计和故障定位。典型的元数据包括：集群唯一 ID、集群名称、API Server 地址、CA 证书指纹、Agent 版本、所属区域、环境标签（如 env=prod）、节点池摘要、最近心跳时间等。这些字段中，集群 ID 和 CA 指纹属于身份类元数据，注册后不应随意变更；标签和节点池摘要属于描述类元数据，可以随集群状态动态更新。

元数据的质量直接影响 Fleet 的治理能力。例如，如果集群没有正确打上 region 和 env 标签，后续基于 ClusterGroup 的策略分发就会失效，导致某些集群被遗漏或误配。因此，建议在接入流程中强制要求填写最小标签集，并在控制面侧做校验。对于节点池摘要，可以定期从集群上报的节点信息中聚合生成，而不是手工维护。

四、纳管与注销：有进有出，状态可控

纳管（Enrollment）是指集群正式成为 Fleet 受管成员的过程。它不仅仅是注册成功，还包括：集群被分配到正确的 ClusterGroup、基础策略已下发并生效、可观测采集已启动、健康检查已纳入监控。只有这些条件都满足，才能认为集群真正“纳管完成”。在实际操作中，可以通过一个简单的检查清单来确认：集群状态为 Ready、心跳正常、标签正确、策略已同步、日志和指标已上报。

注销（Deregistration）则是纳管的逆过程。注销不是简单删除记录，而是一个有序的“排空—断开—清理”流程。首先将集群标记为 Draining，停止向其分发新策略；然后等待其上工作负载迁移或确认可安全下线；接着通知 Agent 停止上报并断开连接；最后从控制面删除集群记录和关联的证书。如果跳过排空直接删除，可能导致策略残留、监控断点或审计缺失。注销完成后，应确认控制面中不再有该集群的活跃连接，且相关 Secret 和证书已被清理。

五、版本与节点池生命周期

集群接入后，版本和节点池的生命周期管理是持续治理的重点。版本生命周期包括：Agent 版本、Kubernetes 版本和 Fleet 控制面版本的兼容性管理。建议维护一张兼容性矩阵，明确哪些 Agent 版本可以连接哪些控制面版本。当控制面升级时，应优先升级 Agent，避免出现协议不兼容。Agent 升级通常采用滚动方式，先升级少量集群验证，再分批推进。

节点池生命周期则关注节点池的创建、扩缩容、升级和下线。在 Fleet 中，节点池信息通常作为集群元数据的一部分上报，用于容量统计和调度决策。当某个节点池需要下线时，应先将其上的工作负载迁移到其他节点池，再执行缩容和删除。对于跨集群的节点池治理，可以通过标签将不同集群的节点池归类，再结合策略统一管理其升级窗口和最大不可用比例。

总体来看，集群注册与生命周期管理是一条从“引导凭证”到“元数据”再到“纳管/注销”和“版本/节点池”的完整链路。每个环节都有明确的输入、状态变化和判断依据。只有把这条链路做扎实，Fleet 才能在多集群环境中稳定地分发策略、采集信号并支撑可靠性治理。