Unidad 5.1: Observabilidad y depuración

Introducción

Desplegó TaskBoard en Managed Kubernetes en el Módulo 3 y lo conectó a PostgreSQL, Redis, Object Storage y Kafka en el Módulo 4. Ahora está en producción y, en algún momento, presentará problemas: picos de latencia de la API, un pod entra en un ciclo de reinicios, una conexión a la base de datos expira silenciosamente o el tráfico deja de llegar a un nivel y nadie sabe por qué. Sin observabilidad integrada, está depurando a ciegas.

Esta unidad le muestra cómo instrumentar y depurar TaskBoard de forma programática en IONOS CLOUD. Enviará métricas al Monitoring Service, reenviará registros al Logging Service, auditará los cambios de infraestructura a través de Activity Logs y capturará el tráfico de red con Flow Logs. Cada herramienta cubre una capa diferente de la pila, y la unidad concluye con un flujo de trabajo de depuración de Kubernetes repetible que los integra. Es fundamental que también aprenda la restricción de IONOS CLOUD que afecta a la mayoría de los equipos: los eventos del plano de control de Kubernetes no se reenvían automáticamente a través del Logging Service, por lo que debe reenviar los registros del clúster usted mismo.

1. Métricas con el Monitoring Service

El Monitoring Service ingiere métricas a través de una canalización que usted crea mediante la API REST. Cada canalización expone un punto final de empuje HTTP que acepta métricas en formato Prometheus (Counter, Gauge, Histogram, Summary), y la visualización se realiza en una instancia administrada de Grafana aprovisionada por contrato y por región. El formato de ingesta alternativo es JSON, que debe comprimirse utilizando Snappy.

Usted crea una canalización mediante POST a /pipelines en el punto final regional. El punto final sigue la plantilla https://monitoring.<region-slug>.ionos.com, por ejemplo https://monitoring.de-txl.ionos.com/pipelines para Berlín o https://monitoring.de-fra.ionos.com/pipelines para Fráncfort. Los agentes de empuje admitidos son Prometheus, Grafana Agent, OpenTelemetry y Fluent Bit.

1.1 Creación de una canalización de métricas

Cree la canalización con un token Bearer. La respuesta devuelve la clave de ingesta por canalización en metadata.key, pero solo en el momento de la creación. Por razones de seguridad, la clave nunca se devuelve en respuestas posteriores, por lo que debe capturarla de inmediato y almacenarla en su gestor de secretos.

curl -s -X POST "https://monitoring.de-txl.ionos.com/pipelines" \
  -H "Authorization: Bearer $IONOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "properties": {
          "name": "taskboard-prod"
        }
      }'

Salida esperada (truncada):

{
  "id": "a1b2c3d4-...",
  "metadata": {
    "key": " exporter-api-key-shown-once ",
    "grafanaEndpoint": "https://a1b2c3d4-...grafana.de-txl.ionos.com"
  },
  "properties": { "name": "taskboard-prod", "status": "PROVISIONING" }
}

El patrón del host de ingesta es <id>-metrics.<id>.monitoring.<region>.ionos.com, y la ruta de envío es /api/v1/push a través del puerto saliente 443. El patrón completo de la URL de envío es <httpEndpoint>/api/v1/push.

1.2 Envío de métricas desde TaskBoard

Configure su agente para que envíe datos al punto de acceso de la canalización. Grafana Agent, Prometheus y OpenTelemetry se autentican estableciendo la cabecera APIKEY: <key>. El ejemplo de Fluent Bit utiliza en su lugar Authorization: Bearer <apiKey>. El intervalo de envío predeterminado es de 1 minuto y es configurable.

# grafana-agent.yaml - remote_write block for TaskBoard API pods
metrics:
  configs:
    - name: taskboard
      remote_write:
        - url: https://a1b2c3d4-metrics.a1b2c3d4.monitoring.de-txl.ionos.com/api/v1/push
          headers:
            APIKEY: ${MONITORING_PIPELINE_KEY}
      scrape_configs:
        - job_name: taskboard-api
          static_configs:
            - targets: ["taskboard-api:8080"]

Una vez que los datos se reciben, cree paneles de control y alertas en la instancia administrada de Grafana en la grafanaEndpoint de la respuesta de creación. Usted define las condiciones de alerta, los umbrales y las preferencias de notificación directamente en Grafana, por ejemplo, una alerta cuando la latencia de las solicitudes p95 de TaskBoard API supera un umbral durante una ventana de 5 minutos. El acceso al Monitoring Service está controlado por el privilegio de IAM denominado Access and manage Monitoring.

2. Registros centralizados con el Logging Service

