#升级 Alauda Build of OpenTelemetry v2

从 v2.0（Operator 0.147.0、Collector 0.147.0）升级到 v2.1（Operator 0.157.0、Collector 0.158.0）需要执行以下步骤：

1. 升级 Alauda Build of OpenTelemetry v2 Operator
2. 更新 OpenTelemetry Collector 配置

前提条件

• 已按照安装 Alauda Build of OpenTelemetry v2 中的说明安装 Alauda Build of OpenTelemetry v2.0 部署。
• Alauda Container Platform Application Observability（之前称为 Alauda Build of OpenTelemetry v2）Operator 0.157.0 已发布到平台。
• 集群管理员已启动 ACP CLI (kubectl) 会话，并具有 cluster-admin 角色。
• 查看升级说明，了解此版本引入的行为变更。

设置环境变量

# Namespace of the OpenTelemetry Collector instance
export OTEL_NS="opentelemetry-collector"
# Name of the OpenTelemetryCollector resource
export OTEL_INSTANCE_NAME="otel"
# Endpoint that the OTLP exporter of this Collector already sends traces to
export OTEL_TRACES_ENDPOINT="jaeger-collector.jaeger-system.svc.cluster.local:4317"

#升级 Operator

Operator 使用 Manual 审批策略订阅，因此必须明确批准升级。有关 Operator 升级的一般背景信息，请参阅Operator。

#通过 Web 控制台升级

选择以下任一方法：

• 批量升级：前往平台管理 > 集群管理 > 集群 > 集群 > 功能组件，然后升级 Alauda Container Platform Application Observability（对于重命名前发布的软件包，显示为 Alauda Build of OpenTelemetry v2）。
• 单独升级：前往管理员 > Marketplace > OperatorHub，打开 Alauda Container Platform Application Observability（对于重命名前发布的软件包，显示为 Alauda Build of OpenTelemetry v2），并批准待处理的升级请求。

#通过 CLI 升级

1. 确认目标版本在已订阅的频道中可用：

   kubectl -ncpaas-system get packagemanifest opentelemetry-operator2 \
     -o jsonpath='{range .status.channels[*]}{.name}{"\t"}{.currentCSV}{"\n"}{end}'

2. 批准待处理的 InstallPlan：

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

3. 等待新的 ClusterServiceVersion 进入 Succeeded 阶段：

   kubectl -nopentelemetry-operator2 get csv

   输出示例

   NAME                                  DISPLAY                            VERSION      REPLACES                              PHASE
   opentelemetry-operator2.v0.157.0-r1   Alauda Build of OpenTelemetry v2   0.157.0-r1   opentelemetry-operator2.v0.147.0-r0   Succeeded

验证

升级 Operator 会重启其管理的所有 Collector。未固定 spec.image 的 Collector 会在 Operator 升级后立即使用 Collector 0.158.0：

kubectl -n${OTEL_NS} get opentelemetrycollector ${OTEL_INSTANCE_NAME} \
  -o custom-columns=NAME:.metadata.name,VERSION:.status.version,READY:.status.scale.statusReplicas,IMAGE:.status.image

输出示例

NAME   VERSION   READY   IMAGE
otel   0.157.0   1/1     build-harbor.alauda.cn/asm/opentelemetry-collector:0.158.0-r1

VERSION 报告管理该实例的 Operator 版本，IMAGE 报告该实例当前运行的 Collector 镜像。

#更新 OpenTelemetry Collector 配置

仅使用类型名称未更改的组件的 Collector（例如通过安装操作步骤创建的配置）无需更改配置。

操作步骤

1. 列出弃用警告，以找出配置中受影响的组件：

   kubectl logs deployment/${OTEL_INSTANCE_NAME}-collector -n ${OTEL_NS} --tail=500 \
     | grep -o '"[a-z_]*" alias is deprecated; use "[a-z_]*" instead' \
     || echo "No deprecation warnings"

   输出示例

   "otlp" alias is deprecated; use "otlp_grpc" instead
   "resourcedetection" alias is deprecated; use "resource_detection" instead
   "spanmetrics" alias is deprecated; use "span_metrics" instead

   完整日志行还会列出受影响的组件实例，例如 "otelcol.component.id": "otlp/traces"。

2. 创建名为 otel-upgrade-patch.yaml 的文件。以下示例迁移使用 resourcedetection processor、spanmetrics connector、名为 otlp/traces 的 otlp exporter 以及 prometheus exporter 的 Collector。只保留与你自己的配置匹配的条目：

   otel-upgrade-patch.yaml

   spec:
     config:
       processors:
         resourcedetection: null
         resource_detection:
           detectors: [env]
           timeout: 2s
       connectors:
         spanmetrics: null
         span_metrics: {}
       exporters:
         otlp/traces: null
         otlp_grpc/traces:
           endpoint: "${OTEL_TRACES_ENDPOINT}"
           tls:
             insecure: true
         prometheus:
           endpoint: 0.0.0.0:8889
           add_metric_suffixes: null
           translation_strategy: UnderscoreEscapingWithoutSuffixes
       service:
         pipelines:
           traces:
             processors: [memory_limiter, resource_detection, batch]
             exporters: [debug, otlp_grpc/traces, span_metrics]
           metrics/spanmetrics:
             receivers: [span_metrics]
   1. 重命名的组件需要将旧键设置为 null，并在新名称下重新创建。请原样复制现有设置：合并补丁不会自动传递这些设置，也不会隐式删除旧键；同时保留两个键会启动同一组件的两个实例。有关重命名组件的完整列表，请参阅组件类型名称现已使用 snake_case。
   2. add_metric_suffixes 已弃用。prometheus exporter 会完全忽略它，因此现在应使用 translation_strategy: UnderscoreEscapingWithoutSuffixes，以使导出的指标名称不带 Prometheus 风格的后缀（例如 _total）。prometheus_remote_write exporter 仍支持 add_metric_suffixes，但会记录弃用警告。
   3. 引用重命名组件的每个管道也必须更新，否则 Collector 会因 references exporter "otlp/traces" which is not configured 启动失败。由于管道成员是列表，因此每个列表都会被整体替换。

3. 使用 envsubst 渲染补丁并应用：

   kubectl patch opentelemetrycollector ${OTEL_INSTANCE_NAME} -n ${OTEL_NS} \
     --type=merge -p "$(envsubst < otel-upgrade-patch.yaml)"

验证

等待 Collector 重启，并确认其启动时没有弃用警告：

kubectl rollout status deployment/${OTEL_INSTANCE_NAME}-collector -n ${OTEL_NS} --timeout=180s
sleep 3
kubectl logs deployment/${OTEL_INSTANCE_NAME}-collector -n ${OTEL_NS} --tail=500 \
  | grep -i "deprecated" || echo "No deprecation warnings"

输出示例

deployment "otel-collector" successfully rolled out
No deprecation warnings

#不受别名覆盖的更改

以下更改不会报告弃用警告，因为受影响的配置要么仍能以不同的行为启动，要么会直接启动失败。请对照你自己的配置进行检查：

完整列表请参阅升级说明。

#后续步骤

Operator 不会升级注入到应用 Pod 中的自动插桩代理。要升级这些代理，请按照升级自动插桩代理中的说明操作。