Unidad 5.1: Observabilidad y depuración

Introducción

Usted envió TaskBoard a Managed Kubernetes en el Módulo 3 y lo conectó a PostgreSQL, Redis, Object Storage y Kafka en el Módulo 4. Ahora está ejecutándose en producción, y en algún momento se comportará mal: se producen picos de latencia en API, un pod se bloquea en un bucle de fallo, una conexión de base de datos se agota silenciosamente o el tráfico deja de llegar a un nivel y nadie sabe por qué. Sin observabilidad integrada, usted está depurando a ciegas.

Esta unidad le muestra cómo instrumentar y depurar TaskBoard de forma programática en IONOS Cloud. Usted enviará métricas a Monitoring Service, enviará registros a 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 termina con un flujo de depuración repetible de Kubernetes que los une. Críticamente, usted también aprenderá la restricción de IONOS que atrapa a la mayoría de los equipos: los eventos del plano de control de Kubernetes no fluyen a través de Logging Service automáticamente, por lo que usted debe enviar los registros de Cluster usted mismo.

1. Métricas con el Monitoring Service

El Monitoring Service ingiere métricas a través de una tubería que usted crea a través de la REST API. Cada tubería expone un punto de terminación de HTTP que acepta métricas en formato Prometheus (Contador, Medidor, Histograma, Resumen), y la visualización se produce en una instancia de Grafana administrada provisionada por contrato y por región. El formato de ingesta alternativo es JSON, que debe estar comprimido utilizando Snappy.

Usted crea una tubería conectándose a /pipelines en el punto de terminación regional. El punto de terminación sigue el modelo 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, Agente de Grafana, OpenTelemetry y Fluent Bit.

1.1 Creación de una tubería de métricas

Cree la tubería con un token Bearer. La respuesta devuelve la clave de ingesta por tubería en metadata.key, pero solo en el momento de la creación. Por razones de seguridad, la clave nunca se devuelve en respuestas posteriores, así que caṕtúrela de inmediato y guárdela en su administrador 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 de host de ingesta es <id>-metrics.<id>.monitoring.<region>.ionos.com, y la ruta de empuje es /api/v1/push sobre el puerto de salida 443. El patrón de URL de empuje completo es <httpEndpoint>/api/v1/push.

1.2 Empujar métricas desde TaskBoard

Configure su agente para empujar a la tubería de punto de terminación. El Agente de Grafana, Prometheus y OpenTelemetry autenticán estableciendo el encabezado APIKEY: <key>. El ejemplo de Fluent Bit utiliza Authorization: Bearer <apiKey> en su lugar. El intervalo de empuje 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 aterricen, cree paneles y alertas en la instancia de Grafana administrada en la grafanaEndpoint de la respuesta de creación. Usted define las condiciones de alerta, umbrales y preferencias de notificación directamente en Grafana, por ejemplo, una alerta cuando la latencia de la solicitud p95 de TaskBoard API excede un umbral durante una ventana de 5 minutos. El acceso al Monitoring Service está controlado por el privilegio IAM con el nombre Access and manage Monitoring.

2. Registros centralizados con el Logging Service

El Logging Service recopila registros a través de su propia canalización, creada con POST /pipelines en el punto de conexión regional https://logging.<region-slug>.ionos.com. Una nueva canalización devuelve el estado PROVISIONING y se vuelve utilizable una vez que esté Ready. Las fuentes de registro admitidas son Kubernetes, Docker, Linux Systemd, HTTP (JSON REST API), 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 canalización permite hasta 5 flujos de registro.

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 se pueden consultar en el Logging Service Grafana durante una ventana de consulta de 30 días. El acceso requiere el privilegio Access and manage Logging Service de IAM.

2.1 Envío de registros con Fluent Bit

Fluent Bit es el agente de registro admitido. Cada fuente de registro requiere el punto de conexión de la canalización y una clave, ambos obtenidos de la respuesta REST API. Para Kubernetes, instale el paquete Fluent Bit para su distribución, luego apunte su salida de enví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 de registro HTTP REST solo acepta registros de registro con formato JSON, por lo que debe estructurar los registros de su aplicación como JSON cuando utilice el camino HTTP en lugar del protocolo de envío.

2.2 La restricción del plano de control de Kubernetes

Esta es la trampa específica de IONOS. Los eventos del plano de control de Kubernetes NO fluyen a través del Logging Service de IONOS automáticamente. Implementar un Workload en Managed Kubernetes no le da el envío de registro Cluster de forma gratuita. Debe configurar el envío de registro de nivel Cluster por separado, lo que en la práctica significa ejecutar Fluent Bit como un DaemonSet en su Cluster para enviar registros Node y de pod a su canalización.

