#Migrating from Alauda Container Platform Tracing

#Deploy the new Jaeger v2 instance

Follow Deploying the Alauda Build of Jaeger v2 in the Alauda Distributed Tracing installation guide. The new Jaeger v2 instance is deployed in a dedicated namespace (jaeger-system by default) so that it does not collide with the legacy jaeger-prod instance in cpaas-system.

When you reach the variable-setup step, keep the default index prefix so that the new Jaeger writes to indices that are clearly separated from the legacy ones:

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"

After completing the installation steps, verify that:

• The Jaeger Pod in jaeger-system is Ready.
• The Jaeger UI is reachable at <platform-url>/clusters/<cluster>/jaeger. It is empty at this point, since no exporter is yet writing to it and the legacy indices have not been attached yet.
• The Service jaeger-collector.jaeger-system.svc.cluster.local accepts OTLP gRPC on port 4317 — this is the endpoint that the v2 OpenTelemetry Collector will export to in Switch the v2 OpenTelemetry Collector to the new Jaeger.

#Attach the legacy indices to the new read aliases

The jaeger-es-rollover init Job run in the previous step created the <prefix>-jaeger-<type>-read and <prefix>-jaeger-<type>-write aliases for the new index family. Jaeger v2 resolves every read through the read alias, so adding the legacy date-stamped indices to that alias is all it takes to make pre-cutover traces queryable in the new Jaeger UI. Nothing is copied, renamed, or reindexed, and the legacy Jaeger keeps serving the same indices.

Perform this step before the cutover, so that the new Jaeger UI is already complete when it starts receiving traces.

Procedure

1. Set the legacy index prefix. It is the es.index-prefix value recorded in Inventory the legacy Jaeger deployment:

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

2. Add the legacy indices to the read aliases of the new index family:

   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

   The -2* pattern matches the date-stamped legacy indices, such as -2026-08-27, and never the numbered rollover indices of the new family. A legacy Jaeger that ran without dependency analysis and without adaptive sampling has no dependencies and no sampling index, so those two iterations return index_not_found_exception. That is expected and does not affect the other two.

   To attach only part of the history, narrow the pattern to the date range you need, for example ${LEGACY_ES_INDEX_PREFIX}-jaeger-${TYPE}-2026-08-1*. Every attached index is scanned on every query, so attach only what you still want to be searchable.

3. Confirm that both index families are resolved by the read aliases, and that the write aliases still point only at the new numbered indices:

   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"

   Example output

   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

   Only the -000001 indices carry is_write_index: true. The legacy indices are attached for reading only, so the new Jaeger cannot write into them.

4. Open the new Jaeger UI at <platform-url>/clusters/<cluster>/jaeger and confirm that services which reported before the cutover are listed and that one of their traces can be opened.

   NOTE

   Pick a time range in the UI that covers the legacy data. The Jaeger UI always sends an explicit range, so its time-range picker behaves as expected.

#Switch the v2 OpenTelemetry Collector to the new Jaeger

After the OpenTelemetry v1 → v2 migration, the recreated otel OpenTelemetryCollector in cpaas-system still writes traces to the legacy Jaeger because its trace exporter was inherited from the v1 backup. The trace-related portion of its spec.config typically looks like this (other fields are unrelated to this step and are omitted):

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] 

Patch the Collector to (1) add a new otlp_grpc/jaeger-v2 exporter pointing at the new Jaeger v2 collector Service in jaeger-system, (2) remove the legacy otlp exporter by setting it to null, and (3) replace the trace pipeline's exporter list with [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 ingestion is restored at this point. New traces are written to the new Jaeger v2 backend and become searchable in the new Jaeger UI.

#Verify the migration

