#从 Alauda Container Platform Tracing 迁移

#部署新的 Jaeger v2 实例

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

到达变量设置步骤时，保留默认索引前缀，以便新的 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"

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

• 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 通过读取别名解析所有读取操作，因此只需将旧版按日期标记的索引添加到该别名，就能使切换前的 trace 可在新的 Jaeger UI 中查询。不会复制、重命名或重新索引任何内容，旧版 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，不会匹配新索引系列的编号滚动索引。未启用依赖分析和自适应采样运行的旧版 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 中仍会将 trace 写入旧版 Jaeger，因为其 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 的新索引（滚动增长）。

4. 抽查真实业务请求是否会在新的 Jaeger UI 中生成 trace。选择一个或两个已完成插桩的应用，触发具有代表性的请求，然后在新的 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。已附加的旧版索引不受影响，但未来的滚动索引将不再添加到读取别名中，ILM 也将无法执行滚动。请在 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 控制台中打开功能开关，并禁用 acp-tracing-ui。卸载旧版 Alauda Build of OpenTelemetry v1 Operator 后，平台定制的可观测性 → 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"