El Logging Service recopila registros a través de su propio canal de procesamiento, creado con POST /pipelines en el punto de acceso regional https://logging.<region-slug>.ionos.com. Un nuevo canal de procesamiento devuelve el estado PROVISIONING y se vuelve utilizable una vez que está Ready. Las fuentes de registros admitidas son Kubernetes, Docker, Linux Systemd, HTTP (API REST JSON) y Genérico. La retención predeterminada es de 30 días, y los valores de retención permitidos son 7, 14, 30 o ilimitado. Cada canal de procesamiento permite hasta 5 flujos de registros.

curl -s -X POST "https://logging.de-txl.ionos.com/pipelines" \
  -H "Authorization: Bearer $IONOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "properties": {
          "name": "taskboard-logs",
          "logs": [
            {"source": "kubernetes", "tag": "taskboard", "protocol": "tcp", "retentionInDays": 30}
          ]
        }
      }'

Los registros son consultables en Grafana de Logging Service durante una ventana de consulta de 30 días. El acceso requiere el privilegio de IAM Access and manage Logging Service.

2.1 Reenvío de registros con Fluent Bit

Fluent Bit es el agente de registros admitido. Cada fuente de registros requiere el punto de acceso de la canalización y una clave, ambos obtenidos de la respuesta de la API REST. Para Kubernetes, instale el paquete de Fluent Bit para su distribución y luego dirija su salida de reenvío al tcpAddress de la canalización con la clave compartida.

# fluent-bit.conf - forward TaskBoard pod logs to the Logging Service
[OUTPUT]
    Name      forward
    Match     *
    Host      <tcpAddress-host>
    Port      9000
    Tag       taskboard
    tls       on
    SharedKey ${LOGGING_PIPELINE_KEY}

Tenga en cuenta que la fuente HTTP REST solo acepta registros de formato JSON, por lo que debe estructurar los registros de su aplicación como JSON cuando utilice la ruta HTTP en lugar del protocolo forward.

2.2 La restricción del plano de control de Kubernetes

Esta es la trampa específica de IONOS CLOUD. Los eventos del plano de control de Kubernetes NO fluyen automáticamente a través del Logging Service de IONOS CLOUD. Desplegar una carga de trabajo en Managed Kubernetes no le proporciona la reenvío de registros del clúster de forma gratuita. Debe configurar el reenvío de registros a nivel de clúster por separado, lo que en la práctica significa ejecutar Fluent Bit como un DaemonSet en su clúster para enviar los registros de los nodos y los pods a su pipeline.

# Excerpt: Fluent Bit DaemonSet output for an MKS cluster
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit
  namespace: logging
spec:
  template:
    spec:
      containers:
        - name: fluent-bit
          image: fluent/fluent-bit:latest
          env:
            - name: LOGGING_PIPELINE_KEY
              valueFrom:
                secretKeyRef:
                  name: logging-pipeline
                  key: shared-key

Para un reenvío integrado sin que cada producto ejecute su propia pila de ingesta, el Logging Service también ofrece Central Logging, una capacidad a nivel de contrato y por región que se activa con PUT /central (cuerpo {"properties":{"enabled":true}}). Solo los administradores de contrato, los propietarios y los usuarios con el privilegio Access and manage Logging Service pueden activarlo o desactivarlo.

3. Auditoría de cambios con Activity Logs

Cuando un incidente se origina en un cambio de configuración, Activity Logs responden a quién cambió qué y cuándo. La URL base de la API es https://api.ionos.com/activitylog/v1, y el servicio es de solo lectura por diseño: cada llamada es una GET. Registra inicios de sesión de usuarios, aprovisionamiento de recursos, cambios de configuración, acceso a datos, recuperaciones de recursos, modificaciones de recursos y eliminaciones de recursos. Cada entrada también rastrea la fuente de una acción, los recursos afectados y la cronología de eventos. Las respuestas son JSON, y la autenticación acepta Basic Authentication o un Bearer Token.

3.1 Consulta del Activity Log

Filtre por un rango de inicio y fin date para acotar la ventana de investigación. La paginación se controla con un límite que restringe el número de elementos de respuesta por página y una compensación para recorrer las páginas siguientes.

# Find all changes during the incident window
curl -s "https://api.ionos.com/activitylog/v1/contracts/${CONTRACT_NUMBER}?startDate=2026-06-04&endDate=2026-06-05&limit=50" \
  -H "Authorization: Bearer $IONOS_TOKEN"

(reemplace ${CONTRACT_NUMBER} con su número de contrato; la ruta base /activitylog/v1 sin el segmento /contracts/{contractNumber} solo devuelve información de la versión de la API, no entradas de registro.)

