#从 Alauda Container Platform Tracing 迁移

本文档介绍如何将现有的、基于旧版 Alauda Container Platform (ACP) Tracing 栈的 tracing 部署——即 Alauda Build of Jaeger（Jaeger 1.60.0）加上 Alauda Build of OpenTelemetry——迁移到基于 Jaeger v2（2.16.0）加上 Alauda Build of OpenTelemetry v2 的 Alauda Distributed Tracing。

迁移分为两个阶段：

1. OpenTelemetry 栈迁移。 将旧版 Alauda Build of OpenTelemetry Operator 和 Collector 替换为 Alauda Build of OpenTelemetry v2。应用 Pod 会重新部署，以注入 v2 Java 智能体。完成此阶段后，telemetry 由 v2 Collector 收集，但仍写入旧版 Jaeger 后端。此阶段请参照 从 Alauda Build of OpenTelemetry 迁移到 Alauda Build of OpenTelemetry v2。

2. Jaeger 后端迁移。 在旧版 Jaeger 旁边部署一个新的 Jaeger v2 实例，将 v2 Collector 的 trace exporter 切换到新后端，并在旧版保留期结束后卸载旧版 Jaeger。

切换完成后，新的 trace 数据会流入新的 Jaeger v2 后端，而旧版 Jaeger 仍会继续提供此前已存储的 traces。待旧版保留期结束（默认 7 天）后，旧版栈将被卸载。

#概述

#ACP Tracing 与 Alauda Distributed Tracing 之间的变化

关于 OpenTelemetry Operator、Collector 和 Instrumentation 资源的变更（包括现在必需的 spec.java.image 字段、Service Mesh v1 不兼容性，以及 Collector 配置 schema 迁移），请参见 OpenTelemetry v2 迁移指南中的 v1 与 v2 之间的变化。

#迁移中断窗口

trace 采集会在两个位置中断：

1. 在 OpenTelemetry v1 → v2 迁移期间，从旧版 OpenTelemetryCollector 被删除开始，到 v2 OpenTelemetryCollector 变为 ready 结束。请参见 OpenTelemetry v2 迁移指南中的 迁移中断窗口。

2. 在 Jaeger 切换期间，当对 v2 Collector 进行 patch，将其 trace exporter 从旧版 Jaeger 重定向到新的 Jaeger v2 后端时。Collector deployment 会重新滚动，因此在滚动期间可能会出现短暂的采集间隙。

在这两个窗口期间，应用 Pod 都会继续正常运行，但在间隙中生成的 telemetry 可能会被临时缓冲，并且如果无法及时导出，则可能会被丢弃。请将每个阶段安排在低流量窗口，并提前通知 telemetry 使用者（开发人员、SRE、Kiali 用户）。

在整个迁移过程中，旧版 Jaeger 查询路径始终可用，因此在新流水线启动期间，之前存储的 traces 仍可在旧版 Jaeger UI 中搜索。

#迁移流程概览

[Stage 1] Migrate Alauda Build of OpenTelemetry to v2 (per external guide)
              ↓ v2 Collector keeps writing traces to the legacy Jaeger
[Step 1]  Deploy the new Jaeger v2 instance (jaeger-system)
[Step 2]  Switch the v2 OpenTelemetry Collector to write to the new Jaeger
              ↓ trace ingestion cutover; new traces go to the new Jaeger
[Step 3]  Verify the migration
              ↓
[Observation] ≤ 7 days — legacy Jaeger remains queryable for historical traces
              ↓
[Step 4]  Uninstall the legacy Jaeger instance and Operator
[Step 5]  Disable the legacy feature switch and clean up legacy ES indices

#trace 数据连续性策略

按照 OpenTelemetry v2 迁移指南中关于 重新创建 OpenTelemetryCollector 资源 的说明，在 OpenTelemetry v2 迁移期间，v2 OpenTelemetry Collector 会部署到相同的 namespace，并使用相同的 Service 名称（cpaas-system 中的 otel-collector）作为旧版 Collector。将 OTLP 导出到 otel-collector.cpaas-system 的应用无需更改配置即可继续工作。

