OpenTelemetry Operator 概述

OpenTelemetry Operator 是一个 Kubernetes Operator 实现，用于管理 OpenTelemetry Collector 和自动注入工作负载的 OpenTelemetry instrumentation 库。它简化了在 Kubernetes 环境中部署和管理 OpenTelemetry 组件的复杂性，提供了声明式的配置方式和自动化管理能力。

概述

OpenTelemetry Operator 是 OpenTelemetry 项目的一部分，专门为 Kubernetes 环境设计。它通过 Kubernetes 的 Operator 模式，实现了对 OpenTelemetry 组件的自动化管理。

什么是 Kubernetes Operator？

Kubernetes Operator 是一种扩展 Kubernetes API 的软件，它使用自定义资源（Custom Resources）和控制器（Controllers）来管理应用程序及其组件。Operator 封装了运维知识，使复杂的应用程序管理变得自动化。

OpenTelemetry Operator 的价值

• 自动化管理：自动创建、更新和删除 OpenTelemetry Collector 实例
• 零代码注入：自动为工作负载注入 OpenTelemetry instrumentation，无需修改应用代码
• 声明式配置：使用 Kubernetes YAML 配置文件，易于版本控制和 GitOps
• 统一管理：在一个地方管理所有 OpenTelemetry 相关组件
• 简化部署：减少手动配置和部署步骤

Operator 架构和工作原理

架构图

┌─────────────────────────────────────────────────────────┐
│              Kubernetes Cluster                          │
│                                                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │      OpenTelemetry Operator                      │  │
│  │  ┌──────────────┐  ┌──────────────────────┐    │  │
│  │  │   Manager    │  │   Webhook Server      │    │  │
│  │  │  (Controller)│  │  (Mutating Webhook)   │    │  │
│  │  └──────┬───────┘  └──────────┬────────────┘    │  │
│  └─────────┼──────────────────────┼─────────────────┘  │
│            │                      │                      │
│            │                      │                      │
│  ┌─────────▼──────────────────────▼─────────────────┐  │
│  │         Custom Resources (CR)                     │  │
│  │  ┌──────────────────┐  ┌──────────────────┐    │  │
│  │  │OpenTelemetry     │  │Instrumentation    │    │  │
│  │  │Collector (CR)    │  │(CR)               │    │  │
│  │  └──────────────────┘  └──────────────────┘    │  │
│  └──────────────────────────────────────────────────┘  │
│            │                      │                      │
│            │                      │                      │
│  ┌─────────▼──────────────────────▼─────────────────┐  │
│  │         Managed Resources                        │  │
│  │  ┌──────────────────┐  ┌──────────────────┐    │  │
│  │  │Collector         │  │Instrumented Pods │    │  │
│  │  │Deployment/       │  │(with sidecar)    │    │  │
│  │  │StatefulSet       │  │                  │    │  │
│  │  └──────────────────┘  └──────────────────┘    │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

工作原理

1. 资源监听：Operator 监听 Kubernetes 集群中的自定义资源（OpenTelemetryCollector、Instrumentation）
2. 配置解析：解析自定义资源的配置，验证配置的有效性
3. 资源创建：根据配置创建相应的 Kubernetes 资源（Deployment、StatefulSet、Service 等）
4. 自动注入：通过 Mutating Webhook 自动为 Pod 注入 instrumentation sidecar
5. 持续监控：持续监控资源状态，确保配置与实际状态一致（Reconciliation）

核心组件

Manager（控制器）

Manager 是 Operator 的核心组件，负责：

• 监听自定义资源的变化
• 执行 Reconciliation 循环
• 创建和管理 Kubernetes 资源
• 处理配置验证和错误

Webhook Server（Webhook 服务器）

Webhook Server 负责：

• 接收 Pod 创建请求
• 根据 Instrumentation 配置决定是否注入
• 修改 Pod 配置以添加 instrumentation sidecar
• 注入环境变量和初始化容器

Operator 管理的组件

OpenTelemetry Collector

OpenTelemetry Operator 可以管理 OpenTelemetry Collector 的生命周期：

• 创建 Collector 实例：根据 OpenTelemetryCollector 自定义资源创建 Collector
• 配置管理：管理 Collector 的配置（receivers、processors、exporters）
• 部署模式：支持 Deployment、StatefulSet、DaemonSet 等部署模式
• 资源管理：管理 Collector 的资源请求和限制
• 自动扩缩容：支持 Horizontal Pod Autoscaling (HPA)
• 服务发现：支持 Target Allocator 进行 Prometheus targets 分发

自动注入 (Auto-instrumentation)

Operator 可以自动为工作负载注入 OpenTelemetry instrumentation：

