#从 Alauda Container Platform Tracing 迁移

#部署新的 Jaeger v2 实例

按照 Alauda Distributed Tracing 安装指南中的部署 Alauda Build of Jaeger v2进行操作。新的 Jaeger v2 实例会部署在专用命名空间中（默认为 jaeger-system），因此不会与 cpaas-system 中旧版的 jaeger-prod 实例冲突。

到达变量设置步骤时，保留默认索引前缀和基础路径。两者都必须与旧版实例使用的值不同：

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

完成安装步骤后，验证以下内容：

• jaeger-system 中的 Jaeger Pod 为 Ready。
• Jaeger UI 可通过 <platform-url>/clusters/<cluster>/jaeger 访问。此时 UI 为空，因为尚无 exporter 向其写入数据，旧版索引也尚未附加。
• Service jaeger-collector.jaeger-system.svc.cluster.local 在端口 4317 接受 OTLP gRPC — 这就是 v2 OpenTelemetry Collector 将在将 v2 OpenTelemetry Collector 切换到新的 Jaeger中导出数据的端点。

#将旧版索引附加到新的读别名

上一步运行的 jaeger-es-rollover init Job 创建了新索引系列的 <prefix>-jaeger-<type>-read 和 <prefix>-jaeger-<type>-write 别名。Jaeger v2 通过读别名解析所有读取请求，因此只需将旧版日期索引添加到该别名，即可在新的 Jaeger UI 中查询迁移前的 trace。不会复制、重命名或重新索引任何内容，旧版 Jaeger 仍会继续提供相同的索引。

在切换前执行此步骤，以便新的 Jaeger UI 在开始接收 trace 时已经包含完整数据。

操作步骤

1. 设置旧版索引前缀。它是在清查旧版 Jaeger 部署中记录的 es.index-prefix 值：

   export LEGACY_ES_INDEX_PREFIX="acp-tracing-${CLUSTER_NAME}"

2. 将旧版索引添加到新索引系列的读别名：

   for TYPE in span service dependencies sampling; do
     echo -n "${TYPE}: "
     curl -k -sS -u "${ES_USER}:${ES_PASS}" -X POST \
       "${ES_ENDPOINT}/_aliases" -H 'Content-Type: application/json' \
       -d "{\"actions\":[{\"add\":{\"index\":\"${LEGACY_ES_INDEX_PREFIX}-jaeger-${TYPE}-2*\",\"alias\":\"${JAEGER_ES_INDEX_PREFIX}-jaeger-${TYPE}-read\"}}]}"
     echo
   done

   -2* 模式会匹配带日期的旧版索引，例如 -2026-08-27，而不会匹配新系列的编号 rollover 索引。在未启用依赖分析和自适应采样的情况下运行的旧版 Jaeger 不会有 dependencies 和 sampling 索引，因此这两次迭代会返回 index_not_found_exception。这是预期行为，不会影响另外两个索引。

   若只需附加部分历史数据，请将模式缩小到所需日期范围，例如 ${LEGACY_ES_INDEX_PREFIX}-jaeger-${TYPE}-2026-08-1*。每次查询都会扫描所有已附加的索引，因此只附加仍需要搜索的索引。

3. 确认两个索引系列都可通过读别名解析，并且写别名仍仅指向新的编号索引：

   curl -k -sS -u "${ES_USER}:${ES_PASS}" \
     "${ES_ENDPOINT}/_cat/aliases/${JAEGER_ES_INDEX_PREFIX}-jaeger-*?v&h=alias,index,is_write_index&s=alias"

   示例输出

   alias                                     index                                                  is_write_index
   acp-${CLUSTER_NAME}-jaeger-service-read   acp-${CLUSTER_NAME}-jaeger-service-000001              -
   acp-${CLUSTER_NAME}-jaeger-service-read   acp-tracing-${CLUSTER_NAME}-jaeger-service-YYYY-MM-DD  -
   acp-${CLUSTER_NAME}-jaeger-service-write  acp-${CLUSTER_NAME}-jaeger-service-000001              true
   acp-${CLUSTER_NAME}-jaeger-span-read      acp-${CLUSTER_NAME}-jaeger-span-000001                 -
   acp-${CLUSTER_NAME}-jaeger-span-read      acp-tracing-${CLUSTER_NAME}-jaeger-span-YYYY-MM-DD     -
   acp-${CLUSTER_NAME}-jaeger-span-write     acp-${CLUSTER_NAME}-jaeger-span-000001                 true

   只有 -000001 索引携带 is_write_index: true。旧版索引仅附加用于读取，因此新的 Jaeger 无法写入这些索引。

4. 在 <platform-url>/clusters/<cluster>/jaeger 打开新的 Jaeger UI，确认切换前上报过数据的服务已列出，并且可以打开其中一个服务的 trace。

   NOTE

   在 UI 中选择覆盖旧版数据的时间范围。Jaeger UI 始终会发送明确的时间范围，因此其时间范围选择器可以按预期工作。

#将 v2 OpenTelemetry Collector 切换到新的 Jaeger

