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

#Удаление ресурсов Instrumentation v1

1. Выведите список существующих ресурсов Instrumentation:

   kubectl get instrumentation -A

2. Удалите каждый ресурс Instrumentation. Замените <namespace> и <name> значениями из предыдущего шага:

   kubectl -n <namespace> delete instrumentation <name>
   TIP

   Удаление Instrumentation не влияет на pod’ы приложений, которые уже были изменены webhook’ом — ранее внедрённый init container, переменные окружения и JAVA_TOOL_OPTIONS остаются в работающих pod’ах. Удаление лишь предотвращает внедрение этих настроек v1 Operator в новые создаваемые pod’ы.

#Удаление ресурсов OpenTelemetryCollector v1

1. Выведите список существующих ресурсов OpenTelemetryCollector:

   kubectl get opentelemetrycollector -A

2. Удалите каждый ресурс OpenTelemetryCollector:

   kubectl -n <namespace> delete opentelemetrycollector <name>

#Удаление v1 Operator

1. Удалите Subscription:

   kubectl delete subscription opentelemetry-operator -n opentelemetry-operator

2. Удалите RBAC и monitoring resources, которые v1 deployment создал в cpaas-system (пропустите этот шаг, если ваше v1 deployment их не создавало). Эти ресурсы сохранены в Создание резервной копии ресурсов v1 для rollback.

   kubectl -n cpaas-system delete servicemonitor otel-collector-monitoring otel-collector
   kubectl -n cpaas-system delete sa otel-collector
   kubectl delete clusterrolebinding otel-collector:cpaas-system:cluster-admin

3. Дождитесь, пока в кластере не останется ни одного CSV v1 Operator. Эта проверка важна — если какой-либо CSV v1 всё ещё присутствует, OLM отклонит установку v2 Operator в Шаге 4 из-за конфликта владельца CRD.

   kubectl get csv -A | grep '^opentelemetry-operator '

   Ожидаемый вывод — пустой.

#Установка v2 Operator

Следуйте инструкции Установка Operator Alauda Build of OpenTelemetry v2. Сокращённый поток CLI выглядит так:

1. Проверьте доступные версии v2 Operator:

   kubectl get packagemanifest opentelemetry-operator2 -o json | jq -r '
     .status.channels[]
     | .name as $channel
     | .entries[]
     | [$channel, .name, .version] | @tsv
   ' | column -t

2. Создайте namespace Operator:

   kubectl get namespace opentelemetry-operator2 || \
     kubectl create namespace opentelemetry-operator2

3. Создайте Subscription. Замените startingCSV на версию, возвращённую на шаге 1.

   kubectl apply -f - <<EOF
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     annotations:
       cpaas.io/target-namespaces: ""
     labels:
       catalog: platform
     name: opentelemetry-operator2
     namespace: opentelemetry-operator2
   spec:
     channel: stable
     installPlanApproval: Manual
     name: opentelemetry-operator2
     source: platform
     sourceNamespace: cpaas-system
     # startingCSV example: opentelemetry-operator2.v0.147.0-r0
     startingCSV: {step-1-operator-csv-version}
   EOF

4. Одобрите InstallPlan:

   kubectl -n opentelemetry-operator2 wait \
     --for=condition=InstallPlanPending subscription opentelemetry-operator2 --timeout=2m
   
   PLAN="$(kubectl -n opentelemetry-operator2 get subscription opentelemetry-operator2 \
     -o jsonpath='{.status.installPlanRef.name}')"
   kubectl -n opentelemetry-operator2 patch installplan "$PLAN" --type=json \
     -p='[{"op": "replace", "path": "/spec/approved", "value": true}]'

5. Дождитесь, пока CSV v2 не перейдёт в состояние Succeeded:

   kubectl wait --for=jsonpath='{.status.phase}'=Succeeded csv \
     --all -n opentelemetry-operator2 --timeout=3m

#Воссоздание ресурсов OpenTelemetryCollector

#Что меняется в этой миграции

При восстановлении манифестов OpenTelemetryCollector из резервной копии v1 необходимо внести следующие изменения, прежде чем применять их в v2.

• Namespace Collector. Namespace Collector должен отличаться от namespace Operator (opentelemetry-operator2). Выберите namespace в зависимости от сценария развертывания:

  • Standalone Collector: отдельный namespace, например opentelemetry-collector.
  • Интеграция Alauda Container Platform Tracing: продолжайте использовать тот же namespace Collector (обычно cpaas-system), чтобы downstream services, ссылающиеся на service Collector, не требовали изменений.
  • Интеграция Alauda Service Mesh v2: оставьте Collector в istio-system, чтобы существующий Istio meshConfig.extensionProviders[].opentelemetry.service оставался действительным.