在 Jaeger 切换完成后，trace 数据会按时间清晰分区：

• 在切换前采集的 traces 只保留在旧版 Jaeger 中。只要旧版 jaeger-es-index-cleaner 仍保留它们，就可以通过 <platform-url>/clusters/<cluster>/acp/jaeger 这个旧版 Jaeger UI 查询；默认情况下，它们会在索引创建日期起 7 天后被清理。
• 在切换后采集的 traces 只会写入新的 Jaeger v2 后端。可以通过 <platform-url>/clusters/<cluster>/jaeger 这个新的 Jaeger UI 查询。

在观察期内，旧版 Jaeger 实例及其 Operator 会有意 保持运行，以便用户可以继续通过旧版 UI 搜索最近的历史 traces。待旧版保留期完全过期（≥ 7 天）后，会在 清理 中卸载旧版栈。

#前提条件

• cluster administrator 角色的用户已建立有效的 ACP CLI（kubectl）会话。
• 当前已安装旧版 ACP Tracing 栈（包含 Jaeger 实例的 Alauda Build of Jaeger Operator，以及包含一个 OpenTelemetryCollector 和一个或多个 Instrumentation 资源的 Alauda Build of OpenTelemetry）。
• Elasticsearch 8.x 可从集群访问，并且您拥有具备创建 ILM policy、index template 和 index alias 权限的 Elasticsearch 用户。
• 运行迁移命令的工作站上已安装 jq 和 envsubst 命令行工具。
• 已通知 telemetry 使用者（开发人员、Kiali 用户、SRE 仪表板）以及应用所有者有关计划中的中断窗口。

#迁移前任务

#将 Alauda Build of OpenTelemetry 迁移到 v2

在迁移 Jaeger 后端之前，请先按照 从 Alauda Build of OpenTelemetry 迁移到 Alauda Build of OpenTelemetry v2 完成从 Alauda Build of OpenTelemetry 到 Alauda Build of OpenTelemetry v2 的迁移。该指南涵盖以下内容：

• 备份并卸载旧版 Alauda Build of OpenTelemetry Operator 及其 OpenTelemetryCollector 和 Instrumentation 资源。
• 安装 v2 Operator。
• 准备 Java 自动埋点镜像，并重新创建 OpenTelemetryCollector 和 Instrumentation 资源，包括设置现在必需的 spec.java.image 字段。
• 重新部署应用 Pod，以便注入新的 Java 智能体。

在此阶段结束时：

• v2 Alauda Build of OpenTelemetry Operator 已安装，旧版 Operator 已卸载。
• cpaas-system 中的 v2 OpenTelemetryCollector 正在运行，其 trace exporter 仍指向旧版 Jaeger（这是根据 v1 备份重新创建 Collector 的自然结果）。
• 所有 Instrumentation 资源都已设置 spec.java.image，并且应用 Pod 已重新部署并注入 v2 Java 智能体。

在本指南的 将 v2 OpenTelemetry Collector 切换到新的 Jaeger 之前，trace 采集会继续流向旧版 Jaeger。

#盘点旧版 Jaeger 部署

请捕获旧版 Jaeger 的当前状态，以便了解迁移范围并生成用于回滚的备份。

1. 列出旧版 Alauda Build of Jaeger Operator 和 Jaeger 实例：

   kubectl get csv -A | grep -i jaeger
   kubectl get jaeger -A

2. 记录旧版 Jaeger 资源中引用的旧版 Elasticsearch endpoint、凭据和索引前缀。它们也将被新 Jaeger v2 实例复用。

#备份旧版 Jaeger 资源

导出旧版 Jaeger 资源，以便在需要时重新构建它们（以及回滚）：