在完成OpenTelemetry v1 → v2 迁移后，重新创建的 otel OpenTelemetryCollector 仍位于 cpaas-system 中，并继续向旧版 Jaeger 写入 trace，因为其 trace exporter 继承自 v1 备份。其 spec.config 中与 trace 相关的部分通常如下所示（其他字段与此步骤无关，因此省略）：

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] 

修补 Collector，以便 (1) 添加一个指向 jaeger-system 中新 Jaeger v2 Collector Service 的新 otlp_grpc/jaeger-v2 exporter，(2) 将旧版 otlp exporter 设置为 null，从而移除该 exporter，以及 (3) 将 trace pipeline 的 exporter 列表替换为 [debug, otlp_grpc/jaeger-v2]：

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp_grpc/jaeger-v2:
        endpoint: jaeger-collector.jaeger-system.svc.cluster.local:4317
        tls:
          insecure: true
      otlp: null # the inherited exporter is named otlp, so it is removed under that name
    service:
      pipelines:
        traces:
          exporters: [debug, otlp_grpc/jaeger-v2]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

至此，trace 摄取已恢复。新的 trace 会写入新的 Jaeger v2 后端，并可在新的 Jaeger UI 中搜索。

#验证迁移

1. 确认两个 OpenTelemetryCollector 资源均处于健康状态：

   kubectl get opentelemetrycollector -A

   示例输出：

   NAMESPACE       NAME     MODE         VERSION   READY   AGE   IMAGE                                                           MANAGEMENT
   cpaas-system    otel     deployment   0.156.0   1/1     5h    build-harbor.alauda.cn/asm/opentelemetry-collector:0.158.0-r0   managed
   jaeger-system   jaeger   deployment   0.156.0   1/1     33m   build-harbor.alauda.cn/asm/jaeger:2.20.0-2.1.0-r0               managed

   cpaas-system/otel（面向应用的 Collector，由 OpenTelemetry v1 → v2 迁移重新部署）和 jaeger-system/jaeger（新的 Jaeger v2 后端，在部署新的 Jaeger v2 实例中部署）都必须报告 READY 为 <ready>/<desired>，其中 <ready> 等于 <desired>（通常为 1/1），并且 MANAGEMENT 为 managed。如果 READY 列显示 0/1 或为空，请在继续之前检查相应命名空间中的 Collector Pod 日志。

2. 使用 telemetrygen 生成示例 trace，并确认它们显示在新的 Jaeger UI 中：

   kubectl apply -n cpaas-system -f - <<EOF
   apiVersion: v1
   kind: Pod
   metadata:
     name: jaeger-migration-check
   spec:
     restartPolicy: Never
     containers:
       - name: telemetrygen
         image: ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest
         args:
           - traces
           - --otlp-endpoint=otel-collector.cpaas-system.svc.cluster.local:4317
           - --otlp-insecure
           - --duration=120s
           - --service=jaeger-migration-check
           - --rate=2
   EOF
   
   kubectl wait -n cpaas-system --for=jsonpath='{.status.phase}'=Succeeded \
     pod/jaeger-migration-check --timeout=10m
   kubectl delete -n cpaas-system pod/jaeger-migration-check

   位于 <platform-url>/clusters/<cluster>/jaeger 的新 Jaeger UI 应列出 jaeger-migration-check 服务及其 trace。

3. 确认新的索引系列正在 Elasticsearch 中创建，并且旧版索引系列完整无缺：

   curl -k -sS -u "${ES_USER}:${ES_PASS}" "${ES_ENDPOINT}/_cat/indices?v" \
     | grep -E 'acp-tracing-|acp-' | sort

   你应看到匹配 acp-tracing-<cluster>-jaeger-* 的旧版索引（带日期、不再增长）以及匹配 acp-<cluster>-jaeger-*-000001 的新索引（rollover、持续增长）。

4. 抽查一个真实业务请求，确认其在新的 Jaeger UI 中生成 trace。选择一个或两个已完成 instrumentation 的应用，触发一个具有代表性的请求，然后在新的 Jaeger UI 中查找其 traceID。

5. 确认迁移前的 trace 仍可访问，并且新的 Jaeger 没有覆盖索引模板：

   curl -k -sS -u "${ES_USER}:${ES_PASS}" \
     "${ES_ENDPOINT}/_cat/aliases/${JAEGER_ES_INDEX_PREFIX}-jaeger-span-read?v&h=alias,index&s=index"
   curl -k -sS -u "${ES_USER}:${ES_PASS}" \
     "${ES_ENDPOINT}/_index_template/${JAEGER_ES_INDEX_PREFIX}-jaeger-span" \
     | grep -o "rollover_alias\|${JAEGER_ES_INDEX_PREFIX}-jaeger-span-read"

   读别名必须同时列出旧版日期索引和新的 -000001 索引，并且在切换前最后一次上报数据的服务仍必须显示在新的 Jaeger UI 中。

   第二条命令必须输出读别名和 rollover_alias。如果结果为空，表示 Jaeger 实例启动时重新创建了索引模板，因为 create_mappings 未设置为 false。已经附加的旧版索引不受影响，但后续 rollover 索引将不再添加到读别名，并且 ILM 将无法继续执行 rollover。在 Jaeger 实例上设置 create_mappings: false，然后重新运行安装指南中的 jaeger-es-rollover init Job。