import requests

def find_changes(token, contract_number, start, end):
    url = f"https://api.ionos.com/activitylog/v1/contracts/{contract_number}"
    headers = {"Authorization": f"Bearer {token}"}
    offset, limit = 0, 100
    while True:
        params = {"startDate": start, "endDate": end, "limit": limit, "offset": offset}
        items = requests.get(url, headers=headers, params=params, timeout=30).json()["hits"]["hits"]
        if not items:
            break
        for entry in items:
            yield entry["_source"]
        offset += limit

El período de retención de Activity Logs es de 35 días. Para cualquier información que necesite más allá de ese plazo, descargue los datos y almacénelos en otro lugar. IONOS Cloud Object Storage es el destino recomendado explícitamente para la persistencia a largo plazo, por lo que una tarea de exportación programada hacia un bucket le proporciona una pista de auditoría que supera la ventana integrada.

4. Depuración de red con Flow Logs

Cuando se interrumpe la conectividad entre los niveles de TaskBoard y los registros de la aplicación no muestran actividad, el problema suele encontrarse en la capa de red: una regla de firewall, un vacío en la enrutación o una NIC configurada de forma incorrecta. Flow Logs capturan el tráfico para que pueda ver exactamente qué se está aceptando y rechazando. Los recursos compatibles son la NIC de la VM, Managed Network Load Balancer, Managed Application Load Balancer y Managed NAT Gateway. Las acciones de captura son Rejected, Accepted o Any, y las direcciones de captura son Ingress, Egress o Bidirectional. Tanto IPv4 como IPv6 son compatibles.

Flow Logs publican en un contenedor de IONOS Cloud Object Storage como .log.gz (texto comprimido con gzip), con rotación cada 10 minutos. Dos restricciones son importantes para la automatización: la configuración es inmutable después de la creación, y existe un solo flow log por recurso. Para cambiar una configuración, debe eliminarlo y volver a crearlo. La creación de flow logs requiere el privilegio de grupo DCD Create Flow logs.

4.1 Lectura de registros de Flow Logs

Cada registro tiene un formato fijo e inmutable (versión 2). Los campos más útiles para la depuración son srcaddr, dstaddr, srcport, dstport, protocol y action, donde action es ACCEPT (permitido por el firewall) o REJECT (bloqueado por el firewall). Una ráfaga de entradas REJECT en el puerto que utiliza su aplicación indica directamente una regla de NSG.

import boto3, gzip

# Flow logs land in an Object Storage bucket as .log.gz objects
s3 = boto3.client("s3",
    endpoint_url="https://s3-eu-central-1.ionoscloud.com",
    aws_access_key_id=ACCESS_KEY,
    aws_secret_access_key=SECRET_KEY)

obj = s3.get_object(Bucket="taskboard-flowlogs", Key="2026/06/05/flow-0001.log.gz")
for line in gzip.decompress(obj["Body"].read()).decode().splitlines():
    f = line.split()
    # version account-id interface-id srcaddr dstaddr srcport dstport protocol packets bytes start end action log-status
    if f and f[-2] == "REJECT":
        print("BLOCKED:", f[3], "->", f[4], "port", f[6])

El campo log-status es OK para un intervalo normal o SKIPDATA cuando se omitieron registros durante el intervalo. Ver SKIPDATA significa que no está obteniendo la imagen completa de esa ventana.

5. El flujo de trabajo de depuración de Kubernetes

La mayoría de los incidentes de producción de TaskBoard se manifiestan primero en Kubernetes. Trabaje las capas en orden, en lugar de saltar directamente a las herramientas de la plataforma, porque la señal más económica se encuentra más cerca del pod.

5.1 Ruta de escalado

Comience con kubectl y escale a la observabilidad de la plataforma solo cuando la señal dentro del clúster se agote:

# 1. What is the pod actually doing?
kubectl get pods -n taskboard
kubectl logs -n taskboard deploy/taskboard-api --tail=100

# 2. Why won't it start or stay healthy?
kubectl describe pod -n taskboard <pod-name>
kubectl get events -n taskboard --sort-by=.lastTimestamp

# 3. Is it a resource or latency problem? -> Monitoring Service metrics in Grafana
# 4. Need historical/aggregated logs across pods? -> Logging Service search

Recuerde la restricción de la sección 2: kubectl logs le muestra la salida en vivo del contenedor, pero no la persiste y los eventos del plano de control no llegan al Logging Service por sí solos. La búsqueda del Logging Service solo es útil si su DaemonSet de Fluent Bit ya está reenviando. Configure la observabilidad antes de la incidencia, no durante ella.

