#从 Alauda Build of OpenTelemetry 迁移到 Alauda Build of OpenTelemetry v2

#删除 v1 Instrumentation 资源

1. 列出现有的 Instrumentation 资源：

   kubectl get instrumentation -A

2. 删除每个 Instrumentation 资源。将 <namespace> 和 <name> 替换为上一步中的值：

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

   删除 Instrumentation 不会影响已经被 webhook 修改过的应用 Pod——之前注入的 init container、环境变量和 JAVA_TOOL_OPTIONS 仍然保留在运行中的 Pod 中。删除操作只会阻止 v1 Operator 将它们注入到新创建的 Pod 中。

#删除 v1 OpenTelemetryCollector 资源

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. 删除 v1 部署在 cpaas-system 中创建的 RBAC 和监控资源（如果你的 v1 部署没有创建这些资源，则跳过此步骤）。这些资源已在 备份 v1 资源 中备份，用于回滚。

   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. 等待集群中不再存在任何 v1 Operator CSV。此检查非常重要——如果仍有任何 v1 CSV 存在，由于 CRD 所有者冲突，OLM 会在 步骤 4 中拒绝安装 v2 Operator。

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

   预期输出为空。

#安装 v2 Operator

请遵循 安装 Alauda Build of OpenTelemetry v2 Operator。简化后的 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. 创建 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. 等待 v2 CSV 达到 Succeeded：

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

#重新创建 OpenTelemetryCollector 资源

#此迁移会带来哪些变化

使用 v1 备份重建 OpenTelemetryCollector manifest 时，在应用到 v2 之前必须调整以下方面。

• Collector 命名空间。Collector 命名空间必须与 Operator 命名空间（opentelemetry-operator2）不同。请根据部署场景选择命名空间：

  • Standalone Collector：使用专用命名空间，例如 opentelemetry-collector。
  • Alauda Container Platform Tracing 集成：继续使用相同的 Collector 命名空间（通常是 cpaas-system），这样引用 Collector service 的下游服务就无需修改。
  • Alauda Service Mesh v2 集成：继续将 Collector 放在 istio-system 中，以便现有的 Istio meshConfig.extensionProviders[].opentelemetry.service 仍然有效。

• 组件兼容性。spec.config 中使用的每个组件都必须被 v2 支持。对于与 Alauda Distributed Tracing 集成时推荐的 Collector 配置，请参见 Alauda Distributed Tracing 文档中的 部署 OpenTelemetry Collector。对于其他场景，请遵循 部署 OpenTelemetry Collector 并根据你的环境调整示例。

• Feature gates。v1 Collector 通常通过 spec.args.feature-gates 传递 Collector feature gates。随着 Collector 版本升级，许多 gate 已经稳定化（因此不再可切换）或者被完全移除，因此直接复用 v1 列表可能会导致 v2 Collector Pod 无法启动。请从备份中移除 spec.args.feature-gates，并且只重新引入 v2 Collector 版本明确记录的 gate。

• 内部指标 Prometheus 端点。service.telemetry.metrics.address 字段不再是暴露内部指标 Prometheus 端点的受支持方式。请改为按照 OpenTelemetry Collector 内部遥测文档 的说明，在 service.telemetry.metrics.readers[].pull.exporter.prometheus 下进行配置。典型的 v1 备份如下：

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

• 内部指标详细程度。level: detailed 会为 Collector 自身的内部指标启用 histogram bucket 和按实例标签，这会显著增加 Prometheus 的 cardinality 和存储成本——尤其是在具有大量 receiver/exporter 实例的 Gateway 模式部署中。生产环境推荐使用默认的 level: normal：它仍会暴露进程资源使用情况以及按组件划分的 sent/received/refused/dropped counter，这对于大多数 SRE 告警和容量需求已经足够。只有在调查 exporter 延迟分布或 batch 大小问题时，才临时切换回 detailed。

• 由 API server 管理的元数据。由 API server 写入的字段（metadata.creationTimestamp、metadata.resourceVersion、metadata.uid、metadata.generation、metadata.managedFields、metadata.finalizers、kubectl.kubernetes.io/last-applied-configuration 注解以及 status）不能在创建时复用，必须从备份中删除。

