Unité 5.1 : Observabilité et débogage

Introduction

Vous avez expédié TaskBoard vers Managed Kubernetes à l'Unité 3 et l'avez connecté à PostgreSQL, Redis, Object Storage et Kafka à l'Unité 4. Maintenant, il est en production, et à un moment donné, il se comportera de manière anormale : des pics de latence de API, un crash de pod, une connexion de base de données qui expire silencieusement, ou le trafic cesse d'atteindre un niveau et personne ne sait pourquoi. Sans une visibilité intégrée, vous déboguez à l'aveugle.

Cette unité vous montre comment instrumenter et déboguer TaskBoard de manière programmatique sur IONOS Cloud. Vous allez envoyer des métriques à Monitoring Service, transmettre des journaux à Logging Service, auditer les modifications d'infrastructure via Activity Logs, et capturer le trafic réseau avec Flow Logs. Chaque outil couvre une couche différente de la pile, et l'unité se termine par un flux de débogage répétable Kubernetes qui les relie. De manière critique, vous apprendrez également la contrainte IONOS qui piège la plupart des équipes : les événements de plan de contrôle de Kubernetes ne passent pas automatiquement par Logging Service, vous devez donc transmettre les journaux Cluster vous-même.

1. Métriques avec le Monitoring Service

Le Monitoring Service ingère des métriques via un pipeline que vous créez à travers le REST API. Chaque pipeline expose un point de terminaison de transmission HTTP qui accepte des métriques au format Prometheus (Compteur, Jauge, Histogramme, Résumé), et la visualisation se produit dans une instance Grafana gérée provisionnée par contrat et par région. Le format d'ingestion alternatif est JSON, qui doit être compressé à l'aide de Snappy.

Vous créez un pipeline en POSTant vers /pipelines sur le point de terminaison régional. Le point de terminaison suit le modèle https://monitoring.<region-slug>.ionos.com, par exemple https://monitoring.de-txl.ionos.com/pipelines pour Berlin ou https://monitoring.de-fra.ionos.com/pipelines pour Francfort. Les agents de transmission pris en charge sont Prometheus, Grafana Agent, OpenTelemetry et Fluent Bit.

1.1 Création d'un pipeline de métriques

Créez le pipeline avec un jeton Bearer. La réponse renvoie la clé d'ingestion par pipeline en metadata.key, mais uniquement lors de la création. Pour des raisons de sécurité, la clé n'est jamais renvoyée dans les réponses ultérieures, donc capturez-la immédiatement et stockez-la dans votre gestionnaire de secrets.

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

Sortie attendue (truncatée) :

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

Le modèle d'hôte d'ingestion est <id>-metrics.<id>.monitoring.<region>.ionos.com, et le chemin de transmission est /api/v1/push sur le port sortant 443. Le modèle d'URL de transmission complet est <httpEndpoint>/api/v1/push.

1.2 Transmission de métriques à partir de TaskBoard

Configurez votre agent pour transmettre au point de terminaison du pipeline. L'agent Grafana, Prometheus et OpenTelemetry s'authentifient en définissant l'en-tête APIKEY: <key>. L'exemple Fluent Bit utilise à la place Authorization: Bearer <apiKey>. L'intervalle de transmission par défaut est de 1 minute et est 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"]

Une fois les données reçues, créez des tableaux de bord et des alertes dans l'instance Grafana gérée à l'adresse grafanaEndpoint de la réponse de création. Vous définissez les conditions d'alerte, les seuils et les préférences de notification directement dans Grafana, par exemple une alerte lorsque la latence de demande p95 de TaskBoard API dépasse un seuil sur une fenêtre de 5 minutes. L'accès au Monitoring Service est contrôlé par le privilège IAM nommé Access and manage Monitoring.

2. Journaux centralisés avec le Logging Service

Le Logging Service collecte les journaux sur son propre pipeline, créé avec POST /pipelines sur le point de terminaison régional https://logging.<region-slug>.ionos.com. Un nouveau pipeline retourne le statut PROVISIONING et devient utilisable une fois qu'il est Ready. Les sources de journaux prises en charge sont Kubernetes, Docker, Linux Systemd, HTTP (JSON REST API), et Generic. La rétention par défaut est de 30 jours, et les valeurs de rétention autorisées sont 7, 14, 30 ou illimitées. Chaque pipeline permet jusqu'à 5 flux de journaux.

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

Les journaux sont interrogables dans le Logging Service Grafana sur une fenêtre de requête de 30 jours. L'accès nécessite le privilège IAM Access and manage Logging Service.

