#从 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 存在，OLM 会因为 CRD 所有权冲突而拒绝在步骤 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 清单时，在应用到 v2 之前，必须调整以下方面。

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

  • 独立 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 端点的受支持方式。请改为在 service.telemetry.metrics.readers[].pull.exporter.prometheus 下进行配置，如 OpenTelemetry Collector internal telemetry 文档所述。典型的 v1 备份如下：

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

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

• 服务器管理的元数据。由 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 复制到新的工作目录，移除服务器管理的元数据，删除 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 字段。exporter 端点和其他环境变量的结构与 v1 相同，但 Java 自动注入现在使用 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 复制出来，从 JAVA_AUTO_INSTRUMENTATION_IMAGE 变量设置 spec.java.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 自动注入的 deployments：

   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 自动注入的 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 和 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

请按照 安装 OpenTelemetry Operator 中记录的 v1 安装操作步骤执行。

#从备份中重建 v1 资源

从 备份 v1 资源中保存的 YAML 文件重建 OpenTelemetryCollector、Instrumentation、ServiceAccount、ClusterRoleBinding 和 ServiceMonitor 资源。

#再次滚动应用 Pod

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