Aller au contenu

Runbook : OpenMetadataAPIErrors5xx

Alerte : OpenMetadataAPIErrors5xx (PrometheusRule, severity critical)

Symptôme :

L'API OpenMetadata retourne > 5 % de 5xx sur 5 min. Le catalog devient inutilisable depuis le cockpit, Superset, l'ingestion Airflow.

Severity : 🔴 critical

Diagnostic

1. Vérifier les pods

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get pod -n akko -l app.kubernetes.io/name=openmetadata
# Attendu : openmetadata + openmetadata-ingestion + opensearch

2. Logs serveur OpenMetadata

kubectl logs -n akko -l app.kubernetes.io/name=openmetadata --tail=200 | grep -iE "error|exception|500"

3. Vérifier OpenSearch (dépendance critique)

kubectl get pod -n akko -l app.kubernetes.io/name=opensearch
kubectl exec -n akko svc/akko-opensearch -- curl -s http://localhost:9200/_cluster/health | jq .
# Attendu : "status": "green" ou "yellow" ; "red" = problème

4. Vérifier le backend PostgreSQL

kubectl exec -n akko akko-postgresql-0 -- psql -U postgres -l | grep openmetadata

Causes fréquentes + correctif

Cause Symptôme (logs) Correctif
OpenSearch down NoNodeAvailableException Redémarrer OpenSearch : kubectl rollout restart sts/akko-opensearch
Pool de connexions PG plein Connection timed out Bump database.connectionPoolSize dans la config
Heap OOM OutOfMemoryError: Java heap space Bump resources.limits.memory + -Xmx JVM
Token Keycloak expiré pod-to-pod 401 Unauthorized sur webhooks Vérifier KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true (L04)
État DB incorrect après upgrade relation does not exist Relancer le job openmetadata-migrate
Jetty header trop petit HTTP 431 Request Header Too Large SERVER_MAX_REQUEST_HEADER_SIZE=64KiB (L07)

Correctif d'urgence (< 5 min)

Rolling restart du serveur OpenMetadata

kubectl rollout restart deploy/akko-openmetadata -n akko
kubectl rollout status deploy/akko-openmetadata -n akko --timeout=300s

Vérifier la santé post-restart

kubectl port-forward -n akko svc/akko-openmetadata 8585:8585 &
curl -f http://localhost:8585/api/v1/system/version
# Attendu : JSON avec {"version":"1.12.x"}

Correctif pérenne (R02)

L07 — taille header Jetty

Dans helm/examples/values-dev.yaml ou values-netcup.yaml :

openmetadata:
  extraEnvs:
    - name: SERVER_MAX_REQUEST_HEADER_SIZE
      value: "65536"
    - name: SERVER_MAX_RESPONSE_HEADER_SIZE
      value: "65536"

L05 — Config figée en DB au bootstrap

OpenMetadata stocke sa config OIDC en DB au premier boot. Les env vars ne sont pas ré-appliquées au restart. Pour reconcilier, utiliser le hook Helm post-install om-oidc-job.yaml qui UPDATE les settings à chaque upgrade. Vérifier son existence :

ls helm/akko/charts/akko-init/templates/openmetadata-oidc-job.yaml

Migration DB

kubectl get job -n akko openmetadata-migrate -o json | jq .status
# Si pas complete, relancer :
kubectl delete job -n akko openmetadata-migrate
helm upgrade akko helm/akko/ -n akko -f ... --set akko-init.openmetadataMigrate.enabled=true

Prévention

  • Test Playwright @authenticated : alice peut ouvrir catalog. sans re-login
  • PrometheusRule précoce : alerter à 2 % de 5xx, pas 5 %
  • Probe HTTP(s) dédiée : 
    - alert: OpenMetadataAPI5xxRate
  expr: sum(rate(http_requests_total{status=~"5..", service="openmetadata"}[5m]))
        / sum(rate(http_requests_total{service="openmetadata"}[5m])) > 0.02
  severity: warning
  • Backup DB OpenMetadata via le CronJob S8-D
  • Resources OpenSearch adéquates (>= 512Mi limits, anti-affinity)

Lessons learned

  • L04 — Split-horizon DNS en k3d → KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true
  • L05 — Config OpenMetadata en DB ≠ env vars
  • L07 — Header Jetty 8KiB trop petit pour JWT Keycloak — bump 64KiB

Liens utiles