본문으로 건너뛰기

OpenTelemetry Operator

OpenTelemetry Operator는 Kubernetes 환경에서 OpenTelemetryCollector CRD를 통해 OpenTelemetry Collector 인스턴스를 선언적으로 관리하는 쿠버네티스 오퍼레이터입니다. Lumie 인프라에서는 Target Allocator 기능을 통해 ServiceMonitor 기반의 스크래핑 대상을 분산 처리하는 역할을 담당합니다.

배포 구성​

  • 네임스페이스: opentelemetry-operator
  • 차트: opentelemetry-operator v0.102.0
  • 이미지: zot.lumie-infra.com/open-telemetry/opentelemetry-operator/opentelemetry-operator:0.141.0
  • ArgoCD Sync Wave: 0 (다른 컴포넌트보다 먼저 배포)

관리하는 이미지​

오퍼레이터가 생성하는 Collector 및 Target Allocator 파드에 사용되는 기본 이미지:

컴포넌트이미지
Collector (기본값)zot.lumie-infra.com/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.144.0
Target Allocatorzot.lumie-infra.com/open-telemetry/opentelemetry-operator/target-allocator:0.141.0
Operator 자체zot.lumie-infra.com/open-telemetry/opentelemetry-operator/opentelemetry-operator:0.141.0

아키텍처​

오퍼레이터 설정​

기본 구성​

fullnameOverride: otel-operator

manager:
  image:
    repository: zot.lumie-infra.com/open-telemetry/opentelemetry-operator/opentelemetry-operator
    tag: "0.141.0"
  collectorImage:
    repository: zot.lumie-infra.com/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib
    tag: "0.144.0"
  targetAllocatorImage:
    repository: zot.lumie-infra.com/open-telemetry/opentelemetry-operator/target-allocator
    tag: "0.141.0"
  resources:
    requests:
      cpu: 15m
      memory: 100Mi
    limits:
      memory: 100Mi
  env:
    ENABLE_WEBHOOKS: "true"

웹훅 인증서​

cert-manager 없이 오퍼레이터가 자체 서명 인증서를 생성합니다. 내부 Kubernetes 서비스 DNS 이름에는 외부 인증 기관(Let's Encrypt 등)이 인증서를 발급할 수 없기 때문입니다:

admissionWebhooks:
  certManager:
    enabled: false

자동 계측 웹훅 범위 제한​

파드 자동 계측(Auto-Instrumentation) 웹훅은 opentelemetry-auto-instrumentation: "enabled" 라벨이 있는 네임스페이스에만 적용됩니다. 현재 해당 라벨을 가진 네임스페이스가 없으므로 자동 계측은 비활성화 상태입니다:

admissionWebhooks:
  namespaceSelector:
    matchLabels:
      opentelemetry-auto-instrumentation: "enabled"

RBAC Proxy 비활성화​

kubeRBACProxy:
  enabled: false

ServiceMonitor​

오퍼레이터 자체 메트릭도 Prometheus로 수집됩니다:

manager:
  serviceMonitor:
    enabled: true
    extraLabels:
      release: prometheus

ArgoCD 동기화 순서​

OpenTelemetry Operator는 OpenTelemetryCollector CRD를 등록하므로, 이 CRD를 사용하는 OpenTelemetry Collector보다 먼저 배포되어야 합니다. ArgoCD sync-wave 0으로 설정하여 다른 리소스보다 우선 배포됩니다:

annotations:
  argocd.argoproj.io/sync-wave: "0"

CRD 변경 무시 설정​

ignoreDifferences:
  - group: apiextensions.k8s.io
    kind: CustomResourceDefinition
    jsonPointers:
      - /spec/conversion/webhook/clientConfig/caBundle
      - /spec/versions

CRD의 caBundle은 런타임에 오퍼레이터가 주입하며, 버전 목록은 업그레이드 과정에서 변경될 수 있으므로 ArgoCD가 이를 drift로 감지하지 않도록 무시합니다.

ServerSideApply 활성화​

syncOptions:
  - ServerSideApply=true

CRD 크기가 크기 때문에 일반적인 apply 방식 대신 Server-Side Apply를 사용합니다.

OpenTelemetryCollector CR 예시​

오퍼레이터가 관리하는 Collector 인스턴스는 별도 네임스페이스(opentelemetry)에 OpenTelemetryCollector CR로 정의됩니다. 자세한 설정은 OpenTelemetry 구성 문서를 참조하세요.

문제 해결​

오퍼레이터 상태 확인​

# 오퍼레이터 파드 상태 확인
kubectl get pods -n opentelemetry-operator

# 오퍼레이터 로그 확인
kubectl logs -n opentelemetry-operator deploy/otel-operator

# 관리 중인 OpenTelemetryCollector CR 확인
kubectl get otelcol -A

웹훅 인증서 문제​

# 웹훅 설정 확인
kubectl get mutatingwebhookconfigurations | grep otel
kubectl get validatingwebhookconfigurations | grep otel

# 인증서 상태 확인
kubectl get secret -n opentelemetry-operator | grep webhook

CRD 미설치 오류​

# CRD 목록 확인
kubectl get crd | grep opentelemetry

# 필요한 CRD 확인
kubectl get crd opentelemetrycollectors.opentelemetry.io
kubectl get crd instrumentations.opentelemetry.io

관련 문서​