#升级

本章介绍 ACP 4.4 日志堆栈支持的升级路径。如果集群仍使用 Alauda Container Platform Log Storage for Elasticsearch，请参阅 从 Log Storage for Elasticsearch 升级 和 历史数据迁移。其他路径包括一次性的 从 ACP 4.3 到 4.4 过渡（从 chart 转向 operator，并通过自动迁移 Runnable 将 SRE 工作量保持为两个步骤），以及此后的每次 ACP 4.4 之后 升级（普通的 OLM channel 升级）。

#从 ACP 4.3 到 4.4

ACP 4.4 日志堆栈使用 Alauda Container Platform Log Storage Management operator 和由用户管理的外部 endpoint，替代 ACP 4.3 基于 chart 的 ClickHouse 和 Kafka 部署。该 operator 提供自动迁移 Runnable，将升级转变为 SRE 团队的两步、零接触流程：

1. 在安装 operator 前创建一个 Secret（platform-default-mq-conn）。
2. 安装 operator。

其余工作——修补旧版 chart 资源，使 helm uninstall 无法销毁这些资源；根据运行中的 chart values 生成 PlatformLogForward CR；根据 chart 的 ClickHouse 凭据初始化存储侧 Secret；以及持续执行重试循环，直到新堆栈达到 Ready——均由 operator 在启动时执行。

本节说明 operator 所依赖的确切契约。如果你的升级跳过了下面的结构（例如，在部署 4.4 operator 前，你已经在 4.3 chart 上运行了 helm uninstall，导致 chart values 不再可发现），则需要像全新安装一样手动编写 PLF；请参阅 安装。

#预检查：SRE 开始前必须执行的操作

唯一必需的预检查步骤是：

1. 在存储集群的 cpaas-system 中创建 Secret/platform-default-mq-conn。有关完整契约，请参阅安装中的 Kafka 部分；必需的键包括 bootstrap、username、password、sasl_mechanism、topics.log、topics.event、topics.audit 和 kafkaClusterName，可选键包括 tls.ca 和 tls.insecure_skip_verify。

Kafka 侧不会自动迁移，因为在 ACP 4.4 中 Kafka 完全由 SRE 管理：operator 不再从 chart values 中发现 Kafka，也无法代你生成凭据。

存储侧（外部 ClickHouse 或 OpenSearch endpoint 以及 DML 凭据）会由 operator 在启动时根据 chart 的运行中 values 自动派生。在 ClickHouse 路径上，operator 会创建 Secret/platform-default-ch-conn；在 OpenSearch 路径上，则会创建 Secret/platform-default-os-conn。这些 Secret 的名称与全新安装时需要创建的名称相同——区别仅在于由谁写入（全新安装时由 SRE 写入，升级时由自动迁移 Runnable 写入）。如果你希望手动创建 Secret（例如 chart values 被外部覆盖时），operator 会使用同名的现有 Secret。

可选：在安装 operator 前，为 operator Deployment 设置环境变量 STRICT_AUTO_MIGRATION=true。在严格模式下，任何自动迁移步骤失败都会导致启动失败，operator 会生成 K8s Event 并拒绝提供服务。对于不接受部分迁移的发布，建议使用此模式；稳定运行时请保持未设置。

#安装 operator

按照安装 § 全新安装中相同的操作步骤，在存储集群上安装 Alauda Container Platform Log Storage Management operator（binary name 为 log-storage-operator）。operator pod 启动后，其 AutoMigrationRunnable（internal/automigration/runnable.go，通过 mgr.Add(automigration.NewRunnable(...)) 添加）会立即以 30 秒为间隔开始迁移循环。

#operator 自动执行的操作

AutoMigrationRunnable 会在每个时间间隔执行以下步骤，直到达到 .status.migrationPhase == Converged。每个步骤都是幂等的：如果其要创建的状态已经存在，则会直接跳过。

#1. 检测 4.3 → 4.4 过渡

满足以下条件时，检测启发式规则会匹配：

• PlatformLogForward/platform-default 不存在，或 .spec.externalStorage.type 为空，并且
• 旧版 chart 所有的资源存在于 cpaas-system 中——具体来说，是一个带有 app.kubernetes.io/managed-by=Helm 的 Deployment/razor，以及一个值以 alauda-log- 为前缀的 helm.sh/chart 标签。

匹配后，.status.migrationPhase 会转移到 Detected，循环继续执行。在全新安装中（没有 chart 标签，也没有旧版 razor Deployment），循环会在此处停止，并等待 SRE 手动编写 PLF。