• Operator 管理的 RBAC 和 Prometheus 抓取。v2 Operator 会自动创建 Collector 所需的 ServiceAccount 和 ClusterRoleBinding 资源。从备份中删除 v1 spec.serviceAccount 字段，这样 Operator 就可以使用正确的权限创建一个新的 ServiceAccount；通常无需手动重建 v1 RBAC 资源。若希望 Operator 也为内部 Prometheus 端点创建 ServiceMonitor，请设置 spec.observability.metrics.enableMetrics: true，并向 metadata.labels 添加一个发现标签（例如 prometheus: kube-prometheus），以便你的 Prometheus Operator 实例拾取该资源。如果某个 Collector 组件需要额外的集群级 RBAC（例如 k8sattributes processor 或 k8sobjects receiver），请参见 自动创建所需的 RBAC 资源。

#迁移操作步骤

1. 从备份中重新创建 OpenTelemetryCollector 资源。以下示例会将 ./otel-v1-backup/collectors.yaml 复制到新的工作目录，去除由 server 管理的元数据，删除 v1 spec.serviceAccount 和 spec.args.feature-gates 字段，将 level: detailed 降级为默认的 level: normal，用新的 readers 配置替换已弃用的 address 字段，通过设置 spec.observability.metrics.enableMetrics: true 并添加 prometheus: kube-prometheus 标签来启用由 Operator 管理的 metrics 抓取，以便 kube-prometheus stack 发现自动创建的 ServiceMonitor，最后应用结果。

   jq 不能直接读取 YAML，因此示例中仅使用 kubectl patch --local -p='[]' -o json 作为本地 YAML 到 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. 等待 Collector Pod 就绪：

   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 字段。导出器端点和其他环境变量的结构与 v1 中保持一致，但 Java auto-instrumentation 现在使用 autoinstrumentation-java 2.x 镜像。在此版本中，默认的 OTLP exporter 协议是 http/protobuf，因此之前指向 Collector gRPC 端口 4317 的端点必须改为 Collector HTTP 端口 4318，除非你显式配置 OTEL_EXPORTER_OTLP_PROTOCOL=grpc。如果 Collector 命名空间或 service 名称发生变化，也请更新 host 值。

使用上一步创建的相同工作目录。以下示例会复制 ./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"

#重新滚动应用 Pod

之前由 v1 Operator 注入埋点的应用 Pod 仍然保留 v1 init container、agent 路径和 JAVA_TOOL_OPTIONS。由于这些 Pod 依赖的 Collector 已被替换，这些 Pod 的遥测导出已不再可用。请重新滚动受影响的工作负载，以便 v2 mutating webhook 注入新的 Java agent 镜像和环境变量。

1. 列出启用了 Java auto-instrumentation 的 Deployment：

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

2. 重启每个已埋点的 Deployment，并等待滚动更新完成。根据你需要的验证谨慎程度，从下面两种方法中选择一种。

   选项 A — 一次一个 Deployment。 对每个 Deployment 单独执行 rollout。对于大型集群，建议按关键性分批重启 Deployment，这样可以在每一批之后暂停并验证。

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

   选项 B — 一条命令重启所有已埋点的 Deployment。 遍历所有启用 Java auto-instrumentation 的 Deployment。该方式更快，但没有内置的暂停点，因此更适合小型集群，或者在你已在金丝雀环境验证过更改之后使用。

   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. 验证集群中只存在 v2 Operator CSV，且其状态已达到 Succeeded：

   kubectl get csv -A | grep -i opentelemetry

2. 验证 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. 验证某个已埋点的应用 Pod 使用新的 Java agent init container：

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

   输出中必须包含在 Instrumentation.spec.java.image 中配置的镜像。

6. 验证 Pod spec 中存在 OpenTelemetry 环境变量。此检查直接针对 Kubernetes 对象，无需应用容器支持 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. 向已埋点的应用发送测试请求，并确认生成的 traces 和指标已出现在你的 tracing 后端（例如 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

请遵循 安装 OpenTelemetry Operator 中记录的 v1 安装操作步骤。

#从备份中重新创建 v1 资源

根据 备份 v1 资源 中捕获的 YAML 文件，重新创建 OpenTelemetryCollector、Instrumentation、ServiceAccount、ClusterRoleBinding 和 ServiceMonitor 资源。

#再次滚动应用 Pod

使用 kubectl rollout restart 重启工作负载，以便 v1 mutating webhook 重新注入 v1 Java agent。