mkdir -p ./acp-tracing-backup

# Jaeger CR (covers the jaeger-prod instance in cpaas-system).
kubectl get jaeger -A -o yaml \
  > ./acp-tracing-backup/jaegers.yaml

# Alauda Build of Jaeger Operator Subscription and CSV.
kubectl get subscription -n jaeger-operator jaeger-operator -o yaml \
  > ./acp-tracing-backup/jaeger-v1-subscription.yaml || true
kubectl -n jaeger-operator get csv -o yaml \
  > ./acp-tracing-backup/jaeger-v1-csv.yaml || true

# Supporting resources for jaeger-prod in cpaas-system. Each is removed in
# Cleanup, so back them up here so rollback can restore them. Skip silently
# (|| true) if a resource is not present in this environment.
kubectl -n cpaas-system get ingress     jaeger-prod-query         -o yaml \
  > ./acp-tracing-backup/jaeger-prod-ingress.yaml             || true
kubectl -n cpaas-system get podmonitor  jaeger-prod-monitor       -o yaml \
  > ./acp-tracing-backup/jaeger-prod-podmonitor.yaml          || true
kubectl -n cpaas-system get rolebinding jaeger-prod-rb            -o yaml \
  > ./acp-tracing-backup/jaeger-prod-rolebinding.yaml         || true
kubectl -n cpaas-system get role        jaeger-prod-role          -o yaml \
  > ./acp-tracing-backup/jaeger-prod-role.yaml                || true
kubectl -n cpaas-system get sa          jaeger-prod-sa            -o yaml \
  > ./acp-tracing-backup/jaeger-prod-sa.yaml                  || true
kubectl -n cpaas-system get secret      jaeger-prod-oauth2-proxy  -o yaml \
  > ./acp-tracing-backup/jaeger-prod-oauth2-proxy-secret.yaml || true
kubectl -n cpaas-system get secret      jaeger-prod-es-basic-auth -o yaml \
  > ./acp-tracing-backup/jaeger-prod-es-basic-auth-secret.yaml || true
kubectl -n cpaas-system get configmap   jaeger-prod-oauth2-proxy  -o yaml \
  > ./acp-tracing-backup/jaeger-prod-oauth2-proxy-configmap.yaml || true

#验证 Elasticsearch 容量

新的 Jaeger 会写入一组独立的索引家族（acp-<cluster>-jaeger-*），而旧索引家族（acp-tracing-<cluster>-jaeger-*）会在旧版保留期内逐步过期。请预留一份额外完整保留周期所需的 trace 存储空间。若启用 (可选) 为旧版 Jaeger 启用双写，则在观察期内请预留大约两倍的稳定态存储空间。

#迁移操作步骤

export JAEGER_NS="jaeger-system"
export JAEGER_INSTANCE_NAME="jaeger"
export JAEGER_ES_INDEX_PREFIX="acp-${CLUSTER_NAME}"      # different from the legacy "acp-tracing-${CLUSTER_NAME}"
export JAEGER_BASEPATH="/clusters/${CLUSTER_NAME}/jaeger"  # different from the legacy "/clusters/${CLUSTER_NAME}/acp/jaeger"

spec:
  config:
    exporters:
      debug: {}
      otlp:
        balancer_name: round_robin
        endpoint: dns:///jaeger-prod-collector-headless.cpaas-system:4317
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          receivers:  [otlp]
          processors: [memory_limiter, batch]
          exporters:  [debug, otlp] 

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp/jaeger-v2:
        endpoint: jaeger-collector.jaeger-system.svc.cluster.local:4317
        tls:
          insecure: true
      otlp: null
    service:
      pipelines:
        traces:
          exporters: [debug, otlp/jaeger-v2]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

#观察期

在切换完成后，请让旧版 Jaeger 继续运行 至少 7 天，以匹配旧版 esIndexCleaner.numberOfDays 的保留策略。在这个窗口期间：