2.1 Transfert de journaux avec Fluent Bit

Fluent Bit est l'agent de journalisation pris en charge. Chaque source de journal nécessite le point de terminaison du pipeline et une clé, obtenus à partir de la réponse REST API. Pour Kubernetes, installez le paquet Fluent Bit pour votre distribution, puis pointez sa sortie de transfert vers le point de terminaison tcpAddress du pipeline avec la clé partagée.

# 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}

Notez que la source de journal HTTP REST n'accepte que les enregistrements de journal au format JSON, donc structurez vos journaux d'application comme JSON lorsque vous utilisez le chemin HTTP au lieu du protocole de transfert.

2.2 La contrainte de plan de contrôle Kubernetes

Ceci est le piège spécifique à IONOS. Les événements de plan de contrôle Kubernetes NE passent PAS automatiquement par le Logging Service d'IONOS. Le déploiement d'une charge de travail sur Managed Kubernetes ne vous donne PAS le transfert de journal Cluster gratuitement. Vous devez configurer le transfert de journal au niveau Cluster séparément, ce qui signifie en pratique exécuter Fluent Bit en tant que DaemonSet dans votre Cluster pour expédier les journaux Node et les journaux de pod vers votre 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

Pour un transfert intégré sans que chaque produit exécute sa propre pile d'ingestion, le Logging Service propose également la journalisation centralisée, une fonctionnalité au niveau du contrat, par région, activée avec PUT /central (corps {"properties":{"enabled":true}}). Seuls les administrateurs de contrat, les propriétaires et les utilisateurs avec le privilège Access and manage Logging Service peuvent basculer cette fonctionnalité.

3. Auditer les modifications avec Activity Logs

Lorsqu'un incident remonte à une modification de configuration, Activity Logs répond à qui a modifié quoi et quand. L'URL de base de API est https://api.ionos.com/activitylog/v1, et le service est en lecture seule par conception : chaque appel est un GET. Il enregistre les connexions utilisateur, la mise à disposition de ressources, les modifications de configuration, l'accès aux données, les récupérations de ressources, les modifications de ressources et les suppressions de ressources. Chaque entrée suit également la source d'une action, les ressources affectées et la chronologie des événements. Les réponses sont JSON, et l'authentification accepte l'authentification de base ou un jeton Bearer.

3.1 Interroger le journal d'activité

Filtrer par une plage de début et de fin date pour délimiter une fenêtre d'enquête. La pagination est contrôlée avec une limite qui plafonne le nombre d'éléments de réponse par page et un décalage pour parcourir les pages suivantes.

# 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"

(replacez ${CONTRACT_NUMBER} par votre numéro de contrat ; le chemin de base /activitylog/v1 sans segment /contracts/{contractNumber} ne retourne que les informations de version API, et non les entrées de journal.)

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

La période de rétention pour Activity Logs est de 35 jours. Pour tout ce dont vous avez besoin au-delà de cela, téléchargez les données et stockez-les ailleurs. IONOS Cloud Object Storage est la cible explicitement recommandée pour la persistance à long terme, donc un travail d'exportation planifié dans un bucket vous donne une traçabilité qui dépasse la fenêtre intégrée.

4. Débogage du réseau avec Flow Logs

Lorsque la connectivité est interrompue entre les niveaux de TaskBoard et les journaux d'application sont silencieux, le problème se situe généralement au niveau du réseau : une règle de pare-feu, un écart de routage ou une carte réseau (NIC) mal configurée. Flow Logs capture le trafic afin que vous puissiez voir exactement ce qui est accepté et rejeté. Les ressources prises en charge sont la carte réseau (NIC) VM, Managed Network Load Balancer, Managed Application Load Balancer et Managed NAT Gateway. Les actions de capture sont Rejetées, Acceptées ou Toutes, et les directions de capture sont Entrée, Sortie ou Bidirectionnelle. Les deux IPv4 et IPv6 sont pris en charge.

Flow Logs publie dans un seau IONOS Cloud Object Storage sous la forme .log.gz (texte compressé gzip), tourné tous les 10 minutes. Deux contraintes sont importantes pour l'automatisation : la configuration est immuable après sa création, et il n'y a qu'un journal de flux par ressource. Pour modifier un paramètre, vous supprimez et recréez. La création de Flow Logs nécessite le privilège de groupe Create Flow logs DCD.

4.1 Lecture des enregistrements de journal de flux