• Совместимость компонентов. Каждый компонент, используемый в spec.config, должен поддерживаться в v2. Для рекомендуемой конфигурации Collector при интеграции с Alauda Distributed Tracing см. Развёртывание OpenTelemetry Collector в документации Alauda Distributed Tracing. Для других сценариев следуйте Развёртывание OpenTelemetry Collector и адаптируйте пример под вашу среду.

• Feature gates. v1 Collectors часто передают Collector feature gates через spec.args.feature-gates. Многие из этих gates либо были стабилизированы (и, следовательно, больше не могут переключаться), либо полностью удалены в более новых версиях Collector, поэтому повторное использование списка v1 может помешать запуску pod Collector в v2. Удалите spec.args.feature-gates из резервной копии и добавьте только те gates, которые явно документированы для используемой версии v2 Collector.

• Внутренний Prometheus endpoint метрик. Поле service.telemetry.metrics.address больше не является поддерживаемым способом экспонирования внутреннего Prometheus endpoint метрик. Настройте его через service.telemetry.metrics.readers[].pull.exporter.prometheus, как описано в OpenTelemetry Collector internal telemetry documentation. Типичный backup v1 выглядит так:

  service:
    telemetry:
      logs:
        level: info
      metrics:
        address: 0.0.0.0:8888
        level: detailed

• Подробность внутренних метрик. level: detailed включает histogram buckets и labels по каждому экземпляру для внутренних метрик самого Collector, что существенно увеличивает cardinality в Prometheus и стоимость хранения — особенно в развертываниях Gateway-mode с большим количеством экземпляров receiver/exporter. Для production рекомендуется значение по умолчанию level: normal: оно по-прежнему показывает использование ресурсов процесса и счётчики sent/received/refused/dropped по каждому компоненту, чего достаточно для большинства требований SRE по alerting и capacity. Возвращайтесь к detailed только временно при исследовании распределений задержек exporter или размера batch.

• Метаданные, управляемые сервером. Поля, записываемые API server (metadata.creationTimestamp, metadata.resourceVersion, metadata.uid, metadata.generation, metadata.managedFields, metadata.finalizers, annotation kubectl.kubernetes.io/last-applied-configuration и status), нельзя повторно использовать при create; их необходимо удалить из резервной копии.

• RBAC и scraping Prometheus, управляемые Operator. v2 Operator автоматически создаёт ресурсы ServiceAccount и ClusterRoleBinding, необходимые Collector. Удалите поле v1 spec.serviceAccount из резервной копии, чтобы Operator мог создать новый ServiceAccount с корректными правами; обычно не требуется вручную воссоздавать ресурсы RBAC v1. Чтобы Operator также создавал ServiceMonitor для внутреннего Prometheus endpoint, установите spec.observability.metrics.enableMetrics: true и добавьте discovery label (например, prometheus: kube-prometheus) в metadata.labels, чтобы ваш Prometheus Operator подхватил ресурс. Если компонент Collector требует дополнительных cluster-level RBAC (например, processor k8sattributes или receiver k8sobjects), следуйте инструкции Автоматическое создание необходимых RBAC ресурсов.

#Процедура миграции

