#Миграция с Alauda Container Platform Tracing

В этом документе описывается, как выполнить миграцию существующего развертывания трассировки на основе устаревшего стека Alauda Container Platform (ACP) Tracing — Alauda Build of Jaeger (Jaeger 1.60.0) в сочетании с Alauda Build of OpenTelemetry — на Alauda Distributed Tracing на базе Jaeger v2 (2.16.0) в сочетании с Alauda Build of OpenTelemetry v2.

Миграция выполняется в два этапа:

1. Миграция стека OpenTelemetry. Замените устаревшие Operator и Collector Alauda Build of OpenTelemetry на Alauda Build of OpenTelemetry v2. Поды приложений пересобираются так, чтобы внедрялся агент Java v2. После этого этапа телеметрия собирается Collector v2, но по-прежнему записывается в устаревший backend Jaeger. Этот этап выполняется по инструкции Миграция с Alauda Build of OpenTelemetry на Alauda Build of OpenTelemetry v2.

2. Миграция backend Jaeger. Разверните новый экземпляр Jaeger v2 рядом с устаревшим Jaeger, переключите trace exporter Collector v2 на новый backend и удалите устаревший Jaeger после истечения периода хранения устаревших данных.

После переключения новый трафик трассировки поступает в новый backend Jaeger v2, а устаревший Jaeger продолжает обслуживать ранее сохраненные трассы. После истечения периода хранения устаревших данных (по умолчанию 7 дней) устаревший стек удаляется.

#Обзор

#Что меняется между ACP Tracing и Alauda Distributed Tracing

Ознакомьтесь с изменениями в ресурсах OpenTelemetry Operator, Collector и Instrumentation (включая теперь обязательное поле spec.java.image, несовместимость с Service Mesh v1 и миграцию схемы конфигурации Collector) в разделе Что изменилось между v1 и v2 руководства по миграции OpenTelemetry v2.

#Окна недоступности при миграции

Сбор трассировки прерывается в двух местах:

1. Во время миграции OpenTelemetry v1 → v2, в промежутке между удалением устаревшего OpenTelemetryCollector и моментом, когда OpenTelemetryCollector v2 становится готов. См. Окно недоступности при миграции в руководстве по миграции OpenTelemetry v2.

2. Во время переключения Jaeger, когда Collector v2 получает патч для перенаправления trace exporter с устаревшего Jaeger на новый backend Jaeger v2. Развертывание Collector выполняется заново, поэтому во время rollout возможен короткий разрыв в сборе данных.

Поды приложений продолжают работать в штатном режиме на протяжении обоих окон, но телеметрия, сгенерированная в эти промежутки, может временно буферизоваться и быть потеряна, если ее не удастся экспортировать вовремя. Планируйте каждый этап на период низкой нагрузки и заранее уведомляйте потребителей телеметрии (разработчиков, SRE, пользователей Kiali).

Путь запроса к устаревшему Jaeger остается доступным на протяжении всей миграции, поэтому ранее сохраненные трассы можно по-прежнему искать в старом Jaeger UI, пока поднимается новый pipeline.

#Схема миграции в общих чертах

