jaegertracing/jaeger-operator

Jaeger Operator for Kubernetes 技术文档

镜像概述和主要用途

Jaeger Operator 是一个 Kubernetes Operator，用于在 Kubernetes 集群中自动化部署、配置、管理和升级 Jaeger 分布式追踪系统。通过自定义资源（Custom Resource, CR）抽象，Jaeger Operator 简化了 Jaeger 实例的生命周期管理，降低了在 Kubernetes 环境中构建可观测性平台的复杂度。

核心功能和特性

• 自定义资源（CR）支持：通过 Jaeger 自定义资源定义（CRD）声明式管理 Jaeger 实例，支持 YAML 配置即部署。
• 多部署策略：内置 all-in-one（测试）、production（生产）等部署策略，适配不同环境需求。
• 自动化生命周期管理：自动处理 Jaeger 组件的部署、升级、回滚及资源清理，无需手动操作 Kubernetes 原生资源（如 Deployment、Service）。
• 存储集成：支持 Elasticsearch、Cassandra、Kafka 等主流存储后端，可通过 CR 配置自动关联存储资源。
• Kubernetes 原生集成：自动生成 ConfigMap、Secret、Service、Ingress 等资源，支持与 Prometheus、Grafana 等可观测性工具联动。
• 采样策略自动注入：通过 MutatingWebhook 向应用 Pod 自动注入 Jaeger 采样配置，简化追踪接入。
• 配置动态更新：支持通过 CR 字段修改实时更新 Jaeger 配置（如存储参数、资源限制），无需重启 Operator。

使用场景和适用范围

• 微服务架构分布式追踪：需对跨服务请求链路进行追踪、排查延迟或错误的场景。
• Kubernetes 可观测性平台：作为可观测性栈（Prometheus + Grafana + Jaeger）的核心组件，构建完整监控体系。
• 简化 Jaeger 管理：团队希望避免手动管理 Jaeger 组件（如 Collector、Query、Agent）及存储资源时使用。
• 多环境一致性部署：需在开发、测试、生产环境中快速复用 Jaeger 配置，保证环境一致性。
• 大规模集群管理：在多租户或大规模 Kubernetes 集群中，通过 Operator 统一管控多个 Jaeger 实例。

详细的使用方法和配置说明

安装 Jaeger Operator

前提条件

• Kubernetes 集群版本 ≥ 1.21（推荐 1.24+）。
• 集群已启用 RBAC（默认启用）。
• 若使用生产模式，需提前部署存储后端（如 Elasticsearch）。

安装方式

1. 通过 Helm Chart 安装（推荐）

Helm 是 Jaeger Operator 官方推荐的安装方式，支持版本控制和参数自定义：

bash
# 添加 Jaeger Helm 仓库
helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
helm repo update

# 安装 Operator（默认命名空间：observability）
helm install jaeger-operator jaegertracing/jaeger-operator \
  --namespace observability \
  --create-namespace \
  --version 2.48.0  # 替换为最新版本

2. 通过 Kubernetes Manifests 安装

直接 apply 官方维护的 YAML 清单（包含 CRD、RBAC 及 Operator Deployment）：

bash
# 安装 CRD
kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.48.0/jaeger-operator.yaml

3. 通过 Operator Lifecycle Manager (OLM) 安装

若集群已部署 OLM（如 OpenShift 内置），可通过 OperatorHub 搜索 Jaeger 并一键安装。

创建 Jaeger 实例

安装 Operator 后，通过 Jaeger 自定义资源（CR）创建实例。以下为典型场景示例：

场景 1：All-in-One 模式（测试环境）

all-in-one 模式将 Jaeger 所有组件（Agent、Collector、Query、Ingester）打包为单个 Pod，适合快速测试，不持久化数据：

yaml
# jaeger-all-in-one.yaml
apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
  name: jaeger-test
spec:
  strategy: allInOne  # 测试模式
  allInOne:
    image: jaegertracing/all-in-one:1.48  # Jaeger 镜像版本
  ingress:
    enabled: true  # 启用 Ingress 暴露 Query UI
    hosts:
      - jaeger-test.example.com  # 替换为实际域名

应用配置：

bash
kubectl apply -f jaeger-all-in-one.yaml -n observability

场景 2：Production 模式（生产环境）

production 模式采用分布式部署，组件独立部署并使用持久化存储（如 Elasticsearch），适合生产环境：

yaml
# jaeger-production.yaml
apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
  name: jaeger-prod
