#升级 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 Build of OpenTelemetry v2 Operator 0.157.0 已发布到平台。
• 集群管理员使用 cluster-admin 角色拥有一个有效的 ACP CLI（kubectl）会话。
• 查看 升级说明，了解此版本引入的行为变更。

设置环境变量

# 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 控制台升级

请选择以下方法之一：

• 批量升级：导航到 Platform Management > Cluster Management > Clusters > cluster > Functional Components，然后升级 Alauda Build of OpenTelemetry v2。
• 单独升级：导航到 Administrator > Marketplace > OperatorHub，打开 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，并使用新名称重新创建。请保持现有设置不变地复制过去：merge patch 不会继承这些设置，也不会隐式删除旧键，同时保留两个键会启动同一组件的两个实例。有关已重命名组件的完整列表，请参见 组件类型名称现在使用 snake_case。
   2. add_metric_suffixes 已弃用。prometheus exporter 完全忽略该项，因此现在通过 translation_strategy: UnderscoreEscapingWithoutSuffixes 来确保导出的 metric 名称不包含诸如 _total 之类的 Prometheus 风格后缀。prometheus_remote_write exporter 仍然支持 add_metric_suffixes，但会记录弃用警告。
   3. 任何引用了已重命名组件的 pipeline 也必须一并更新，否则 Collector 将无法启动，并报错 references exporter "otlp/traces" which is not configured。由于 pipeline 成员是列表，因此每个列表都必须整体替换。

3. 使用 envsubst 渲染 patch 并应用它：

   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 中的自动埋点 agent。要升级它们，请按照 升级自动埋点 agent 中的说明操作。