#2. patch-keep-legacy — 保护 chart 资源免受 helm uninstall 影响

operator 会将注解 helm.sh/resource-policy: keep 添加到 cpaas-system 中 30 种旧版 chart 所有资源上。选择器为 app.kubernetes.io/managed-by=Helm,app.kubernetes.io/instance in (chart-alauda-log-center, chart-alauda-log-clickhouse, chart-alauda-log-agent)。

这 30 种资源包括：ClickHouseInstallation/cpaas-clickhouse、AutoRepair CR、由 chi 派生的 Service、StatefulSet/chi-cpaas-clickhouse-*、StatefulSet/razor、StatefulSet/kafka-*、Deployment/aggregate-vector、Deployment/razor、chi 所有的 PVC、kafka PVC、razor-data-* PVC（包括根据 Bug 115 按名称模式匹配的 topolvm 动态 PVC）、底层 PV（根据 Bug 58 v7 重新添加 persistentVolumeReclaimPolicy: Retain）、ConfigMap/clickhouse-storage-config、ConfigMap/logging-ttl-config、ConfigMap/log-policy-config、ConfigMap/log-center-configuration、Secret/aggregate-vector-config、Secret/secret-bridge、Secret/cpaas-clickhouse-users、MonitorDashboards、AlertRules、RdsKafka / KafkaTopic / KafkaUser / KafkaNodePool / StrimziPodSet CR、Feature/log-center、chart ServiceAccount / Role / RoleBinding，以及 chart 的 Subscription。

添加修补后，可以在任何时间卸载 chart，而不会销毁数据。

#3. derive-plf — 根据 chart values 构建 PlatformLogForward CR

operator 读取以下输入并生成 PlatformLogForward/platform-default：

如果 Secret/platform-default-ch-conn（ClickHouse 路径）或 Secret/platform-default-os-conn（OpenSearch 路径）不存在，operator 会立即写入它，并填充 endpoint、username、password、tls.ca 和 tls.insecure_skip_verify（最后一项是智能默认值：存在 CA 时使用 strict，仅有自签名材料时跳过——参见 Bug 131）。这与 SRE 在全新安装时需要创建的 Secret 具有相同的结构和名称；区别仅在于此处由自动迁移 Runnable 代你填充。如果 Secret 已存在，operator 不会修改其内容。

你在预检查期间创建的 Kafka mq-conn Secret 会被验证，但 operator 从不向其中写入内容。

#4. 应用 PLF 并驱动 reconcile

operator 会应用派生的 PLF（仅在 PLF 不存在时应用，从不覆盖手动创建的 PLF），然后移交给其主 PlatformLogForwardReconciler。从此开始，reconcile 流程与全新安装完全相同：添加 finalizer，重新创建 Feature/log-center、MonitorDashboard、AlertRule、ConfigMap/log-policy-config、ConfigMap/logging-ttl-config 和 ConfigMap/aiops-logging-migrations，并为其添加指向 PLF 的 ownerReference 回指（Bug 113）；schema-migrations Job 针对外部 ClickHouse 运行，以推进 schema；然后发布新的 Deployment/aggregate-vector 和 Deployment/razor。

#5. 等待 Ready

持续观察 PlatformLogForward/platform-default.status.conditions，直到 Ready 变为 True。需要按顺序观察的中间条件包括 MessageQueueReady、StorageReady、SchemaMigrated、CollectorReady、RazorReady。有关每项的具体检查，请参阅如何验证全新安装——升级路径使用相同的状态对象。

在健康的 AutoMigrationRunnable tick 上，.status.migrationPhase 会经过 Detected → LegacyPatched → PLFDerived → PLFApplied → Converged。当其读取为 Converged 时，迁移完成。

#Ready 之后：弃用旧 chart

一旦 Ready=True，chart 便不再发挥作用——operator 已接管其 Deployments 和 Services，并正在驱动新的 aggregate-vector 和 razor。chart 的资源可以安全删除，因为它们要么已携带 helm.sh/resource-policy: keep（因此 helm uninstall 不会触碰数据），要么在你误删后会由 operator 在下一次 reconcile 时重新创建。

你可以在方便时卸载 chart：

helm uninstall chart-alauda-log-center -n cpaas-system
helm uninstall chart-alauda-log-clickhouse -n cpaas-system
helm uninstall chart-alauda-log-agent -n cpaas-system

如果某个资源在卸载时携带 helm.sh/resource-policy: keep，Helm 会跳过该资源。这就是迁移所依赖的全部机制。

#回滚计划