# 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 el envío integrado sin que cada producto ejecute su propia pila de ingesta, el Logging Service también ofrece Registro centralizado, una capacidad de nivel de contrato, por región, activada con PUT /central (cuerpo {"properties":{"enabled":true}}). Solo los administradores de contrato, propietarios y usuarios con el privilegio Access and manage Logging Service pueden activar o desactivar esta función.

3. Auditoría de cambios con Activity Logs

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

3.1 Consulta del registro de actividad

Filtre por un rango de inicio y fin de date para delimitar una ventana de investigación. La paginación se controla con un límite que limita el número de elementos de respuesta por página y un desplazamiento para avanzar por 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 segmento /contracts/{contractNumber} solo devuelve información de versión de 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 para Activity Logs es de 35 días. Para cualquier cosa que necesite más allá de eso, descargue los datos y guárdelos en otro lugar. IONOS Cloud Object Storage es el destino explícitamente recomendado para la persistencia a largo plazo, por lo que un trabajo de exportación programado en un bucket le da un registro de auditoría que sobrevive a 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 están en silencio, el problema suele estar en la capa de red: una regla de Firewall, un hueco de enrutamiento o una NIC mal configurada. Flow Logs capturan el tráfico para que pueda ver exactamente qué se acepta y qué se rechaza. Los recursos admitidos son la NIC de VM, Managed Network Load Balancer, Managed Application Load Balancer y Managed NAT Gateway. Las acciones de captura son Rechazadas, Aceptadas o Cualquiera, y las direcciones de captura son de Entrada, Salida o Bidireccional. Tanto IPv4 como IPv6 son compatibles.

Flow Logs publican en un bucket de IONOS Cloud Object Storage como .log.gz (texto comprimido con gzip), rotado cada 10 minutos. Dos restricciones son importantes para la automatización: la configuración es inmutable después de la creación, y hay un registro de flujo por recurso. Para cambiar una configuración, es necesario eliminarla y recrearla. Crear Flow Logs requiere el privilegio de grupo Create Flow logs DCD.

4.1 Lectura de registros de flujo

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 Firewall) o REJECT (bloqueado por Firewall). Una ráfaga de entradas REJECT en el puerto que utiliza su aplicación apunta directamente a 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 saltaron registros durante el intervalo. Ver SKIPDATA significa que no está obteniendo la imagen completa para esa ventana.

5. El flujo de depuración de Kubernetes

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

5.1 Camino de escalada

Comience con kubectl y escále a la observabilidad de la plataforma solo cuando la señal dentro de Cluster 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 de contenedor en vivo, pero no persiste y los eventos del control de plano no llegan a Logging Service por sí solos. La búsqueda de Logging Service solo es útil si su DaemonSet de Fluent Bit ya está reenviando. Conecte la observabilidad antes del incidente, no durante él.

5.2 Comprobaciones de estado

Las sondas de estado y 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 conexión del Servicio, por lo que el tráfico deja de fluir a una instancia rota, mientras que una sonda de estado reinicia un contenedor colgado.

# 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 provisiona por separado de sus manifiestos de K8s, configure su comprobación de estado para que coincida con la misma ruta /readyz, para que el ALB y Kubernetes estén de acuerdo en cuáles son los backends saludables.

API Tarjeta de referencia rápida

Puntos de conexión clave para el tema de esta unidad:

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

Laboratorio de código

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

Requisitos previos:

• Cuenta de IONOS Cloud con token API (IONOS_TOKEN exportado)
• TaskBoard ejecutándose en Managed Kubernetes (Unidad 3.2)
• kubectl configurado contra su MKS Cluster
• Un cubo Object Storage y 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

No hay texto para traducir. Por favor, proporcione el texto que desea traducir.