5.2 Verificaciones de estado

Las sondas de viabilidad y de preparación son su primera línea de recuperación automatizada. Una sonda de preparación que falla elimina el pod de los puntos de finalización del Service, de modo que el tráfico deja de fluir hacia una instancia defectuosa, mientras que una sonda de viabilidad reinicia un contenedor bloqueado.

# TaskBoard API deployment probes
livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  initialDelaySeconds: 10
  periodSeconds: 15
readinessProbe:
  httpGet: { path: /readyz, port: 8080 }
  initialDelaySeconds: 5
  periodSeconds: 10

Dado que Managed Application Load Balancer se aprovisiona de forma independiente de sus manifiestos de K8s, configure su verificación de estado para que coincida con la misma ruta /readyz, de modo que el ALB y Kubernetes estén de acuerdo sobre qué backends están en buen estado.

Tarjeta rápida de referencia de la API

Puntos finales clave para el tema de esta unidad:

URL base (CloudAPI): https://api.ionos.com/cloudapi/v6 Autenticación: Authorization: Bearer <token> (el envío de métricas utiliza APIKEY: <key>)

Laboratorio de código

Objetivo: Configurar métricas y registro centralizado para TaskBoard, y luego depurar una interrupción de conectividad simulada utilizando Activity Logs y Flow Logs.

Requisitos previos:

• Cuenta de IONOS CLOUD con token de API (IONOS_TOKEN exportado)
• TaskBoard en ejecución en Managed Kubernetes (Unidad 3.2)
• kubectl configurado para su clúster de MKS
• Un bucket de Object Storage y una Access Key + Secret Key para Flow Logs

Paso 1: Crear la canalización de monitorización

curl -s -X POST "https://monitoring.de-txl.ionos.com/pipelines" \
  -H "Authorization: Bearer $IONOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"properties":{"name":"taskboard-prod"}}' | tee pipeline.json

Salida esperada:

{"id":"...","metadata":{"key":"...","grafanaEndpoint":"https://...grafana.de-txl.ionos.com"},...}

Paso 2: Capturar la clave de ingesta

export MON_KEY=$(python3 -c "import json;print(json.load(open('pipeline.json'))['metadata']['key'])")
echo "Stored key length: ${#MON_KEY}"

Salida esperada:

Stored key length: 44

Paso 3: Crear la canalización de registros

curl -s -X POST "https://logging.de-txl.ionos.com/pipelines" \
  -H "Authorization: Bearer $IONOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"properties":{"name":"taskboard-logs","logs":[{"source":"kubernetes","tag":"taskboard","protocol":"tcp","retentionInDays":30}]}}'

Salida esperada:

{"id":"...","properties":{"name":"taskboard-logs","status":"PROVISIONING"}}

Paso 4: Despliegue del DaemonSet de Fluent Bit para reenviar los registros del clúster (los registros del plano de control no llegarán de otra manera)

kubectl create namespace logging
kubectl create secret generic logging-pipeline -n logging --from-literal=shared-key="$LOGGING_PIPELINE_KEY"
kubectl apply -f fluent-bit-daemonset.yaml

Salida esperada:

daemonset.apps/fluent-bit created

Paso 5: Simular una interrupción agregando una regla de NSG que bloquee el puerto de la capa de aplicación, y luego observar el fallo del tráfico

kubectl get pods -n taskboard   # pods Running, but requests time out

Paso 6: Buscar el cambio en Activity Logs

curl -s "https://api.ionos.com/activitylog/v1/contracts/${CONTRACT_NUMBER}?startDate=2026-06-05&endDate=2026-06-05&limit=20" \
  -H "Authorization: Bearer $IONOS_TOKEN"

Salida esperada:

{"hits":{"total":1,"hits":[{"_source":{"action":"configuration changes","resource":"firewallrule/...","user":"...","time":"..."}}]}}

Paso 7: Confirmar en la capa de red con Flow Logs

python3 read_flowlogs.py | grep BLOCKED

Salida esperada:

BLOCKED: 10.0.2.5 -> 10.0.3.7 port 8080

Lista de verificación:

• [ ] Se ha creado la canalización de monitorización y se ha capturado la clave antes de cualquier segunda llamada a la API
• [ ] La canalización de registros alcanza Ready y el DaemonSet de Fluent Bit está en ejecución
• [ ] La consulta de Activity Logs devuelve el cambio de configuración problemático
• [ ] Flow Logs muestra registros de REJECT en el puerto bloqueado

Limpieza:

