#从 Alauda Container Platform Tracing 迁移

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

迁移分两个阶段进行：

1. OpenTelemetry 栈迁移。 将旧版 Alauda Build of OpenTelemetry Operator 和 Collector 替换为 Alauda Build of OpenTelemetry v2。对应用 Pod 进行滚动发布，以注入 v2 Java agent。完成此阶段后，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 继续提供已存储的历史 trace。等旧版保留期到期后（默认 7 天），再卸载旧版栈。

#概览

#ACP Tracing 与 Alauda Distributed Tracing 的变化

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

#迁移中断窗口

trace ingestion 会在两个位置中断：

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

2. 在 Jaeger 切换期间，当 v2 Collector 被打补丁，将 trace exporter 从旧版 Jaeger 重定向到新的 Jaeger v2 后端时。Collector 会进行滚动，因此在滚动过程中可能出现短暂的 ingestion 间隙。

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

在整个迁移过程中，旧版 Jaeger query 路径始终可用，因此在新流水线启动期间，之前存储的 trace 仍可在旧版 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 资源 的指导，v2 OpenTelemetry Collector 会部署在与旧版 Collector 相同的 namespace 中，并使用相同的 Service 名称（cpaas-system 中的 otel-collector）。向 otel-collector.cpaas-system 导出 OTLP 的应用无需更改任何配置即可继续工作。

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

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

在观察期内，旧版 Jaeger 实例及其 Operator 会刻意 保持运行，以便用户仍可通过旧版 UI 查询最近的历史 trace。等旧版保留数据完全过期后（≥ 7 天），即可在 清理 中卸载旧版栈。

#前提条件

• 由拥有 cluster-admin 角色的集群管理员建立的有效 ACP CLI (kubectl) 会话。
• 当前已安装旧版 ACP Tracing 栈（Alauda Build of Jaeger Operator 与一个 Jaeger 实例，以及 Alauda Build of OpenTelemetry 与一个 OpenTelemetryCollector 和一个或多个 Instrumentation 资源）。
• 集群可访问 Elasticsearch 8.x，并且你拥有有权限创建 ILM 策略、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 auto-instrumentation image，并重新创建 OpenTelemetryCollector 和 Instrumentation 资源，包括设置现在必需的 spec.java.image 字段。
• 对应用 Pod 进行滚动发布，以注入新的 Java agent。

在此阶段结束时：

• v2 Alauda Build of OpenTelemetry Operator 已安装，旧版 Operator 已卸载。
• cpaas-system 中的 v2 OpenTelemetryCollector 正在运行，并且其 trace exporter 仍指向旧版 Jaeger（这是从 v1 备份重新创建 Collector 的自然结果）。
• 所有 Instrumentation 资源都已设置 spec.java.image，并且应用 Pod 已使用 v2 Java agent 完成滚动发布。

在本指南的 将 v2 OpenTelemetry Collector 切换到新的 Jaeger 之前，trace ingestion 会继续流入旧版 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-*）会在旧版保留期内逐步过期。请在 Elasticsearch 中预留至少额外一个完整保留周期所需的 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 agent 指标名称上验证仪表板、告警以及 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，是默认单一导出流水线之外的一种可选方案。当出现以下任一情况时，可考虑使用：

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

权衡如下：

• 由于每个 span 都会被索引到两个索引族中，Elasticsearch 的写入负载和存储占用在观察期内会大约 翻倍。
• 在卸载旧版 Jaeger 之前，trace pipeline 必须通过 停止双重导出 额外打一个补丁才能恢复。
• 需要监控两个导出流水线的失败情况（otelcol_exporter_send_failed_spans_total，分别针对 otlp/jaeger-v2 和 otlp/jaeger-v1）。

双重导出不会将切换前的 traces 回填到新 Jaeger；切换前的 traces 仍然只能通过旧版 Jaeger UI 查询。

#启用双重导出

在 将 v2 OpenTelemetry Collector 切换到新的 Jaeger 收敛之后，otel Collector 只有一个向 Jaeger 后端写入的 trace exporter，即 otlp/jaeger-v2（trace pipeline 为 [debug, otlp/jaeger-v2]）。请对 Collector 打补丁，将旧版 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

补丁应用后，每个 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

应用该补丁后，v2 Collector 只会向新的 Jaeger 写入 traces。现在可以继续执行 卸载旧版 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。请提前告知用户，并在观察期内引导他们通过旧版 UI 查询更早的 traces。

应该在什么时候启用双重导出？

默认的单一导出路径足以满足大多数迁移场景。只有在以下情况之一成立时，才启用双重导出（(可选) 启用向旧版 Jaeger 的双重导出）：

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

请注意，双重导出会使观察期内 Elasticsearch 的写入负载和存储量大约翻倍，并且在卸载旧版 Jaeger 之前需要额外执行一个补丁步骤。

旧版和新的 Jaeger 可以共享同一个 Elasticsearch 索引吗？

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

观察期内需要多少额外的 Elasticsearch 存储空间？

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

迁移过程中可以启用 Service Performance Monitoring (SPM) 吗？

SPM 是可选的，并且可以在 验证迁移 之后的任何时间启用。请按照 (可选) 启用 Service Performance Monitoring (SPM) 的说明，添加 spanmetrics connector 并在新的 Jaeger 中配置 metrics 后端。