#接管旧版索引的保留策略

到目前为止，旧版 jaeger-es-index-cleaner CronJob 一直在使旧版索引过期。该 CronJob 由旧版 Jaeger 资源拥有，并将在下一步中随该资源一起进行垃圾回收，因此必须先移交保留策略。否则旧版索引会无限期保留在 Elasticsearch 中——而且由于它们已附加到读别名，还会继续在每次查询中被扫描。

为这些索引指定专属的 Index Lifecycle Management 策略，其中只能包含一个 delete 阶段。

在切换完成后执行此步骤，确保旧版 Jaeger 已停止创建新的每日索引。

操作步骤

1. 创建策略。将 min_age 设置为旧版清理器应用的保留期限，即盘点旧版 Jaeger 部署中记录的 esIndexCleaner.numberOfDays 值，默认为 7：

   export LEGACY_RETENTION_DAYS="7"
   
   curl -k -sS -u "${ES_USER}:${ES_PASS}" -X PUT \
     "${ES_ENDPOINT}/_ilm/policy/jaeger-legacy-ilm-policy" \
     -H 'Content-Type: application/json' --data-binary @- << EOF
   {
     "policy": {
       "phases": {
         "delete": {
           "min_age": "${LEGACY_RETENTION_DAYS}d",
           "actions": { "delete": {} }
         }
       }
     }
   }
   EOF

2. 将其应用于整个旧版索引系列：

   curl -k -sS -u "${ES_USER}:${ES_PASS}" -X PUT \
     "${ES_ENDPOINT}/${LEGACY_ES_INDEX_PREFIX}-jaeger-*/_settings" \
     -H 'Content-Type: application/json' \
     -d '{"index.lifecycle.name":"jaeger-legacy-ilm-policy"}'

3. 确认每个旧版索引都受策略管理，并且没有任何索引报告错误。Elasticsearch 默认每 10 分钟轮询一次 ILM，因此阶段在推进前会暂时保持为 new：

   curl -k -sS -u "${ES_USER}:${ES_PASS}" \
     "${ES_ENDPOINT}/${LEGACY_ES_INDEX_PREFIX}-jaeger-*/_ilm/explain?pretty" \
     | grep -E '"index"|"managed"|"policy"|"phase"|"step"|"reason"'

   每个索引都必须报告 "managed" : true，其策略为 jaeger-legacy-ilm-policy，并且不得出现任何 "reason" 行。

当索引达到保留期限末尾时，Elasticsearch 会将其删除，并自动将其从读别名中移除——无需维护该别名。

#卸载旧版 Jaeger 实例

删除旧版 Jaeger 实例及其支持资源。Elasticsearch 索引不会受到影响，因此切换前的 trace 仍可在新的 Jaeger UI 中查询：

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

卸载 Alauda Build of Jaeger Operator：

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

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

#禁用旧版功能开关并停用旧版索引系列

1. 在 ACP Web 控制台中，打开 Feature Switch，并禁用 acp-tracing-ui。卸载旧版 Alauda Build of OpenTelemetry v1 Operator 后，平台定制的 Observability → Tracing 视图将不再可用。更新内部文档和操作手册，将其指向 Jaeger UI URL <platform-url>/clusters/<cluster>/jaeger。

2. 等待旧版索引过期。接管旧版索引的保留策略中应用的策略会在每个索引达到保留期限后将其删除，并从读别名中移除，因此此步骤无需执行任何操作，只需检查剩余内容：

   curl -k -sS -u "${ES_USER}:${ES_PASS}" \
     "${ES_ENDPOINT}/_cat/indices/${LEGACY_ES_INDEX_PREFIX}-jaeger-*?v&h=index,docs.count,store.size&s=index"

   如果要在保留期限结束前停用切换前的 trace，请直接删除索引，而不是等待其过期：

   # ?h=index returns just the index-name column (no table header),
   # which the for-loop iterates over.
   for idx in $(curl -k -sS -u "${ES_USER}:${ES_PASS}" \
                  "${ES_ENDPOINT}/_cat/indices/${LEGACY_ES_INDEX_PREFIX}-jaeger-*?h=index"); do
     curl -k -sS -u "${ES_USER}:${ES_PASS}" -X DELETE "${ES_ENDPOINT}/${idx}"
     echo
   done

   删除索引也会将其从读别名中移除，因此新的 Jaeger 将不再返回这些 trace。

3. 上一步的列表为空后，删除 ILM 不会自行清理的内容——旧版索引模板和仅删除策略：

   for TYPE in span service dependencies sampling; do
     curl -k -sS -u "${ES_USER}:${ES_PASS}" -X DELETE \
       "${ES_ENDPOINT}/_index_template/${LEGACY_ES_INDEX_PREFIX}-jaeger-${TYPE}"
     echo
   done
   
   curl -k -sS -u "${ES_USER}:${ES_PASS}" -X DELETE \
     "${ES_ENDPOINT}/_ilm/policy/jaeger-legacy-ilm-policy"