1. Воссоздайте ресурс OpenTelemetryCollector из резервной копии. В следующем примере ./otel-v1-backup/collectors.yaml копируется в новый рабочий каталог, удаляются server-managed metadata, поля v1 spec.serviceAccount и spec.args.feature-gates, значение level: detailed понижается до стандартного level: normal, устаревшее поле address заменяется новой конфигурацией readers, включается scraping метрик под управлением Operator через установку spec.observability.metrics.enableMetrics: true и добавление label prometheus: kube-prometheus, чтобы стек kube-prometheus подхватил автоматически созданный ServiceMonitor, после чего результат применяется.

   jq не читает YAML напрямую, поэтому в примере kubectl patch --local -p='[]' -o json используется только как локальный декодер YAML-to-JSON перед передачей ресурсов в jq.

   RESTORE_DIR=./otel-v2-restore
   
   mkdir -p "$RESTORE_DIR"
   cp ./otel-v1-backup/collectors.yaml "$RESTORE_DIR/collectors.yaml"
   
   kubectl patch --local -f "$RESTORE_DIR/collectors.yaml" --type=json -p='[]' -o json \
     | jq -s '
         {
           apiVersion: "v1",
           kind: "List",
           items: map(
             del(
               .metadata.annotations."kubectl.kubernetes.io/last-applied-configuration",
               .metadata.creationTimestamp,
               .metadata.finalizers,
               .metadata.generation,
               .metadata.managedFields,
               .metadata.resourceVersion,
               .metadata.uid,
               .status,
               .spec.serviceAccount,
               .spec.args."feature-gates"
             )
             | .spec.config.service.telemetry.metrics = (
                 (.spec.config.service.telemetry.metrics // {})
                 | del(.address)
                 | if .level == "detailed" then .level = "normal" else . end
                 | .readers = [
                     {
                       pull: {
                         exporter: {
                           prometheus: {
                             host: "0.0.0.0",
                             port: 8888,
                             without_scope_info: true,
                             without_type_suffix: true,
                             without_units: true
                           }
                         }
                       }
                     }
                   ]
               )
             | .spec.observability.metrics.enableMetrics = true
             | .metadata.labels.prometheus = "kube-prometheus"
           )
         }
       ' > "$RESTORE_DIR/collectors.json"
   
   kubectl apply -f "$RESTORE_DIR/collectors.json"

2. Дождитесь, пока pod’ы Collector не станут ready:

   kubectl wait --for=condition=Ready pod \
     -l app.kubernetes.io/managed-by=opentelemetry-operator \
     -n <collector-namespace> --timeout=3m

#Воссоздание ресурсов Instrumentation

Для каждого ресурса Instrumentation, который вы сохранили в резервной копии, воссоздайте его на v2, указав новое поле spec.java.image. Endpoint экспортера и другие переменные окружения имеют ту же структуру, что и в v1, но Java auto-instrumentation теперь использует образ autoinstrumentation-java серии 2.x. В этой версии протокол OTLP exporter по умолчанию — http/protobuf, поэтому endpoints, которые ранее указывали на gRPC port Collector 4317, необходимо изменить на HTTP port Collector 4318, если только вы явно не настроите OTEL_EXPORTER_OTLP_PROTOCOL=grpc. При необходимости обновите также значение host, если изменились namespace Collector или имя service.

Используйте тот же рабочий каталог, созданный на предыдущем шаге. В следующем примере ./otel-v1-backup/instrumentations.yaml копируется, spec.java.image задаётся из переменной JAVA_AUTO_INSTRUMENTATION_IMAGE, сохранённое значение OTEL_EXPORTER_OTLP_ENDPOINT изменяется с порта 4317 на 4318, после чего создаются ресурсы Instrumentation:

RESTORE_DIR=./otel-v2-restore
JAVA_AUTO_INSTRUMENTATION_IMAGE="ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1"

mkdir -p "$RESTORE_DIR"
cp ./otel-v1-backup/instrumentations.yaml "$RESTORE_DIR/instrumentations.yaml"

kubectl patch --local -f "$RESTORE_DIR/instrumentations.yaml" --type=json -p='[]' -o json \
  | jq -s --arg javaAutoInstrumentationImage "$JAVA_AUTO_INSTRUMENTATION_IMAGE" '
      {
        apiVersion: "v1",
        kind: "List",
        items: map(
          del(
            .metadata.annotations."kubectl.kubernetes.io/last-applied-configuration",
            .metadata.creationTimestamp,
            .metadata.finalizers,
            .metadata.generation,
            .metadata.managedFields,
            .metadata.resourceVersion,
            .metadata.uid,
            .status
          )
          | .spec.java.image = $javaAutoInstrumentationImage
          | (.spec.env[]? | select(.name == "OTEL_EXPORTER_OTLP_ENDPOINT").value) |= sub(":4317"; ":4318")
          | (.spec.java.env[]? | select(.name == "OTEL_EXPORTER_OTLP_ENDPOINT").value) |= sub(":4317"; ":4318")
        )
      }
    ' > "$RESTORE_DIR/instrumentations.json"

kubectl apply -f "$RESTORE_DIR/instrumentations.json"

#Перевод application pods на новый rollout

Pod’ы приложений, которые ранее были инструментированы v1 Operator, по-прежнему содержат v1 init container, путь к agent и JAVA_TOOL_OPTIONS. Поскольку Collector, на который опирались эти pod’ы, был заменён, экспорт телеметрии из них больше не работает. Выполните rollout затронутых workloads, чтобы mutating webhook v2 внедрил новый образ Java agent и переменные окружения.

1. Выведите список deployments, которые включили Java auto-instrumentation:

   kubectl get deploy -A -o json | jq -r '
     .items[]
     | select(.spec.template.metadata.annotations["instrumentation.opentelemetry.io/inject-java"])
     | "\(.metadata.namespace) \(.metadata.name)"'

2. Перезапустите каждый instrumented deployment и дождитесь завершения rollout. Выберите один из двух подходов ниже в зависимости от того, насколько осторожно вам нужно выполнить проверку.

   Option A — По одному deployment за раз. Выполняйте rollout для каждого Deployment отдельно. Для крупных наборов ресурсов перезапускайте deployments волнами, упорядоченными по критичности, чтобы можно было приостановиться и выполнить проверку после каждой волны.

   kubectl -n <namespace> rollout restart deployment/<name>
   kubectl -n <namespace> rollout status deployment/<name>

   Option B — Все instrumented deployments одной командой. Пройдитесь по каждому Deployment, который включил Java auto-instrumentation. Это быстрее, но не даёт встроенной точки паузы, поэтому подходит для небольших наборов ресурсов или после проверки изменения на canary.

   kubectl get deploy -A -o json | jq -r '
     .items[]
     | select(.spec.template.metadata.annotations["instrumentation.opentelemetry.io/inject-java"])
     | [.metadata.namespace, .metadata.name] | @tsv
   ' | while IFS=$'\t' read -r namespace name; do
     kubectl -n "$namespace" rollout restart deployment/"$name"
     kubectl -n "$namespace" rollout status deployment/"$name"
   done

#Проверка миграции

1. Убедитесь, что существует только CSV v2 Operator и что он достиг фазы Succeeded:

   kubectl get csv -A | grep -i opentelemetry

2. Убедитесь, что workloads v2 Operator работают:

   kubectl -n opentelemetry-operator2 get csv,deploy

3. Убедитесь, что ресурсы OpenTelemetryCollector здоровы и сообщают версию v2:

   kubectl get opentelemetrycollector -A

4. Убедитесь, что у ресурсов Instrumentation настроено spec.java.image:

   kubectl get instrumentation -A \
     -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}{"\t"}{.spec.java.image}{"\n"}{end}'