{"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}"

No hay texto para traducir. Por favor, proporcione el texto técnico que desea que traduzca.

Stored key length: 44

Paso 3: Crear la canalización de registro

Para crear la canalización de registro, usted debe seguir los pasos a continuación. La canalización de registro es un componente crítico de la infraestructura escalable, ya que permite la monitorización y el análisis de los registros de la aplicación. Esto es especialmente importante en entornos de desarrollo y pruebas, donde la capacidad de depuración y análisis es fundamental.

La canalización de registro se compone de varios componentes, incluyendo la recopilación de registros, el procesamiento de registros y el almacenamiento de registros. Cada componente juega un papel crucial en la canalización de registro, y su configuración correcta es esencial para garantizar la alta disponibilidad y la escalabilidad de la infraestructura.

Al crear la canalización de registro, usted debe considerar factores como la cantidad de datos que se van a procesar, el tipo de datos que se van a almacenar y los requisitos de seguridad y cumplimiento normativo. La elección del almacenamiento de datos adecuado, como el Object Storage o el Block Storage, es fundamental para garantizar la eficiencia y la escalabilidad de la canalización de registro.

Además, la autenticación y la autorización son aspectos críticos de la canalización de registro, ya que garantizan que solo los usuarios autorizados puedan acceder y modificar los registros. La implementación de medidas de seguridad avanzada, como el cifrado y la protección DDoS, también es esencial para proteger la canalización de registro contra amenazas y vulnerabilidades.

En resumen, la creación de la canalización de registro es un paso fundamental en la configuración de la infraestructura escalable. Al seguir los pasos y considerar los factores mencionados anteriormente, usted puede crear una canalización de registro eficiente y segura que satisfaga las necesidades de su aplicación y su negocio.

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}]}}'

No hay texto para traducir. Por favor, proporcione el texto que desea traducir.

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

Paso 4: Implementar el DaemonSet de Fluent Bit para enviar los registros de Cluster (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

No hay texto para traducir. Por favor, proporcione el texto que desea traducir.

daemonset.apps/fluent-bit created

Paso 5: Simular una interrupción agregando una regla de NSG que bloquea el puerto de la capa de la aplicación, luego observe cómo falla el tráfico

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

Paso 6: Encuentre 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"

No hay texto para traducir. Por favor, proporcione el texto técnico que desea que traduzca.

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

Paso 7: Confirmar a nivel de red con Flow Logs

python3 read_flowlogs.py | grep BLOCKED

No hay texto que traducir. Por favor, proporcione el texto técnico que necesita ser traducido al español.

BLOCKED: 10.0.2.5 -> 10.0.3.7 port 8080

Lista de verificación de validación:

• [ ] Se creó la canalización de monitorización y se capturó la clave antes de cualquier segunda llamada a API
• [ ] La canalización de registro alcanza Ready y el DaemonSet de Fluent Bit está en ejecución
• [ ] La consulta de Activity Logs devuelve el cambio de configuración ofensivo
• [ ] Flow Logs muestra los registros 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 los desarrolladores que deben evitarse con la observabilidad en IONOS Cloud:

1. Esperar registros de Kubernetes sin reenvío

   • Problema: Usted abre el Logging Service Grafana después de implementar en MKS y no ve registros de Cluster o control-plane.
   • Por qué sucede: Los eventos de control-plane de Kubernetes no fluyen a través de la plataforma IONOS Logging Service automáticamente. La plataforma no los envía por usted.
   • Solución: Ejecute Fluent Bit como un DaemonSet (o configure la registración centralizada) y apúntelo a la tubería de registración tcpAddress con la clave compartida antes de que necesite los registros.

2. Perder la clave de la tubería de métricas

   • Problema: Su agente obtiene 401/403 en push y no puede encontrar la clave para solucionarlo.
   • Por qué sucede: La clave de ingesta se devuelve solo una vez, en metadata.key al crear la tubería, y nunca aparece en respuestas posteriores por razones de seguridad.
   • Solución: Capture la clave en su tienda de secretos en el momento de la creación. Si se pierde, no se puede recuperar; proporcione una tubería fresca o gire la clave.

3. Intentar editar un registro de flujo en su lugar

   • Problema: Usted actualiza la dirección de captura de un registro de flujo a través de API y el cambio no tiene efecto.
   • Por qué sucede: La configuración del registro de flujo es inmutable después de la creación, y hay un 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 eliminación y creación en su Terraform/automatización en lugar de esperar una actualización en su lugar.

Resumen

Ahora puede instrumentar TaskBoard de extremo a extremo en IONOS Cloud. Las métricas fluyen hacia una Monitoring Service pipeline y se representan en managed Grafana con alertas; los registros fluyen hacia una Logging Service pipeline a través de Fluent Bit; los cambios de infraestructura son auditables a través de la lectura-only Activity Logs API; y los fallos a nivel de red son visibles en Flow Logs escritos en Object Storage. Con sondas y controles de salud de ALB coincidentes en su lugar, las instancias rotas se eliminan automáticamente de la rotación. Lo más importante, usted conoce la restricción de IONOS que afecta a los equipos en producción: los registros Cluster y los eventos de control de plano deben ser reenviados por usted, no por la plataforma.

Puntos clave:

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

Terminología importante:

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

Próximos pasos

Continúe aprendiendo: Unidad 5.2: Automatización de la seguridad

Temas relacionados:

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