#Migrating to Jaeger v2

#Uninstall the legacy OpenTelemetry Collector and Operator

The v1 and v2 Alauda Build of OpenTelemetry Operators share the same CRDs, so the v1 Operator must be removed before the v2 Operator is installed. The legacy Alauda Build of Jaeger Operator owns a separate CRD (jaegertracing.io/v1.Jaeger) and is left running so that the legacy Jaeger continues to serve historical traces during the observation window.

1. Delete the legacy OpenTelemetryCollector instance in the istio-system namespace:

   kubectl -n istio-system delete opentelemetrycollector otel

2. Uninstall the Alauda Build of OpenTelemetry Operator from the Administrator view in the web console.

   • From Marketplace → OperatorHub → use the search box to search for Alauda build of OpenTelemetry.
   • Click on the Alauda build of OpenTelemetry title to enter its details.
   • On the Alauda build of OpenTelemetry details page, click the Uninstall button in the upper right corner.
   • In the Uninstall "opentelemetry-operator"? window, click Uninstall.

For background on why the v1 Operator must be removed before the v2 Operator is installed, and on the resulting outage characteristics, see Migrate Alauda Build of OpenTelemetry to v2 in the Alauda Distributed Tracing migration guide.

#Deploy the new distributed tracing stack

Complete the Prerequisites section of Configuring distributed tracing platform with Service Mesh to bring up the v2 stack:

• Install the Alauda Build of OpenTelemetry v2 Operator.
• Deploy a new Jaeger v2 instance (defaulted to the jaeger-system namespace).
• Deploy the v2 OpenTelemetry Collector (defaulted to the jaeger-system namespace).

The v2 stack is namespace-isolated from the legacy jaeger-prod Jaeger in istio-system, so the two can coexist for the duration of the observation window.

#Attach the legacy Elasticsearch indices to the new read aliases

Traces produced before the cutover live in the index family that the legacy Jaeger instance wrote. Attaching those indices to the read aliases of the new index family makes them queryable in the new Jaeger UI, so the legacy Jaeger no longer has to be kept alive to answer historical queries. Nothing is copied, renamed, or reindexed, and the legacy indices stay read-only.

Perform this step before repointing the mesh, so that the new Jaeger UI is already complete when it starts receiving spans.

Follow Attach the legacy indices to the new read aliases in the Alauda Distributed Tracing migration guide, with these two values:

• LEGACY_ES_INDEX_PREFIX — the --jaeger-es-index-prefix value used when the legacy Jaeger was installed (for example istio-tracing-<cluster>). Read it back from the legacy instance rather than relying on memory:

  kubectl -n istio-system get jaeger jaeger-prod \
    -o jsonpath='{.spec.storage.options.es\.index-prefix}{"\n"}'

• JAEGER_ES_INDEX_PREFIX — the prefix chosen for the new Jaeger v2 instance in Configuring distributed tracing platform with Service Mesh.

Both Jaeger instances must use the same Elasticsearch cluster, which is the case when the new instance was installed against the endpoint of the legacy one.

#Repoint the Istio extension provider at the new OpenTelemetry Collector

Patch the Istio resource so that the otel extension provider targets the new v2 OpenTelemetry Collector in the jaeger-system namespace instead of the deleted legacy Collector in istio-system:

kubectl patch istio default --type=merge -p '
spec:
  values:
    meshConfig:
      enableTracing: true
      extensionProviders:
      - name: otel
        opentelemetry:
          port: 4317
          service: otel-collector.jaeger-system.svc.cluster.local
'

Once the patch is applied and the Istio control plane reconciles, sidecars send spans to the new OpenTelemetry Collector and new traces appear in the Jaeger v2 UI. The Telemetry resource does not need to be changed because it already references the provider by name (otel).

#Uninstall the legacy Jaeger instance and Operator

The legacy Jaeger no longer has to outlive the retention window: with the indices attached to the read aliases, pre-cutover traces are served by the new Jaeger UI. Keep the legacy instance only for as long as you want a rollback target, then remove it. See Trace data continuity strategy for the data-continuity model.

1. Delete the legacy Jaeger instance and its supporting resources in the istio-system namespace. The resource names below match the defaults produced by install-jaeger.sh with --target-namespace='istio-system'; adjust them if you used a different --jaeger-instance-name during the original installation.

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

2. Uninstall the Alauda build of Jaeger Operator from the Administrator view in the web console.

   • From Marketplace → OperatorHub → use the search box to search for Alauda build of Jaeger.
   • Click on the Alauda build of Jaeger title to enter its details.
   • On the Alauda build of Jaeger details page, click the Uninstall button in the upper right corner.
   • In the Uninstall "jaeger-operator"? window, click Uninstall.

Once the legacy indices have expired under the policy applied above, remove the leftover index templates and the delete-only policy as described in Disable the legacy feature switch and retire the legacy index family in the Alauda Distributed Tracing migration guide. The acp-tracing-ui feature switch mentioned there belongs to the platform tracing stack and does not apply to a Service Mesh deployment.