5. Убедитесь, что instrumented application pod использует новый init container Java agent:

   kubectl -n <namespace> get pod <pod-name> \
     -o jsonpath='{.spec.initContainers[*].image}'

   В выводе должно присутствовать изображение, настроенное в Instrumentation.spec.java.image.

6. Убедитесь, что в pod spec присутствуют переменные окружения OpenTelemetry. Эта проверка выполняется непосредственно на Kubernetes object и не требует, чтобы application container поддерживал kubectl exec или включал команду env.

   kubectl -n <namespace> get pod <pod-name> -o json | jq -r '
     .spec.containers[]
     | .name as $container
     | (.env // [])
     | map(select(.name == "JAVA_TOOL_OPTIONS" or (.name | startswith("OTEL_"))))
     | select(length > 0)
     | "container=" + $container,
       (.[] | "\(.name)=\(.value // (.valueFrom | tostring))")
   '

7. Отправьте тестовый запрос в instrumented application и подтвердите, что полученные traces и metrics отображаются в вашем tracing backend (например, Jaeger UI или консоль Tracing платформы) и в Prometheus.

#Удаление ресурсов v2

kubectl delete instrumentation -A --all
kubectl delete opentelemetrycollector -A --all
kubectl delete subscription opentelemetry-operator2 -n opentelemetry-operator2
kubectl delete csv -n opentelemetry-operator2 --all

#Дождаться полного удаления v2 Operator

kubectl get csv -A | grep -i opentelemetry-operator2

Ожидаемый вывод — пустой.

#Повторная установка v1 Operator

Следуйте процедуре установки v1, описанной в Установка OpenTelemetry Operator.

#Воссоздание ресурсов v1 из резервной копии

Воссоздайте ресурсы OpenTelemetryCollector, Instrumentation, ServiceAccount, ClusterRoleBinding и ServiceMonitor из YAML-файлов, сохранённых в Создание резервной копии ресурсов v1.

#Повторный rollout application pods

Перезапустите workloads с помощью kubectl rollout restart, чтобы mutating webhook v1 повторно внедрил v1 Java agent.