1. Confirm that both OpenTelemetryCollector resources are healthy:

   kubectl get opentelemetrycollector -A

   Example output:

   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

   Both cpaas-system/otel (the application-facing Collector, redeployed by the OpenTelemetry v1 → v2 migration) and jaeger-system/jaeger (the new Jaeger v2 backend, deployed in Deploy the new Jaeger v2 instance) must report READY as <ready>/<desired> with <ready> equal to <desired> (typically 1/1) and MANAGEMENT as managed. If the READY column shows 0/1 or is empty, inspect the Collector pod logs in the corresponding namespace before continuing.

2. Generate sample traces with telemetrygen and verify they appear in the new 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

   The new Jaeger UI at <platform-url>/clusters/<cluster>/jaeger should list the jaeger-migration-check service and its traces.

3. Confirm that the new index family is being created in Elasticsearch and that the legacy index family is intact:

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

   You should see legacy indices matching acp-tracing-<cluster>-jaeger-* (date-stamped, no longer growing) and new indices matching acp-<cluster>-jaeger-*-000001 (rollover, growing).

4. Spot-check that a real business request produces a trace in the new Jaeger UI. Pick one or two already-instrumented applications, trigger a representative request, and look up its traceID in the new Jaeger UI.

5. Confirm that pre-cutover traces are still reachable and that the new Jaeger did not overwrite the index templates:

   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"

   The read alias must list both the legacy date-stamped indices and the new -000001 index, and a service that last reported before the cutover must still appear in the new Jaeger UI.

   The second command must print the read alias and rollover_alias. An empty result means the Jaeger instance recreated its index templates on startup because create_mappings is not set to false. The legacy indices already attached are unaffected, but future rollover indices would no longer be added to the read alias and ILM could no longer roll over. Set create_mappings: false on the Jaeger instance and re-run the jaeger-es-rollover init Job from the installation guide.

#Take over retention of the legacy indices

Up to this point the legacy jaeger-es-index-cleaner CronJob has been expiring the legacy indices. That CronJob is owned by the legacy Jaeger resource and is garbage-collected together with it in the next step, so retention has to be handed over first. Otherwise the legacy indices stay in Elasticsearch indefinitely — and, because they are attached to the read aliases, they also keep being scanned by every query.

Give them an Index Lifecycle Management policy of their own, containing only a delete phase.

Run this step after the cutover, once the legacy Jaeger has stopped creating new daily indices.

Procedure

1. Create the policy. Set min_age to the retention the legacy cleaner applied — the esIndexCleaner.numberOfDays value recorded in Inventory the legacy Jaeger deployment, 7 by default:

   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. Apply it to the whole legacy index family:

   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. Confirm that every legacy index is managed and that none of them reports an error. Elasticsearch polls ILM every 10 minutes by default, so the phase stays new for a while before it advances:

   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"'

   Every index must report "managed" : true with policy jaeger-legacy-ilm-policy, and no "reason" line must appear.

When an index reaches the end of its retention, Elasticsearch deletes it and Elasticsearch removes it from the read alias automatically — the alias needs no maintenance.

#Uninstall the legacy Jaeger instance

Delete the legacy Jaeger instance and its supporting resources. The Elasticsearch indices are not touched, so pre-cutover traces stay queryable in the new 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

Uninstall the 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

#Disable the legacy feature switch and retire the legacy index family

1. In the ACP web console, open Feature Switch and disable acp-tracing-ui. The platform-customized Observability → Tracing view is no longer functional after the legacy Alauda Build of OpenTelemetry v1 Operator is uninstalled. Update internal documentation and runbooks to point to the Jaeger UI URL <platform-url>/clusters/<cluster>/jaeger.

2. Let the legacy indices expire. The policy applied in Take over retention of the legacy indices deletes each index once it reaches its retention and removes it from the read alias, so this step needs no action — only a check of what is left:

   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"

   To retire the pre-cutover traces earlier than their retention, delete the indices directly instead of waiting:

   # ?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

   Deleting an index removes it from the read alias as well, so the new Jaeger simply stops returning those traces.

3. Once the listing in the previous step comes back empty, remove what ILM does not clean up by itself — the legacy index templates and the delete-only policy:

   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"