spec:
  strategy: production  # 生产模式
  collector:
    replicas: 2  #  collector 副本数（高可用）
    resources:
      limits:
        cpu: 1000m
        memory: 1Gi
  query:
    replicas: 2  # Query 副本数
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
  storage:
    type: elasticsearch  # 使用 Elasticsearch 存储追踪数据
    elasticsearch:
      nodeCount: 3  # Elasticsearch 节点数（若需 Operator 自动部署 ES）
      # 若使用外部 ES，替换为：
      # hosts: ["https://elasticsearch:9200"]
      # secretName: jaeger-es-secret  # 存储 ES 认证信息的 Secret 名称
  agent:
    strategy: DaemonSet  # Agent 以 DaemonSet 部署（每个节点一个实例）
  ingress:
    enabled: true
    hosts:
      - jaeger-prod.example.com

应用配置：

bash
kubectl apply -f jaeger-production.yaml -n observability

配置参数说明

Jaeger 自定义资源（CR）核心字段

环境变量配置

Jaeger Operator 自身支持通过环境变量调整行为（通过 Operator Deployment 的 env 字段配置）：

集成与扩展

存储集成（Elasticsearch 示例）

生产环境推荐使用 Elasticsearch 存储追踪数据。若已有外部 Elasticsearch 集群，通过 spec.storage.elasticsearch.hosts 和 secretName 配置：

yaml
spec:
  storage:
    type: elasticsearch
    elasticsearch:
      hosts: ["https://es-cluster:9200"]  # 外部 ES 地址
      secretName: es-credentials  # 包含 ES 用户名密码的 Secret（key 为 `username` 和 `password`）

采样策略配置

通过 spec.sampling 定义采样策略（如固定采样率、基于服务名动态调整）：

yaml
spec:
  sampling:
    options:
      default_strategy:
        type: probabilistic  # 概率采样
        param: 0.001  # 采样率（1/1000 请求）
      per_service_strategies:
        - service: "payment-service"  # 对特定服务调整采样率
          type: rateLimiting
          param: 10  # 每秒最多采样 10 个请求

安全配置（TLS）

为 Jaeger 组件间通信或外部访问启用 TLS：

yaml
spec:
  ingress:
    tls:
      - hosts: [jaeger-prod.example.com]
        secretName: jaeger-tls  # 包含 TLS 证书的 Secret（key 为 `tls.crt` 和 `tls.key`）
  collector:
    tls:
      enabled: true  # 启用 Collector 服务端 TLS（客户端需验证证书）
      secretName: collector-tls  # Collector 证书 Secret

部署示例

Helm 安装 Operator 完整示例

bash
# 添加仓库并安装 Operator（指定命名空间和版本）
helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
helm repo update
helm install jaeger-operator jaegertracing/jaeger-operator \
  --namespace observability \
  --create-namespace \
  --version 2.48.0 \
  --set watchNamespace=""  # 监控全集群（默认仅监控安装命名空间）

Production 模式 Jaeger 实例完整配置

yaml
# jaeger-prod-full.yaml
apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
  name: jaeger-prod
  namespace: observability
spec:
  strategy: production
  collector:
    replicas: 3
    resources:
      requests: {cpu: "500m", memory: "512Mi"}
      limits: {cpu: "1000m", memory: "1Gi"}
  query:
    replicas: 2
    resources:
      limits: {cpu: "500m", memory: "512Mi"}
    serviceType: ClusterIP  # 内部访问用 ClusterIP，外部通过 Ingress 暴露
  storage:
    type: elasticsearch
    elasticsearch:
      hosts: ["https://es-cluster:9200"]
      secretName: es-creds
      indexCleaner:  # 自动清理旧索引
        enabled: true
        numberOfDays: 30  # 保留 30 天数据
  agent:
    strategy: DaemonSet
    resources:
      limits: {cpu: "100m", memory: "64Mi"}
  ingress:
    enabled: true
    hosts: [jaeger.example.com]
    tls:
      - hosts: [jaeger.example.com]
        secretName: jaeger-tls
  sampling:
    options:
      default_strategy: {type: "probabilistic", param: 0.01}

查看 Jaeger 资源

部署后通过以下命令验证资源状态：

bash
# 查看 Jaeger CR 状态
kubectl get jaeger -n observability

# 查看 Jaeger 组件 Pod
kubectl get pods -n observability -l app.kubernetes.io/instance=jaeger-prod

# 查看 Ingress 地址
kubectl get ingress jaeger-prod -n observability -o jsonpath='{.status.load***.ingress[0].ip}'