• 零代码注入：无需修改应用代码即可获得可观测性
• 多语言支持：支持 Java、Python、Node.js、.NET、Go、PHP 等
• 命名空间级别：可以为整个命名空间启用自动注入
• Pod 级别：可以为特定 Pod 启用自动注入
• 灵活配置：支持自定义 SDK 配置、采样率、资源属性等

前置要求

在安装和使用 OpenTelemetry Operator 之前，需要确保满足以下要求：

Kubernetes 集群要求

• Kubernetes 版本：1.19 或更高版本
• API 服务器：需要支持 CustomResourceDefinition (CRD)
• 权限：需要集群管理员权限来安装 Operator

cert-manager 安装

OpenTelemetry Operator 使用 cert-manager 来管理 Webhook 的 TLS 证书。在安装 Operator 之前，必须先安装 cert-manager。

检查 cert-manager

# 检查 cert-manager 是否已安装
kubectl get pods -n cert-manager

# 如果没有安装，先安装 cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

# 等待 cert-manager 就绪
kubectl wait --for=condition=ready pod -l app.kubernetes.io/instance=cert-manager -n cert-manager --timeout=300s

cert-manager 版本要求

• cert-manager 版本：1.0.0 或更高版本

权限要求

安装 Operator 需要以下权限：

• ClusterRole：创建和管理 CustomResourceDefinition
• ClusterRoleBinding：绑定 ClusterRole 到 ServiceAccount
• ServiceAccount：Operator 运行所需的 ServiceAccount
• Webhook 权限：创建和管理 MutatingWebhookConfiguration

网络要求

• API 服务器访问：Operator 需要访问 Kubernetes API 服务器
• 镜像拉取：需要能够从容器镜像仓库拉取镜像
• 网络策略：确保网络策略允许必要的通信

安装 Operator

OpenTelemetry Operator 可以通过两种方式安装：使用 kubectl 直接安装，或使用 Helm Chart 安装。

方式一：使用 kubectl 安装（推荐）

这是最简单的安装方式，适合快速开始：

# 安装最新版本的 Operator
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

安装特定版本

如果需要安装特定版本，可以指定版本号：

# 安装 v0.100.0 版本
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.100.0/opentelemetry-operator.yaml

验证安装

安装完成后，验证 Operator 是否正常运行：

# 检查 Operator 命名空间
kubectl get namespace opentelemetry-operator-system

# 检查 Operator Pod 状态
kubectl get pods -n opentelemetry-operator-system

# 查看 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=50

预期输出示例：

NAME                                                  READY   STATUS    RESTARTS   AGE
opentelemetry-operator-controller-manager-xxxxx      2/2     Running   0          2m

方式二：使用 Helm 安装

使用 Helm 可以提供更多的配置选项：

# 添加 Helm 仓库
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

# 安装 Operator
helm install opentelemetry-operator open-telemetry/opentelemetry-operator

Helm 配置选项

使用 Helm 可以自定义配置：

# values.yaml
manager:
  image:
    repository: ghcr.io/open-telemetry/opentelemetry-operator
    tag: "0.100.0"
  resources:
    limits:
      cpu: 500m
      memory: 256Mi
    requests:
      cpu: 100m
      memory: 128Mi

webhook:
  image:
    repository: ghcr.io/open-telemetry/opentelemetry-operator
    tag: "0.100.0"

安装时指定配置文件：

helm install opentelemetry-operator open-telemetry/opentelemetry-operator -f values.yaml

验证安装

无论使用哪种安装方式，都应该验证安装是否成功：

# 1. 检查 CustomResourceDefinition 是否创建
kubectl get crd | grep opentelemetry

# 应该看到以下 CRD：
# - opentelemetrycollectors.opentelemetry.io
# - instrumentations.opentelemetry.io

# 2. 检查 Operator Pod 状态
kubectl get pods -n opentelemetry-operator-system

# 3. 检查 Webhook 配置
kubectl get mutatingwebhookconfiguration | grep opentelemetry

# 4. 检查 Operator 日志（确认没有错误）
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator --tail=100

创建第一个 Collector 实例

安装 Operator 后，可以创建第一个 OpenTelemetry Collector 实例。

基本配置示例

创建一个最简单的 Collector 配置：

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: simplest
  namespace: default
spec:
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      memory_limiter:
        check_interval: 1s
        limit_percentage: 75
        spike_limit_percentage: 15
    exporters:
      debug: {}
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter]
          exporters: [debug]

配置说明

apiVersion 和 kind

• apiVersion: opentelemetry.io/v1beta1：OpenTelemetryCollector 自定义资源的 API 版本
• kind: OpenTelemetryCollector：资源类型

