Práctica: OpenTelemetry Operator y auto-instrumentación en Kubernetes con corrección

Lo que vas a aprender en este TP

• Instalar el Operator
• Declarar Collector e Instrumentation
• Instrumentar mediante anotación

Introducción #

Lo que vas a aprender en esta sección

• Instalar el Operator
• Declarar Collector e Instrumentation
• Instrumentar mediante anotación

Contexto. El equipo de plataforma quiere que todas las aplicaciones del clúster produzcan trazas sin que cada equipo modifique sus imágenes. Validas el enfoque con el Operator.

Requisitos previos: Docker, kubectl y kind  ·  Duración estimada: 50 min

Una aplicación instrumentada sin modificar la imagen, cuyos spans llegan a un Collector gestionado por el Operator.

Puesta en práctica #

Pasos guiados, con su corrección.

1. 1. Preparar el clúster

   ¿Por qué? El Operator usa webhooks de admisión cuyos certificados gestiona cert-manager.

   Crea un clúster kind, instala cert-manager y después el Operator, y espera a que estén disponibles.
   Ver la corrección

   kind create cluster --name otel
   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
   kubectl wait --for=condition=Available deploy --all -n cert-manager --timeout=180s
   kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
   kubectl wait --for=condition=Available deploy --all -n opentelemetry-operator-system --timeout=180s
   kubectl get crd | grep opentelemetry

2. 2. Declarar un Collector

   ¿Por qué? El Collector se describe como un recurso de Kubernetes: el Operator crea el Deployment, el Service y el ConfigMap.

   Crea un namespace demo y un recurso OpenTelemetryCollector en modo deployment con un receiver OTLP, k8sattributes y el exportador debug.
   Ver la corrección

   kubectl create namespace demo
   cat <<'EOF' | kubectl apply -f -
   apiVersion: opentelemetry.io/v1beta1
   kind: OpenTelemetryCollector
   metadata: { name: demo, namespace: demo }
   spec:
     mode: deployment
     config:
       receivers:
         otlp: { protocols: { grpc: { endpoint: 0.0.0.0:4317 }, http: { endpoint: 0.0.0.0:4318 } } }
       processors:
         k8sattributes: {}
         batch: {}
       exporters:
         debug: { verbosity: detailed }
       service:
         pipelines:
           traces: { receivers: [otlp], processors: [k8sattributes, batch], exporters: [debug] }
   EOF
   kubectl -n demo get pods,svc     # demo-collector

3. 3. Declarar la instrumentación

   ¿Por qué? El recurso Instrumentation centraliza exportador, propagadores y muestreo para todo un namespace.

   Crea un recurso Instrumentation que envíe en OTLP/HTTP al Collector, con los propagadores tracecontext y baggage y un muestreo del 100 %.
   Ver la corrección

   cat <<'EOF' | kubectl apply -f -
   apiVersion: opentelemetry.io/v1alpha1
   kind: Instrumentation
   metadata: { name: defaut, namespace: demo }
   spec:
     exporter: { endpoint: http://demo-collector.demo:4318 }
     propagators: [tracecontext, baggage]
     sampler: { type: parentbased_always_on }
   EOF
   kubectl -n demo get instrumentation

4. 4. Instrumentar una aplicación mediante anotación

   ¿Por qué? La anotación basta: el Operator inyecta el agente Python al arrancar el pod, sin modificar la imagen.

   Despliega una pequeña aplicación Flask en una imagen Python estándar con la anotación instrumentation.opentelemetry.io/inject-python y observa el init container y las variables OTEL_* inyectados.
   Ver la corrección

   cat <<'EOF' | kubectl apply -f -
   apiVersion: apps/v1
   kind: Deployment
   metadata: { name: catalogue, namespace: demo }
   spec:
     replicas: 1
     selector: { matchLabels: { app: catalogue } }
     template:
       metadata:
         labels: { app: catalogue }
         annotations: { instrumentation.opentelemetry.io/inject-python: "true" }
       spec:
         containers:
           - name: app
             image: python:3.12-slim
             command: ["sh", "-c"]
             args:
               - pip install flask >/dev/null && python -c "from flask import Flask; a=Flask('catalogue'); a.get('/')(lambda: 'ok'); a.run(host='0.0.0.0', port=8080)"
             ports: [{ containerPort: 8080 }]
   EOF
   kubectl -n demo rollout status deploy/catalogue --timeout=180s
   kubectl -n demo get pod -l app=catalogue -o jsonpath='{.items[0].spec.initContainers[*].name}{"\n"}'
   kubectl -n demo exec deploy/catalogue -- env | grep ^OTEL_

5. 5. Comprobar los spans

   ¿Por qué? El exportador debug muestra los spans recibidos con los atributos de Kubernetes añadidos por k8sattributes.

   Genera algunas peticiones con un port-forward y busca en los logs del Collector el span GET /, service.name y k8s.pod.name.
   Ver la corrección

   kubectl -n demo port-forward deploy/catalogue 8080:8080 &
   for i in $(seq 1 5); do curl -s localhost:8080/ ; done ; kill %1
   kubectl -n demo logs deploy/demo-collector | grep -E 'Name +: GET|service.name|k8s.pod.name' | head

6. 6. Evolucionar y limpiar

   ¿Por qué? Modificar el recurso Instrumentation solo afecta a los pods recreados: hay que reiniciar los despliegues.

   Pasa el muestreo al 10 %, reinicia el despliegue, comprueba el nuevo valor de OTEL_TRACES_SAMPLER_ARG y elimina el clúster.
   Ver la corrección

   kubectl -n demo patch instrumentation defaut --type merge -p '{"spec":{"sampler":{"type":"parentbased_traceidratio","argument":"0.1"}}}'
   kubectl -n demo rollout restart deploy/catalogue && kubectl -n demo rollout status deploy/catalogue
   kubectl -n demo exec deploy/catalogue -- env | grep SAMPLER
   kind delete cluster --name otel

Nivel de dificultad : ●●●○○ (3/5)