OpenTelemetry の Helm チャートは、Collector を DaemonSet、Deployment、StatefulSet としてデプロイし、妥当なデフォルトの設定を生成します。values.yaml ファイルだけで完全にカスタマイズできるため、GitOps に自然に適合します。このガイドでは、チャートをインストールし、一般的なニーズに preset を使い、Collector の設定を上書きする方法を説明します。

インストールする

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

helm install my-opentelemetry-collector open-telemetry/opentelemetry-collector \
  --namespace observability --create-namespace \
  --set image.repository="otel/opentelemetry-collector-k8s" \
  --set mode=daemonset

2 つの設定が必須です。

• mode は、daemonset、deployment、statefulset のいずれかである必要があります。デフォルトはありません。
• image.repository は、ディストリビューションを選びます。Kubernetes のディストリビューション（otel/opentelemetry-collector-k8s）には、preset が必要とするコンポーネントが含まれています。それ以外のコンポーネントが必要な場合は、contrib イメージを使います。

--version でチャートを、image.tag でイメージを固定し、レビュー可能にするため、--set フラグではなく values ファイルにすべてを保持します。

# values.yaml
mode: daemonset
image:
  repository: otel/opentelemetry-collector-k8s
  tag: "0.163.0"   # テスト済みのバージョンに固定する

helm install otel-agent open-telemetry/opentelemetry-collector \
  -n observability --create-namespace -f values.yaml --version <chart-version>

どの仕事にどのモードか

• daemonset：ノードごとに 1 つの Pod。ログの収集、kubelet のメトリクス、ホストのメトリクスに使います。これらはローカルのノードにしか存在しないからです。
• deployment：スケーラブルなサービス。アプリケーションが送信するゲートウェイに使います。
• statefulset：安定したストレージや ID が必要な場合。たとえば、永続キューや Target Allocator のパターンです。
• クラスターごとに 1 回だけ収集すべきデータ（クラスターのメトリクス、Kubernetes のイベント）には、単一のレプリカを持つ Deployment または StatefulSet を使います。そうしないと、重複が生じます。

preset

preset は、一般的な設定を有効にし、それらが必要とする receiver、processor、RBAC、ボリュームのマウントを含みます。

# エージェント：すべてのノードで、ログ、ホストと kubelet のメトリクス、Pod のメタデータ
mode: daemonset
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubeletMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true

# クラスター全体のメトリクスとイベントを、1 回だけ
mode: deployment
replicaCount: 1
presets:
  clusterMetrics:
    enabled: true
  kubernetesEvents:
    enabled: true

preset には、そのコンポーネントを含む Collector のイメージが必要なので、Kubernetes または contrib のイメージを使ってください。出発点として扱ってください。珍しいニーズには、コンポーネントとその RBAC やボリュームを自分で設定します。すべてのオプションは、チャートの values.yaml に列挙されています。

Collector の設定を上書きする

config キーは、チャートのデフォルトの Collector の設定の上にマージされます。必要なものを追加または変更します。

mode: deployment
replicaCount: 2

config:
  processors:
    memory_limiter:
      check_interval: 1s
      limit_percentage: 80
      spike_limit_percentage: 20
  exporters:
    otlp/tempo:
      endpoint: tempo.observability.svc.cluster.local:4317
      tls:
        insecure: true
  service:
    pipelines:
      traces:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [otlp/tempo]

つまずきやすいルール：

• デフォルトの exporter は debug です。 上のように、使用する各パイプラインで置き換えます。
• デフォルトのコンポーネントを null に設定すると、削除されます： config.receivers.zipkin: null。
• リストは置き換えられ、マージされません。 パイプラインを変更する場合は、保持したいデフォルトを含めて、すべてのコンポーネントを列挙します。
• 使わないポートを無効にして、Service をすっきりさせます。たとえば ports.jaeger-compact.enabled: false。
• ログと debug exporter： includeCollectorLogs: true で logsCollection を有効にし、ログのパイプラインに debug exporter を残すと、Collector が自分のログを読み取って、それをフィードバックし、ログの爆発を引き起こす可能性があります。先に実際の exporter に切り替えてください。

簡略化した、OTLP のみのゲートウェイ：

config:
  receivers:
    jaeger: null
    prometheus: null
    zipkin: null
  service:
    pipelines:
      traces:
        receivers: [otlp]
        exporters: [otlp/tempo]
      metrics: null
      logs: null
ports:
  jaeger-compact:
    enabled: false
  jaeger-thrift:
    enabled: false
  jaeger-grpc:
    enabled: false
  zipkin:
    enabled: false

シークレットと環境変数

認証情報を環境変数で注入し、Collector の設定では ${env:NAME} で参照します。

extraEnvs:
  - name: BACKEND_TOKEN
    valueFrom:
      secretKeyRef:
        name: otel-backend
        key: token

config:
  exporters:
    otlphttp/backend:
      endpoint: https://otlp.backend.example.com
      headers:
        authorization: Bearer ${env:BACKEND_TOKEN}

Secret を、プレーンな形で Git に置かないでください。SOPS で暗号化するか、シークレットマネージャーから同期します。

Flux でデプロイする

Flux を使う場合、チャートは HelmRelease です。

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: open-telemetry
  namespace: flux-system
spec:
  interval: 1h
  url: https://open-telemetry.github.io/opentelemetry-helm-charts
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: otel-agent
  namespace: observability
spec:
  interval: 10m
  chart:
    spec:
      chart: opentelemetry-collector
      version: "<chart-version>"
      sourceRef:
        kind: HelmRepository
        name: open-telemetry
        namespace: flux-system
  values:
    mode: daemonset
    image:
      repository: otel/opentelemetry-collector-k8s
    presets:
      kubernetesAttributes:
        enabled: true

Git での values の変更は、Flux を通じてロールアウトされます。Flux のシリーズが、remediation やドリフト検出などの HelmRelease のオプションを説明しています。

確認する

kubectl get pods -n observability
kubectl logs -n observability daemonset/otel-agent-opentelemetry-collector | tail -n 20
kubectl port-forward -n observability svc/otel-agent-opentelemetry-collector 13133:13133 &
curl -s http://localhost:13133

Pod と Service の名前は、リリース名に従います。Pod がクラッシュループする場合、ログは通常、不明なコンポーネントや無効なキーを示します。その場合、設定が参照するコンポーネントがイメージに含まれていないか、値が間違ったキーの下にインデントされています。