El chart de Helm de OpenTelemetry despliega el Collector como un DaemonSet, un Deployment o un StatefulSet, y genera una configuración predeterminada razonable. Lo personalizas por completo mediante un archivo values.yaml, lo que lo hace encajar de forma natural con GitOps. Esta guía lo instala, usa presets para necesidades comunes y muestra cómo sobrescribir la configuración del Collector.

Instala

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

Se requieren dos ajustes:

• mode debe ser daemonset, deployment o statefulset. No hay valor predeterminado.
• image.repository elige la distribución. La distribución de Kubernetes (otel/opentelemetry-collector-k8s) incluye los componentes que necesitan los presets. Usa la imagen contrib si necesitas componentes fuera de ella.

Fija el chart con --version y la imagen con image.tag, y mantén todo en un archivo de valores en lugar de flags --set, para que sea revisable:

# values.yaml
mode: daemonset
image:
  repository: otel/opentelemetry-collector-k8s
  tag: "0.163.0"   # fija una versión que hayas probado

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

Qué modo para qué trabajo

• daemonset: un pod por nodo. Úsalo para recopilación de logs, métricas del kubelet y métricas de host, porque eso solo existe en el nodo local.
• deployment: un servicio escalable. Úsalo para un gateway al que envían las aplicaciones.
• statefulset: cuando necesitas almacenamiento o identidad estables, por ejemplo una cola persistente o el patrón del Target Allocator.
• Para datos que deben recopilarse una sola vez por clúster (métricas del clúster, eventos de Kubernetes), usa un Deployment o StatefulSet con una sola réplica, o tendrás duplicados.

Presets

Los presets activan configuraciones comunes, incluidos los receivers, processors, RBAC y montajes de volúmenes que necesitan:

# Agente: logs, métricas de host y kubelet, y metadatos de pods en cada nodo
mode: daemonset
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubeletMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true

# Métricas y eventos de todo el clúster, una sola vez
mode: deployment
replicaCount: 1
presets:
  clusterMetrics:
    enabled: true
  kubernetesEvents:
    enabled: true

Los presets necesitan una imagen del Collector que contenga sus componentes, así que usa la imagen de Kubernetes o contrib. Trátalos como un punto de partida: para necesidades inusuales, configura tú mismo los componentes y su RBAC y volúmenes. Todas las opciones están listadas en el values.yaml del chart.

Sobrescribe la configuración del Collector

La clave config se fusiona sobre la configuración predeterminada del Collector del chart. Añade o cambia lo que necesites:

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]

Reglas que hacen tropezar a la gente:

• El exporter predeterminado es debug. Reemplázalo en cada pipeline que uses, como arriba.
• Definir un componente predeterminado como null lo elimina: config.receivers.zipkin: null.
• Las listas se reemplazan, no se fusionan. Cuando cambias un pipeline, lista todos sus componentes, incluidos los predeterminados que quieras conservar.
• Desactiva los puertos sin usar para mantener ordenado el Service, por ejemplo ports.jaeger-compact.enabled: false.
• Logs y el exporter debug: si habilitas logsCollection con includeCollectorLogs: true y mantienes el exporter debug en el pipeline de logs, el Collector puede leer sus propios logs y realimentarlos, causando una explosión de logs. Cambia primero a un exporter real.

Un gateway solo OTLP recortado:

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

Secretos y variables de entorno

Inyecta credenciales con variables de entorno y haz referencia a ellas en la configuración del Collector con ${env:NOMBRE}:

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}

Mantén el Secret fuera de Git en forma de texto plano: cífralo con SOPS o sincronízalo desde un gestor de secretos.

Despliega con Flux

Si usas Flux, el chart es un 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

Un cambio en los valores en Git se despliega entonces mediante Flux. La serie de Flux cubre opciones de HelmRelease como remediation y la detección de desviaciones.

Verifica

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

Los nombres de los Pods y Services siguen el nombre de tu release. Si un pod entra en crash-loop, el log suele nombrar el componente desconocido o la clave inválida. En ese caso, la imagen no contiene un componente que tu configuración referencia, o un valor se indentó bajo la clave equivocada.