curl -s -X DELETE "https://monitoring.de-txl.ionos.com/pipelines/$MON_ID" -H "Authorization: Bearer $IONOS_TOKEN"
curl -s -X DELETE "https://logging.de-txl.ionos.com/pipelines/$LOG_ID" -H "Authorization: Bearer $IONOS_TOKEN"
kubectl delete namespace logging

Errores comunes

Errores de desarrollo a evitar con la observabilidad en IONOS CLOUD:

1. Esperar registros de Kubernetes sin reenvío

   • Problema: Abre Grafana del Logging Service después de desplegar en MKS y no ve registros del clúster ni del plano de control.
   • Por qué ocurre: Los eventos del plano de control de Kubernetes no fluyen automáticamente a través del Logging Service de IONOS CLOUD. La plataforma no los envía por usted.
   • Solución: Ejecute Fluent Bit como un DaemonSet (o configure el registro centralizado) y diríjalo al tcpAddress de su canal de registros con la clave compartida antes de necesitar los registros.

2. Perder la clave del canal de métricas

   • Problema: Su agente recibe 401/403 al enviar y no puede encontrar la clave para corregirlo.
   • Por qué ocurre: La clave de ingesta se devuelve solo una vez, en metadata.key al crear el canal, y nunca aparece en respuestas posteriores por razones de seguridad.
   • Solución: Capture la clave en su almacén de secretos en el momento de la creación. Si se pierde, no puede recuperarla; provisione un canal nuevo o rote la clave.

3. Intentar editar un Flow Log in situ

   • Problema: Actualiza la dirección de captura de un Flow Log a través de la API y el cambio no surte efecto.
   • Por qué ocurre: La configuración de un Flow Log es inmutable después de su creación, y existe un solo registro de flujo por recurso.
   • Solución: Elimine el registro de flujo existente y cree uno nuevo con la configuración deseada. Codifique este patrón de eliminar y luego crear en su Terraform o automatización, en lugar de esperar una actualización in situ.

Resumen

Ahora puede instrumentar TaskBoard de extremo a extremo en IONOS CLOUD. Las métricas fluyen hacia una canalización de Monitoring Service y se representan en Grafana administrado con alertas; los registros fluyen hacia una canalización de Logging Service a través de Fluent Bit; los cambios de infraestructura son auditables a través de la API de Activity Logs de solo lectura; y las fallas a nivel de red son visibles en Flow Logs escritos en Object Storage. Con sondas y comprobaciones de estado de ALB correspondientes implementadas, las instancias dañadas se eliminan de la rotación automáticamente. Lo más importante es que conoce la restricción de IONOS CLOUD que afecta a los equipos en producción: los registros del clúster y los eventos del plano de control deben ser reenviados por usted, no por la plataforma.

Puntos clave:

• Las canalizaciones de monitorización aceptan métricas en formato Prometheus en /api/v1/push; la clave de ingesta se muestra solo una vez en la creación
• Las canalizaciones de registros admiten orígenes de Kubernetes, Docker, Systemd, HTTP y Genérico, con retención de 7/14/30/ilimitada; Fluent Bit es el agente admitido
• Los eventos del plano de control de Kubernetes NO fluyen automáticamente a través de Logging Service; reenvíelos usted mismo con un DaemonSet de Fluent Bit o Central Logging
• Activity Logs es de solo lectura (solo GET), filtrable por fecha, con retención de 35 días; exporte a Object Storage para trazas de auditoría más largas
• Flow Logs capturan ACCEPT/REJECT por NIC, NLB, ALB y NAT Gateway en objetos de .log.gz; la configuración es inmutable y una por recurso

Terminología importante:

• Canalización de métricas: Una instancia de Monitoring Service creada mediante POST /pipelines que expone un punto final de empuje HTTP para métricas en formato Prometheus.
• Clave de ingesta: La credencial por canalización devuelta una vez en metadata.key; los agentes la envían como la cabecera APIKEY (o Bearer para Fluent Bit).
• Central Logging: Un conmutador a nivel de contrato y por región (PUT /central) que permite a los productos integrados reenviar registros a Logging Service sin que cada uno ejecute su propia ingesta.
• Activity Logs: La API de auditoría de solo lectura en /activitylog/v1 que registra quién cambió qué recurso y cuándo, con retención de 35 días.
• Flow Logs: Capturas de red inmutables, por recurso, publicadas como texto gzip en Object Storage, utilizadas para ver el tráfico aceptado y rechazado.

Próximos pasos

Siga aprendiendo: Unidad 5.2: Automatización de seguridad

Temas relacionados:

• Unidad 3.2: Despliegue y operaciones de Kubernetes
• Unidad 4.2: Integración de Object Storage