Chaque enregistrement est au format fixe et immuable (version 2). Les champs les plus utiles pour le débogage sont srcaddr, dstaddr, srcport, dstport, protocol et action, où action est ACCEPT (autorisé par le pare-feu) ou REJECT (bloqué par le pare-feu). Une série d'entrées REJECT sur le port que votre application utilise pointe directement vers une règle de groupe de sécurité réseau (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])

Le champ log-status est OK pour un intervalle normal ou SKIPDATA lorsque des enregistrements ont été ignorés pendant l'intervalle. Voir SKIPDATA signifie que vous n'obtenez pas une image complète pour cette fenêtre.

5. Le flux de débogage de Kubernetes

La plupart des incidents de production de TaskBoard apparaissent d'abord dans Kubernetes. Travaillez les couches dans l'ordre plutôt que de passer directement aux outils de plateforme, car le signal le moins coûteux est le plus proche du pod.

5.1 Chemin d'escalade

Commencez avec kubectl et escaladez à l'observabilité de la plateforme uniquement lorsque le signal dans Cluster est épuisé :

# 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

Rappelez-vous la contrainte de la Section 2 : kubectl logs vous montre la sortie de conteneur en direct, mais elle ne persiste pas et les événements de plan de contrôle ne atteignent pas le Logging Service par défaut. La recherche de Logging Service n'est utile que si votre DaemonSet Fluent Bit est déjà en cours de transfert. Branchez l'observabilité avant l'incident, et non pendant.

5.2 Vérifications de santé

Les sondes de vivacité et de prêt sont votre première ligne de récupération automatisée. Une sonde de prêt qui échoue supprime le pod des points de terminaison de service, de sorte que le trafic cesse de s'écouler vers une instance défectueuse, tandis qu'une sonde de vivacité redémarre un conteneur bloqué.

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

Puisque Managed Application Load Balancer est provisionné séparément de vos manifests K8s, configurez sa vérification de santé pour correspondre au même chemin /readyz, afin que l'ALB et Kubernetes soient d'accord sur les backends sains.

API Carte de référence rapide

Points de terminaison clés pour le sujet de cette unité :

URL de base (CloudAPI) : https://api.ionos.com/cloudapi/v6 Authentification : Authorization: Bearer <token> (l'envoi de métriques utilise APIKEY: <key>)

Laboratoire de code

Objectif : Mettre en place des métriques et une journalisation centralisée pour TaskBoard, puis déboguer une panne de connectivité simulée en utilisant Activity Logs et Flow Logs.

Prérequis :

• Compte IONOS Cloud avec jeton API (IONOS_TOKEN exporté)
• TaskBoard en cours d'exécution sur Managed Kubernetes (Unité 3.2)
• kubectl configuré contre votre MKS Cluster
• Un seau Object Storage et une clé d'accès + clé secrète pour Flow Logs

Étape 1 : Créer le pipeline de surveillance

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

Sortie attendue :

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

Étape 2 : Capturez la clé d'ingestion

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

Sortie attendue :

Stored key length: 44

Étape 3 : Créer le pipeline de journalisation

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

Sortie attendue :

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