metadata

• name: simplest：Collector 实例的名称
• namespace: default：部署的命名空间

spec.config

spec.config 字段包含 OpenTelemetry Collector 的配置，使用 YAML 格式。这个配置与标准的 OpenTelemetry Collector 配置格式相同。

配置组件说明：

• receivers：数据接收器

  • otlp：OpenTelemetry Protocol 接收器
    • grpc：gRPC 协议，端口 4317
    • http：HTTP 协议，端口 4318

• processors：数据处理器

  • memory_limiter：内存限制处理器，防止内存溢出
    • check_interval: 1s：检查间隔
    • limit_percentage: 75：内存使用限制（75%）
    • spike_limit_percentage: 15：峰值限制（15%）

• exporters：数据导出器

  • debug：调试导出器，将数据输出到日志

• service.pipelines：数据处理管道

  • traces：追踪数据管道
    • receivers: [otlp]：使用 OTLP 接收器
    • processors: [memory_limiter]：使用内存限制处理器
    • exporters: [debug]：使用调试导出器

应用配置

保存配置到文件（例如 collector.yaml），然后应用：

# 应用配置
kubectl apply -f collector.yaml

# 检查 Collector 状态
kubectl get opentelemetrycollector

# 查看 Collector Pod
kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector

# 查看 Collector 日志
kubectl logs -l app.kubernetes.io/name=opentelemetry-collector --tail=50

验证部署

验证 Collector 是否正常工作：

# 1. 检查 Collector Pod 状态
kubectl get pods -l app.kubernetes.io/name=opentelemetry-collector

# 预期输出：
# NAME                              READY   STATUS    RESTARTS   AGE
# simplest-collector-xxxxx          1/1     Running   0          1m

# 2. 检查 Collector Service
kubectl get svc -l app.kubernetes.io/name=opentelemetry-collector

# 预期输出：
# NAME              TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
# simplest-collector   ClusterIP   10.96.xxx.xxx   <none>        4317/TCP,4318/TCP   1m

# 3. 检查 Collector 日志（应该看到接收到的数据）
kubectl logs -l app.kubernetes.io/name=opentelemetry-collector --tail=20

发送测试数据

可以使用 OpenTelemetry 示例应用发送测试数据：

# 获取 Collector Service 地址
COLLECTOR_SERVICE=$(kubectl get svc -l app.kubernetes.io/name=opentelemetry-collector -o jsonpath='{.items[0].metadata.name}')

# 使用 otel-cli 发送测试数据（需要先安装 otel-cli）
otel-cli span --service test-service --name test-span --endpoint http://$COLLECTOR_SERVICE:4318

Operator 配置选项

OpenTelemetryCollector 自定义资源支持多种配置选项。

部署模式 (mode)

Operator 支持三种部署模式：

1. Deployment 模式（默认）

适用于无状态 Collector，可以水平扩展：

spec:
  mode: deployment
  replicas: 3

2. StatefulSet 模式

适用于需要持久化存储或有序部署的场景：

spec:
  mode: statefulset
  replicas: 2

3. DaemonSet 模式

适用于在每个节点上运行一个 Collector 的场景：

spec:
  mode: daemonset

镜像配置 (image)

默认情况下，Operator 使用 otel/opentelemetry-collector 镜像。可以自定义镜像：

spec:
  image: otel/opentelemetry-collector-contrib:0.100.0

镜像选择建议：

• otel/opentelemetry-collector：核心镜像，包含基本组件
• otel/opentelemetry-collector-contrib：贡献镜像，包含所有社区贡献的组件（推荐）
• otel/opentelemetry-collector-k8s：Kubernetes 优化镜像（使用 Helm 安装时默认使用）

资源限制 (resources)

配置 Collector 的资源请求和限制：

spec:
  resources:
    limits:
      cpu: 1000m
      memory: 512Mi
    requests:
      cpu: 200m
      memory: 128Mi

服务账户 (serviceAccount)

指定 Collector 使用的服务账户：

spec:
  serviceAccount: otel-collector-sa

环境变量 (env)

为 Collector 容器添加环境变量：

spec:
  env:
    - name: MY_ENV_VAR
      value: "my-value"
    - name: ANOTHER_VAR
      valueFrom:
        secretKeyRef:
          name: my-secret
          key: secret-key

卷挂载 (volumeMounts)

挂载 ConfigMap、Secret 或其他卷：

spec:
  volumeMounts:
    - name: config-volume
      mountPath: /etc/otelcol
  volumes:
    - name: config-volume
      configMap:
        name: my-config

自动扩缩容 (autoscaler)

配置 Horizontal Pod Autoscaling：