• 旧版 Jaeger UI 会继续提供所有尚未被旧版 jaeger-es-index-cleaner 删除的切换前 traces。该 cleaner 会在每个索引创建约 7 天后将其移除；一旦所有切换前索引都被清理完毕，旧版 Jaeger 就不再保留任何有用数据，可以卸载。
• 新的 Jaeger 会累积切换后产生的 traces。请针对新的 Jaeger UI 和 v2 Java 智能体的指标名称验证仪表板、告警以及 Kiali 集成。
• 请清晰地传达这一分界：告诉用户新的 Jaeger UI 显示的是从切换开始之后的 traces，而较旧的 traces 仍保留在旧版 Jaeger UI 中。

如果切换前 traces 没有业务价值，您可以缩短或跳过观察期，直接进入 清理；代价是，一旦移除旧版栈，所有早于切换点的 traces 都将不再可访问。

#清理

kubectl -n cpaas-system delete ingress      jaeger-prod-query         --ignore-not-found
kubectl -n cpaas-system delete podmonitor   jaeger-prod-monitor       --ignore-not-found
kubectl -n cpaas-system delete jaeger       jaeger-prod               --ignore-not-found
kubectl -n cpaas-system delete rolebinding  jaeger-prod-rb            --ignore-not-found
kubectl -n cpaas-system delete role         jaeger-prod-role          --ignore-not-found
kubectl -n cpaas-system delete sa           jaeger-prod-sa            --ignore-not-found
kubectl -n cpaas-system delete secret       jaeger-prod-oauth2-proxy  --ignore-not-found
kubectl -n cpaas-system delete secret       jaeger-prod-es-basic-auth --ignore-not-found
kubectl -n cpaas-system delete configmap    jaeger-prod-oauth2-proxy  --ignore-not-found

kubectl -n jaeger-operator delete subscription jaeger-operator --ignore-not-found

kubectl get jaeger -A
kubectl delete crd jaegers.jaegertracing.io

#（可选）为旧版 Jaeger 启用双写

将 v2 OpenTelemetry Collector 配置为把每个 span 同时写入新的 Jaeger 和旧版 Jaeger，是一种可选方案，用来替代默认的单写 pipeline。以下场景可考虑启用：

• 并行验证。 您希望在完全信任新后端之前，使用生产流量将新的 Jaeger 与旧版 Jaeger 进行对比。
• 更快的原地回滚。 如果新 Jaeger 在观察期内出现问题，您只需通过一次 patch 将 otlp/jaeger-v2 从 trace pipeline 中移除，旧版 Jaeger 就会继续不中断地接收 traces。
• 逐步切换 UI。 不同团队计划按各自节奏从旧版 UI 切换到新版 UI，而您希望在过渡期间两个 UI 都能显示切换后的数据。

权衡如下：

• 在观察期内，Elasticsearch 的写入负载和存储使用量大约会 翻倍，因为每个 span 都会被索引到两组索引家族中。
• 在卸载旧版 Jaeger 之前，必须通过 停止双写 中的额外 patch 回退 trace pipeline。
• 必须监控两个导出 pipeline 的失败情况（otelcol_exporter_send_failed_spans_total，分别针对 otlp/jaeger-v2 和 otlp/jaeger-v1）。

双写不会将切换前的 traces 回填到新的 Jaeger 中；切换前的 traces 只能通过旧版 Jaeger UI 查询。

#启用双写

在 将 v2 OpenTelemetry Collector 切换到新的 Jaeger 收敛之后，otel Collector 只有 otlp/jaeger-v2 这一个向 Jaeger 后端写入 traces 的 exporter（trace pipeline 为 [debug, otlp/jaeger-v2]）。请对 Collector 进行 patch，把旧版 Jaeger 作为第二个 exporter otlp/jaeger-v1 加回去，镜像恢复被切换步骤移除的原始 otlp exporter 的旧版 Jaeger endpoint、headless-Service 负载均衡和 TLS 设置：

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp/jaeger-v1:
        endpoint: dns:///jaeger-prod-collector-headless.cpaas-system:4317
        balancer_name: round_robin
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          exporters: [debug, otlp/jaeger-v2, otlp/jaeger-v1]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