Étape 4 : Déployer le DaemonSet Fluent Bit pour transmettre les journaux Cluster (les journaux du plan de contrôle n'arriveront pas sinon)

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

Sortie attendue :

daemonset.apps/fluent-bit created

Étape 5 : Simuler une panne en ajoutant une règle NSG qui bloque le port du niveau application, puis observer l'échec du trafic

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

Étape 6 : Rechercher le changement dans le 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"

Sortie attendue :

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

Étape 7 : Confirmer au niveau du réseau avec Flow Logs

python3 read_flowlogs.py | grep BLOCKED

Le texte à traduire est vide, veuillez fournir le texte à traduire.

BLOCKED: 10.0.2.5 -> 10.0.3.7 port 8080

Liste de validation :

• [ ] Pipeline de surveillance créée et clé capturée avant tout deuxième appel de API
• [ ] Pipeline de journalisation atteint Ready et le DaemonSet Fluent Bit est en cours d'exécution
• [ ] La requête Activity Logs renvoie le changement de configuration incriminé
• [ ] Flow Logs affiche les enregistrements REJECT sur le port bloqué

Nettoyage :

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

Erreurs courantes

Erreurs de développement à éviter avec l'observabilité sur IONOS Cloud :

1. S'attendre à des journaux Kubernetes sans transfert

   • Problème : Vous ouvrez le Logging Service Grafana après le déploiement sur MKS et vous ne voyez aucun journal Cluster ou de plan de contrôle.
   • Pourquoi cela se produit-il : Les événements de plan de contrôle Kubernetes ne transitent pas automatiquement par la plateforme IONOS Logging Service. La plateforme ne les expédie pas pour vous.
   • Correction : Exécutez Fluent Bit en tant que DaemonSet (ou configurez la journalisation centralisée) et pointez-le vers le tcpAddress de votre pipeline de journalisation avec la clé partagée avant d'avoir besoin des journaux.

2. Perdre la clé du pipeline de métriques

   • Problème : Votre agent reçoit 401/403 lors de la poussée et vous ne pouvez pas trouver la clé pour corriger le problème.
   • Pourquoi cela se produit-il : La clé d'ingestion n'est renvoyée qu'une seule fois, dans metadata.key lors de la création du pipeline, et n'apparaît jamais dans les réponses ultérieures pour des raisons de sécurité.
   • Correction : Capturez la clé dans votre magasin de secrets au moment de la création. Si elle est perdue, vous ne pouvez pas la récupérer ; créez un nouveau pipeline ou faites pivoter la clé.

3. Essayer de modifier un journal de flux en place

   • Problème : Vous mettez à jour la direction de capture d'un journal de flux via API et le changement n'a pas d'effet.
   • Pourquoi cela se produit-il : La configuration du journal de flux est immuable après sa création, et il n'y a qu'un seul journal de flux par ressource.
   • Correction : Supprimez le journal de flux existant et créez-en un nouveau avec les paramètres souhaités. Encodez ce modèle de suppression puis de création dans votre Terraform/automatisation, plutôt que de vous attendre à une mise à jour en place.

Résumé

Vous pouvez maintenant instrumenter TaskBoard de bout en bout sur IONOS Cloud. Les métriques s'écoulent dans un pipeline Monitoring Service et sont rendues dans un Grafana géré avec des alertes ; les journaux s'écoulent dans un pipeline Logging Service via Fluent Bit ; les modifications d'infrastructure sont auditable via le Activity Logs API en lecture seule ; et les défaillances au niveau du réseau sont visibles dans Flow Logs écrit dans Object Storage. Avec des sondes et des vérifications de santé ALB correspondantes en place, les instances défectueuses sont supprimées automatiquement de la rotation. Le plus important, vous connaissez la contrainte IONOS qui affecte les équipes en production : les journaux Cluster et les événements de contrôle doivent être transmis par vous, et non par la plateforme.

Points clés :

• Les pipelines de surveillance acceptent les métriques au format Prometheus à /api/v1/push ; la clé d'ingestion n'est affichée qu'une seule fois lors de la création
• Les pipelines de journalisation prennent en charge les sources Kubernetes, Docker, Systemd, HTTP, et génériques avec une rétention de 7/14/30/illimitée ; Fluent Bit est l'agent pris en charge
• Les événements de contrôle Kubernetes ne s'écoulent pas automatiquement dans le pipeline Logging Service ; transmettez-les vous-même avec un DaemonSet Fluent Bit ou une journalisation centralisée
• Activity Logs est en lecture seule (GET uniquement), filtrable par date, avec une rétention de 35 jours ; exportez vers Object Storage pour des traces d'audit plus longues
• Flow Logs capture ACCEPT/REJECT par NIC, NLB, ALB, et passerelle NAT dans des objets .log.gz ; la configuration est immuable et une par ressource

Terminologie importante :

• Pipeline de métrique : Une instance Monitoring Service créée via POST /pipelines qui expose un point de terminaison de push HTTP pour les métriques au format Prometheus.
• Clé d'ingestion : Le credencial par pipeline renvoyé une seule fois dans metadata.key ; les agents l'envoient en tant qu'en-tête APIKEY (ou Bearer pour Fluent Bit).
• Journalisation centralisée : Un commutateur au niveau du contrat, par région (PUT /central) qui permet aux produits intégrés de transmettre des journaux au pipeline Logging Service sans que chacun exécute sa propre ingestion.
• Activity Logs : L'enregistrement d'audit API en lecture seule à /activitylog/v1 qui enregistre qui a modifié quelle ressource et quand, conservé pendant 35 jours.
• Flow Logs : Des captures de réseau immuables, par ressource, publiées sous forme de texte gzip dans Object Storage, utilisées pour voir le trafic accepté et rejeté.

Prochaines étapes

Continuer l'apprentissage : Unité 5.2 : Automatisation de la sécurité

Sujets connexes :

• Unité 3.2 : Déploiement et exploitation de Kubernetes
• Unité 4.2 : Intégration de Object Storage