spec:
  autoscaler:
    minReplicas: 1
    maxReplicas: 5
    targetCPUUtilization: 70
    targetMemoryUtilization: 80

详细配置请参考 HPA 配置文档。

Target Allocator

启用 Target Allocator 进行 Prometheus targets 分发：

spec:
  targetAllocator:
    enabled: true

详细配置请参考 Target Allocator 文档。

完整配置示例

结合多个配置选项的完整示例：

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: production-collector
  namespace: observability
spec:
  mode: statefulset
  replicas: 3
  image: otel/opentelemetry-collector-contrib:0.100.0
  serviceAccount: otel-collector-sa
  resources:
    limits:
      cpu: 2000m
      memory: 1Gi
    requests:
      cpu: 500m
      memory: 256Mi
  autoscaler:
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilization: 70
    targetMemoryUtilization: 80
  targetAllocator:
    enabled: true
  env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: "service.name=collector,service.version=1.0.0"
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      memory_limiter:
        check_interval: 1s
        limit_percentage: 75
        spike_limit_percentage: 15
      batch:
        timeout: 1s
        send_batch_size: 1024
    exporters:
      otlp:
        endpoint: uptrace-grpc.yodao.cn:4317
        tls:
          insecure: false
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [otlp]
        metrics:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [otlp]
        logs:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [otlp]

与现有文档的集成

OpenTelemetry Operator 与现有文档体系的关系：

与语言接入文档的关系

• 自动注入：Operator 可以自动注入 instrumentation，无需手动配置 SDK
• 配置方式：仍然可以通过环境变量或配置文件自定义 SDK 行为
• 兼容性：自动注入与手动接入完全兼容

参考文档：

• Golang 接入指南
• Java 接入指南
• Python 接入指南

与高级配置文档的关系

• 采样配置：可以在 Instrumentation 资源中配置采样
• 资源属性：可以配置资源属性
• 自定义配置：支持所有高级配置选项

参考文档：

• 采样配置
• 性能优化

与 Uptrace 平台的关系

• 数据导出：Collector 可以导出数据到 Uptrace 平台
• DSN 配置：在 Collector 配置中使用 Uptrace DSN
• 平台功能：可以使用 Uptrace 平台的所有功能

参考文档：

• Uptrace 平台概览
• DSN 配置与查看

常见问题

1. Operator 安装失败？

可能原因：

• cert-manager 未安装或版本不兼容
• 权限不足
• 网络问题导致无法拉取镜像

解决方法：

# 检查 cert-manager
kubectl get pods -n cert-manager

# 检查 Operator 日志
kubectl logs -n opentelemetry-operator-system -l app.kubernetes.io/name=opentelemetry-operator

# 检查事件
kubectl get events -n opentelemetry-operator-system --sort-by='.lastTimestamp'

2. Collector 无法启动？

可能原因：

• 配置错误
• 资源不足
• 镜像拉取失败

解决方法：

# 检查 Collector Pod 状态
kubectl describe pod <collector-pod-name>

# 检查 Collector 日志
kubectl logs <collector-pod-name>

# 验证配置
kubectl get opentelemetrycollector <collector-name> -o yaml

3. 自动注入不工作？

可能原因：

• Webhook 未正确配置
• Instrumentation 资源未创建
• Pod 注解配置错误

解决方法：

# 检查 Webhook 配置
kubectl get mutatingwebhookconfiguration

# 检查 Instrumentation 资源
kubectl get instrumentation

# 检查 Pod 注解
kubectl get pod <pod-name> -o yaml | grep instrumentation

详细故障排查请参考 故障排查文档。

4. 如何升级 Operator？

升级步骤：

# 备份现有配置
kubectl get opentelemetrycollector -A -o yaml > backup.yaml

# 升级 Operator
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

# 验证升级
kubectl get pods -n opentelemetry-operator-system

5. 如何卸载 Operator？

卸载步骤：

# 删除所有 Collector 实例
kubectl delete opentelemetrycollector --all --all-namespaces

# 删除 Operator
kubectl delete -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

# 清理 CRD（可选）
kubectl delete crd opentelemetrycollectors.opentelemetry.io
kubectl delete crd instrumentations.opentelemetry.io

下一步

• 自动注入 - 了解如何自动注入 instrumentation
• 水平 Pod 自动扩缩容 - 配置 Collector 的自动扩缩容
• Target Allocator - 使用 Target Allocator 分发 Prometheus targets
• 故障排查 - 解决常见问题
• 语言接入指南 - 了解手动接入方式

参考资源

• OpenTelemetry Operator 官方文档
• OpenTelemetry Operator GitHub
• OpenTelemetry Collector 文档
• Kubernetes Operator 模式