Alauda Build of OpenTelemetry v2
  • 简体中文

    • 升级 Auto-instrumentation Agents

    每个 Instrumentation 资源都会在 spec.<language>.image 中指定其注入的 agent 镜像，而该 agent 会通过一个 init container 复制到 application pod 中；当 pod 被准入时，Operator 会注入这个 init container。因此，升级 agent 由两部分组成：

    1. 更新 Instrumentation 资源中的镜像引用
    2. 重启已进行自动插桩的 workload，因为正在运行的 pod 会继续使用其启动时所带的 agent 版本

    下面的示例将 Java agent 从 2.26.1 升级到 2.30.0。对于其他受支持的语言，只需替换对应字段即可，同样适用：spec.python.image、spec.nodejs.image、spec.dotnet.image、spec.go.image 或 spec.apacheHttpd.image。

    为什么 Operator 不会替你执行此操作

    Operator 会在 instrumentation.opentelemetry.io/default-auto-instrumentation-<language>-image 注解中记录默认情况下它将注入的镜像，并在启动时为任何其镜像仍与该默认值匹配的语言重写 spec.<language>.image。你自己提供的镜像永远不会匹配，因此会保持不变。这里始终如此，因为 Operator 只提供注入机制，不包含预构建的 instrumentation 镜像：每个 spec.<language>.image 都保存的是你自行构建或获取的镜像。

    前提条件

    • 如 升级 Alauda Build of OpenTelemetry v2 所述，Alauda Build of OpenTelemetry v2 Operator 已升级到 0.157.0。
    • 要升级到的 agent 镜像由你自行构建或获取，并且可以从集群中拉取。Operator 不包含预构建的 instrumentation libraries 或 container images；请参见 Instrumentation Options。
    • 由具有 cluster-admin 角色的 cluster administrator 持有的有效 ACP CLI (kubectl) 会话。

    目录

    更新 Instrumentation 资源重启已进行自动插桩的 Workloads验证版本注意事项

    更新 Instrumentation 资源

    1. 列出 Instrumentation 资源以及每个资源注入的 Java agent 镜像：

      kubectl get instrumentation -A \
  -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,JAVA_IMAGE:.spec.java.image

      示例输出

      NAMESPACE          NAME              JAVA_IMAGE
otelv2-java-demo   acp-common-java   <registry>/opentelemetry-operator/autoinstrumentation-java:2.26.1

    2. 设置后续命令使用的环境变量：

      # Namespace and name of the Instrumentation resource to upgrade
export INSTR_NS="otelv2-java-demo"
export INSTR_NAME="acp-common-java"
# Java agent image to upgrade to
export JAVA_AGENT_IMAGE="<registry>/opentelemetry-operator/autoinstrumentation-java:2.30.0"

    3. 更新镜像引用：

      kubectl -n ${INSTR_NS} patch instrumentation ${INSTR_NAME} --type=merge \
  -p "{\"spec\":{\"java\":{\"image\":\"${JAVA_AGENT_IMAGE}\"}}}"
      NOTE

      Instrumentation 资源仅在 pod 被准入时读取，因此此 patch 对已在运行的 pod 不会产生影响，它们也不会重启。

      Operator 会为其支持的每种语言填充默认镜像，而不仅仅是你配置的那一种；当这些默认值中的某一个过旧而无法自动升级时，Operator 会发出警告——例如 dotnet image ... 1.2.0 is at a version that cannot be automatically upgraded。该警告与正在升级的语言无关，也不会阻止该 patch 被应用。

    重启已进行自动插桩的 Workloads

    1. 列出更新后的 Instrumentation 资源所适用的 workloads：

      kubectl -n ${INSTR_NS} get deployment -o json | jq -r '
  .items[]
  | select(.spec.template.metadata.annotations["instrumentation.opentelemetry.io/inject-java"])
  | .metadata.name'
      NOTE

      注入注解也可以设置在 namespace 上，此时该 namespace 中的每个 workload 都会被插桩，上面的命令将不会返回任何结果。请根据你部署中启用注入的方式调整选择条件，并以相同方式覆盖 DaemonSet 和 StatefulSet workloads。

    2. 重启每个 workload，并等待其变为 ready：

      for DEPLOY in $(kubectl -n ${INSTR_NS} get deployment -o json | jq -r '
  .items[]
  | select(.spec.template.metadata.annotations["instrumentation.opentelemetry.io/inject-java"])
  | .metadata.name'); do
  kubectl -n ${INSTR_NS} rollout restart deployment/"${DEPLOY}"
  kubectl -n ${INSTR_NS} rollout status deployment/"${DEPLOY}" --timeout=300s
done
      WARNING

      重启 workloads 会中断它们所提供的流量。如果应用无法容忍滚动重启，请在维护窗口期间进行发布，或者一次只重启一个。

    验证

    1. 确认注入的 init container 运行的是新的 agent 镜像：

      kubectl -n ${INSTR_NS} get pods \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.initContainers[*].image}{"\n"}{end}'

      示例输出

      otel-demo-consumer-for-test-7f69ffbbd6-fvgnv    <registry>/opentelemetry-operator/autoinstrumentation-java:2.30.0
otel-demo-provider-for-test-9d648d8ff-mn9rx     <registry>/opentelemetry-operator/autoinstrumentation-java:2.30.0

      如果某个 pod 列出时没有镜像，则说明它未进行自动插桩，原因可能是它没有携带注入注解，或者是在添加该注解之前就已经被准入。

    2. 确认 agent 已加载到 application JVM 中。Operator 会将 agent 挂载到一个以其所插桩 container 命名的目录下：

      kubectl -n ${INSTR_NS} get pods \
  -o jsonpath='{range .items[*].spec.containers[*].env[?(@.name=="JAVA_TOOL_OPTIONS")]}{.value}{"\n"}{end}'

      示例输出

       -javaagent:/otel-auto-instrumentation-java-otel-demo-consumer-for-test/javaagent.jar
 -javaagent:/otel-auto-instrumentation-java-otel-demo-provider-for-test/javaagent.jar

    3. 生成 application 流量，并确认 traces 仍然到达 Collector。如果 Collector 使用 debug exporter，则 span batches 会出现在其日志中：

      kubectl logs deployment/otel-collector -n opentelemetry-collector --tail=50 | grep '"spans":'

      示例输出

      2026-08-28T11:05:30.145Z  info  Traces  {..., "otelcol.component.id": "debug", "otelcol.signal": "traces", "resource spans": 1, "spans": 8}

    版本注意事项

    • 此版本中的 Instrumentation API 没有变化。新增了两个可选字段：spec.initContainerSecurityContext，用于设置注入的 init containers 的 security context；以及 spec.go.securityContext，用于覆盖 Go sidecar 的默认值。请参见 Security Context Configuration。
    • agent 的发布独立于 Operator，并遵循各自的版本流。在将其发布到 production 之前，请先查看你要升级的 agent 的 release notes，了解行为变化，例如新增或重命名的 span attributes。
    • 在 spec.exporter.endpoint 中配置的 exporter endpoint 不受此次升级影响。Java agent 仍默认使用 http/protobuf protocol，因此除非显式设置 OTEL_EXPORTER_OTLP_PROTOCOL=grpc，否则该 endpoint 必须指向端口 4318 上的 Collector OTLP HTTP receiver。