如果升级进入 Converged，但下游检查失败（例如 razor-api 版本不兼容，或 OpenSearch 上的 ISM policy 行为异常等），回滚路径如下：

1. kubectl delete platformlogforward platform-default。operator 的 handlePLFTerminating 会清理自上述第 4 步以来创建的所有资源。
2. 卸载 operator（请参阅卸载中的对应步骤）。
3. 重新安装 ACP 4.3 chart。由于所有 chart 所有的资源仍然存在（受 helm.sh/resource-policy: keep 保护），chart 会重新接管这些资源。

你在预检查期间创建的 Kafka mq-conn Secret 与 chart 自身的资源无关，可以保留；4.3 chart 不会读取它。

#升级期间的已知问题

• 旧版 razor StatefulSet drain 条件。 PLF 会公开一个 LegacyRazorDrained 子条件（Bug 182、Bug 187）。它报告旧 chart 的 StatefulSet/razor 状态——要么已正常 drain，要么不存在（因为 chart 从未拥有 razor sts，或 sts 已被删除）。两种情况都算成功。未 drain 的旧 razor sts 会阻止新的 razor Deployment 接管日志主题。
• 自签名 CA 的 HTTPS ClickHouse 上的 schema-migrations。 如果派生的 platform-default-ch-conn Secret 最终包含 tls.insecure_skip_verify: true，而你之后提供了真实 CA（tls.ca），智能默认值会切换为严格验证。这是有意设计的行为——参见 Bug 131。
• 自动派生的存储凭据与轮换后的凭据。 platform-default-ch-conn（或 platform-default-os-conn）Secret 携带的是 chart 首次运行 operator 时所使用的存储凭据。如果之后在 ClickHouse 或 OpenSearch 侧轮换了这些凭据，则必须更新 Secret；operator 在第一次 tick 后不会再次派生凭据。
• STRICT_AUTO_MIGRATION 与临时 RBAC 错误的交互。 如果 operator 安装所携带的 RBAC 缺少自动迁移路径所需的任一角色（完整列表请参阅 Bug 108 和 Bug 122），严格模式将拒绝提供服务。非严格模式会在下一次 tick 重试；通常在 cluster-transformer 或 platform operator installer 完成后即可成功。

#ACP 4.4 之后

上述自动迁移流程是一次性的——仅当 operator 检测到 ACP 4.3 chart 形态时才会运行。一旦平台已运行 ACP 4.4 并且已有 PlatformLogForward，后续每次升级都只是通过 OLM 进行普通的 operator 升级，不再包含 chart 迁移步骤，也不需要 SRE 创建运行中安装已有资源之外的其他资源。

#ACP 4.4 内部（补丁版本升级）

v4.4.x → v4.4.y 会作为新的 ClusterServiceVersion，在同一个 Subscription channel 中交付。当你批准升级（或自动批准升级）时：

1. OLM 将 log-storage-operator Deployment 滚动更新为新镜像。
2. operator 使用更新后的逻辑对现有 PlatformLogForward/platform-default 执行 reconcile。任何随版本发布而带有新默认值的嵌入式资源（SQL migration、ISM policy、VRL transform、aggregate-vector 配置）都会在下一次 reconcile 时重新生成。
3. 如果该版本包含新的数据库 migration，schema-migrations Job 会针对外部 ClickHouse 运行该 migration，并将 schema_migrations.version 向前推进。aggvec init-container 会等待其变为 Complete，然后新的 aggvec pod 才会就绪。
4. Deployment/aggregate-vector 和 Deployment/razor 会滚动更新为新镜像。PLF 子条件（SchemaMigrated、CollectorReady、RazorReady）会在滚动更新期间变为 False，完成后恢复为 True。

无需 SRE 干预，两个由 SRE 创建的 Secret 以及 PlatformLogForward spec 都不需要编辑。

#从 ACP 4.4 升级到 ACP 4.5

ACP 4.4 → 4.5 只是普通的 OLM channel 升级，不包含破坏性变更。 PlatformLogForward v1alpha1 CRD、platform-default-mq-conn Secret 契约，以及 platform-default-ch-conn / platform-default-os-conn Secret 契约都会原样延续。客户在 4.4 上创建的 PLF 在升级后仍可正常工作，无需进行任何重写；除批准 Subscription 的新 CSV 外，也不需要执行任何 SRE 可见的操作。

你不会再次运行 patch-keep-legacy 或 derive-plf——这些子命令仅用于处理 4.3 时代基于 chart 的安装，在最初以 4.4 启动的平台上不会执行任何操作。4.4 → 4.5 不存在对应的一次性迁移流程。