[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

#Стратегия непрерывности данных трассировки

Если следовать рекомендациям Воссоздание ресурсов OpenTelemetryCollector во время миграции OpenTelemetry v2, Collector v2 развертывается в том же namespace и с тем же именем Service (otel-collector в cpaas-system), что и устаревший Collector. Приложения, которые экспортируют OTLP в otel-collector.cpaas-system, продолжают работать без каких-либо изменений конфигурации.

После переключения Jaeger трассировочные данные строго разделяются по времени:

• Трассы, поступившие до переключения, остаются только в устаревшем Jaeger. Их можно запрашивать через устаревший Jaeger UI по адресу <platform-url>/clusters/<cluster>/acp/jaeger до тех пор, пока устаревший jaeger-es-index-cleaner их хранит — по умолчанию 7 дней с даты создания индекса.
• Трассы, поступившие после переключения, записываются только в новый backend Jaeger v2. Их можно запрашивать через новый Jaeger UI по адресу <platform-url>/clusters/<cluster>/jaeger.

Экземпляр устаревшего Jaeger и его Operator намеренно остаются запущенными в течение периода наблюдения, чтобы пользователи могли продолжать искать недавние исторические трассы через старый UI. После полного истечения срока хранения устаревших данных (≥ 7 дней) устаревший стек удаляется в разделе Очистка.

#Предварительные требования

• Активная сессия ACP CLI (kubectl) у администратора кластера с ролью cluster-admin.
• В данный момент установлен устаревший стек ACP Tracing (Alauda Build of Jaeger Operator с экземпляром Jaeger и Alauda Build of OpenTelemetry с OpenTelemetryCollector и одним или несколькими ресурсами Instrumentation).
• Elasticsearch 8.x доступен из кластера, и у вас есть пользователь Elasticsearch с правами на создание политик ILM, шаблонов индексов и alias индексов.
• На рабочей станции, с которой выполняются команды миграции, установлены утилиты командной строки jq и envsubst.
• Потребители телеметрии (разработчики, пользователи Kiali, SRE dashboards) и владельцы приложений уведомлены о запланированных окнах недоступности.

#Подготовительные задачи

#Миграция Alauda Build of OpenTelemetry на v2

Перед миграцией backend Jaeger завершите миграцию с Alauda Build of OpenTelemetry на Alauda Build of OpenTelemetry v2, следуя инструкции Миграция с Alauda Build of OpenTelemetry на Alauda Build of OpenTelemetry v2. В этом руководстве рассматриваются:

• Создание резервной копии и удаление устаревших Operator Alauda Build of OpenTelemetry и его ресурсов OpenTelemetryCollector и Instrumentation.
• Установка Operator v2.
• Подготовка образа для автоматической Java-инструментации и воссоздание ресурсов OpenTelemetryCollector и Instrumentation, включая задание теперь обязательного поля spec.java.image.
• Пересборка подов приложений так, чтобы внедрялся новый агент Java.

В конце этого этапа:

• Установлен Operator Alauda Build of OpenTelemetry v2, а устаревший Operator удален.
• OpenTelemetryCollector v2 в cpaas-system запущен, но его trace exporter по-прежнему указывает на устаревший Jaeger (что является естественным результатом воссоздания Collector на основе резервной копии v1).
• Во всех ресурсах Instrumentation задано поле spec.java.image, а поды приложений пересобраны с агентом Java v2.

Сбор трассировки продолжает поступать в устаревший Jaeger до выполнения шага Переключите Collector OpenTelemetry v2 на новый Jaeger в этом руководстве.

#Снимите инвентаризацию развертывания устаревшего Jaeger

Зафиксируйте текущее состояние устаревшего Jaeger, чтобы понимать масштаб миграции и иметь возможность подготовить резервные копии для отката.

1. Перечислите устаревшие экземпляры Alauda Build of Jaeger Operator и Jaeger:

   kubectl get csv -A | grep -i jaeger
   kubectl get jaeger -A

2. Запишите endpoint Elasticsearch, учетные данные и префикс индекса, указанные в устаревшем ресурсе Jaeger. Они также будут повторно использованы новым экземпляром 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, равный одному полному периоду хранения трасс. Если вы включаете (Необязательно) Включение двойного экспорта в устаревший 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. Cleaner удаляет каждый индекс примерно через ~7 дней после даты создания; когда все индексы до переключения будут очищены, в устаревшем Jaeger не останется полезных данных, и его можно будет удалить.
• Новый Jaeger накапливает трассы, созданные после переключения. Проверяйте dashboards, alerts и интеграции Kiali с новым Jaeger UI и именами метрик нового агента Java v2.
• Четко объясните пользователям разделение: сообщите, что новый Jaeger UI показывает трассы начиная с момента переключения, а более старые трассы остаются в устаревшем 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

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

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

#(Необязательно) Включение двойного экспорта в устаревший Jaeger

Настройка Collector OpenTelemetry v2 на запись каждого span одновременно в новый Jaeger и в устаревший Jaeger — это альтернативный, включаемый вручную вариант вместо стандартного конвейера с одиночным экспортом. Рассмотрите его, если применимо одно из следующих условий:

• Параллельная проверка. Вы хотите сравнить новый Jaeger с устаревшим Jaeger на боевом трафике в период наблюдения, прежде чем полностью полагаться на новый backend.
• Более быстрый откат на месте. Если в период наблюдения у нового Jaeger обнаружатся проблемы, вы можете одним патчем убрать otlp/jaeger-v2 из pipeline трассировки, и устаревший Jaeger продолжит получать трассы без перерыва.
• Постепенное переключение UI. Разные команды планируют переход с устаревшего UI на новый UI по собственным графикам, и вам нужно, чтобы оба UI отображали данные после переключения в переходный период.

Компромиссы:

• Нагрузка на запись в Elasticsearch и использование хранилища примерно удваиваются в период наблюдения, поскольку каждый span индексируется в обоих семействах индексов.
• Перед удалением устаревшего Jaeger pipeline трассировки нужно будет вернуть дополнительным патчем в разделе Остановите двойной экспорт.
• Необходимо отслеживать сбои в двух export pipeline (otelcol_exporter_send_failed_spans_total и для otlp/jaeger-v2, и для otlp/jaeger-v1).

Двойной экспорт не выполняет backfill трасс до переключения в новый Jaeger; трассы до переключения по-прежнему доступны только через устаревший Jaeger UI.

#Включите двойной экспорт

После того как Переключите Collector OpenTelemetry v2 на новый Jaeger завершился, Collector otel имеет otlp/jaeger-v2 как единственный trace exporter, записывающий в backend Jaeger (pipeline трассировки — [debug, otlp/jaeger-v2]). Примените патч к Collector, чтобы снова добавить устаревший Jaeger как второй exporter otlp/jaeger-v1, повторяя endpoint устаревшего Jaeger, балансировку нагрузки headless Service и TLS-настройки исходного exporter otlp, удаленного на шаге переключения:

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 записывается в оба backend Jaeger.

#Остановите двойной экспорт

После периода наблюдения, перед Удалите устаревший экземпляр Jaeger, удалите устаревший exporter из pipeline трассировки:

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

После этого патча Collector v2 записывает трассы только в новый Jaeger. Теперь можно перейти к Удалите устаревший экземпляр Jaeger.

#Откат

Для отката этапа OpenTelemetry v1 → v2 см. раздел Откат в руководстве по миграции OpenTelemetry v2. Для этапа миграции Jaeger, описанного в этом документе, выберите путь отката, соответствующий текущей фазе:

#FAQ

Нужно ли приложениям обновлять свои OTLP endpoint?

Нет. Если следовать рекомендации Воссоздание ресурсов OpenTelemetryCollector из руководства по миграции OpenTelemetry v2, Collector OpenTelemetry v2 разворачивается в том же namespace (cpaas-system), с тем же именем Service (otel-collector) и теми же портами (4317/4318). Нагрузки, которые отправляли данные в otel-collector.cpaas-system:4317, продолжают работать без каких-либо изменений.

Покажет ли новый Jaeger UI трассы, созданные до переключения?

Нет. Трассы до переключения хранятся только в устаревшем Jaeger и остаются доступными для запросов через устаревший Jaeger UI на протяжении окна хранения устаревших данных (по умолчанию 7 дней). Новый Jaeger UI начинает показывать трассы только с момента переключения. Сообщите об этом пользователям заранее и направляйте их к старому UI для старых трасс в течение периода наблюдения.

Когда следует включать двойной экспорт?

Для большинства миграций достаточно стандартного пути с одиночным экспортом. Включайте двойной экспорт ((Необязательно) Включение двойного экспорта в устаревший Jaeger) только если выполняется одно из следующих условий:

• Вам нужно проверить новый Jaeger на боевом трафике до начала его использования.
• Разные команды будут переходить с устаревшего UI на новый UI по независимым графикам, и вы хотите, чтобы оба UI показывали данные после переключения в переходный период.
• Вам нужен максимально быстрый путь отката на месте в течение периода наблюдения.

Имейте в виду, что двойной экспорт примерно удваивает нагрузку на запись в Elasticsearch и объем хранилища в период наблюдения, а также добавляет дополнительный шаг патча перед удалением устаревшего Jaeger.

Могут ли устаревший и новый Jaeger использовать один и тот же индекс Elasticsearch?

Нет. Устаревший Jaeger использует ежедневные индексы с датой в имени (acp-tracing-<cluster>-jaeger-span-YYYY-MM-DD), тогда как Jaeger v2 использует rollover alias (acp-<cluster>-jaeger-span-write / -read, построенные на *-000001, *-000002, …). Схемы и жизненный цикл управляются по-разному, поэтому эти два семейства индексов должны оставаться раздельными. Оставьте префиксы по умолчанию, показанные в разделе Разверните новый экземпляр Jaeger v2, чтобы избежать конфликтов.

Сколько дополнительного хранилища Elasticsearch требуется в период наблюдения?

При стандартном пути с одиночным экспортом новое семейство индексов растет с нуля, а устаревшее семейство постепенно уменьшается по мере истечения срока хранения; планируйте дополнительный объем хранилища для трасс, равный одному полному периоду хранения, как буфер steady state. При включенном двойном экспорте планируйте примерно удвоенный steady-state размер устаревшего семейства индексов на весь период наблюдения, плюс запас на повторы и всплески поступления данных.

Можно ли включить Service Performance Monitoring (SPM) в рамках миграции?

SPM — опция, которую можно включить в любое время после Проверьте миграцию. Следуйте инструкции (Необязательно) Включение Service Performance Monitoring (SPM), чтобы добавить connector spanmetrics в Collector OpenTelemetry v2 и настроить backend метрик в новом Jaeger.