应用 patch 后，每个 span 都会同时写入两个 Jaeger 后端。

#停止双写

在观察期结束后、卸载旧版 Jaeger 实例之前，请从 trace pipeline 中移除旧版 exporter：

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp/jaeger-v1: null
    service:
      pipelines:
        traces:
          exporters: [debug, otlp/jaeger-v2]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

应用此 patch 后，v2 Collector 将只会把 traces 写入新的 Jaeger。此时即可继续执行 卸载旧版 Jaeger 实例。

#回滚

关于 OpenTelemetry v1 → v2 阶段的回滚，请参见 OpenTelemetry v2 迁移指南中的 回滚。对于本文档中执行的 Jaeger 迁移阶段，请根据当前所处阶段选择相应的回滚路径：

#FAQ

应用是否需要更新它们的 OTLP endpoint？

不需要。按照 OpenTelemetry v2 迁移指南中 重新创建 OpenTelemetryCollector 资源 的说明，v2 OpenTelemetry Collector 会部署在相同的 namespace（cpaas-system）中，使用相同的 Service 名称（otel-collector）和相同的端口（4317/4318）。导出到 otel-collector.cpaas-system:4317 的工作负载无需任何更改即可继续工作。

新的 Jaeger UI 会显示切换前的 traces 吗？

不会。切换前的 traces 只存储在旧版 Jaeger 中，并且在旧版保留窗口期间（默认 7 天）仍可通过旧版 Jaeger UI 查询。新的 Jaeger UI 从切换点开始才会显示 traces。请提前向用户说明这一点，并在观察期内将旧 traces 的查询引导到旧版 UI。

什么时候应该启用双写？

默认的单写路径足以满足大多数迁移场景。仅当以下情况之一成立时，才启用双写（(可选) 为旧版 Jaeger 启用双写）：

• 您需要在依赖新 Jaeger 之前，使用生产流量验证其与旧版 Jaeger 的一致性。
• 不同团队会按各自计划从旧版 UI 切换到新版 UI，并且您希望在过渡期间两个 UI 都显示切换后的数据。
• 您希望在观察期内拥有最快的原地回滚路径。

请注意，双写会在观察期内使 Elasticsearch 的写入负载和存储使用量大约翻倍，并且会在卸载旧版 Jaeger 之前额外增加一个 patch 步骤。

旧版和新 Jaeger 能共用同一个 Elasticsearch 索引吗？

不能。旧版 Jaeger 使用按日期命名的每日索引（acp-tracing-<cluster>-jaeger-span-YYYY-MM-DD），而 Jaeger v2 使用 rollover 别名（acp-<cluster>-jaeger-span-write / -read，其后端为 *-000001、*-000002，等等）。两者的 schema 和生命周期管理方式不同，因此两组索引家族必须保持分离。请保留 部署新的 Jaeger v2 实例 中显示的默认前缀，以避免冲突。

观察期需要额外多少 Elasticsearch 存储？

在默认单写路径下，新的索引家族会从零开始增长，而旧索引家族会在旧版保留期内逐步过期；请预留一份额外完整保留周期所需的 trace 存储作为稳定态缓冲。若启用双写，则在观察期内请为旧索引家族预留大约两倍的稳定态大小，并为重试和采集突发预留额外余量。

迁移过程中可以启用 Service Performance Monitoring（SPM）吗？

SPM 是可选功能，可以在 验证迁移 之后的任何时间启用。请参照 (可选) 启用 Service Performance Monitoring（SPM），为 v2 OpenTelemetry Collector 添加 spanmetrics connector，并在新的 Jaeger 中配置 metrics 后端。