Skip to content

Runbook: OpenMetadataAPIErrors5xx

Alerte : OpenMetadataAPIErrors5xx (PrometheusRule, severity critical)

Symptôme :

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

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 .
# Expected: "status": "green" ou "yellow"; "red" = problème

4. Vérifier PostgreSQL backend

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

Causes fréquentes + fix

Cause Symptôme logs Fix
OpenSearch down NoNodeAvailableException Restart OpenSearch : kubectl rollout restart sts/akko-opensearch
Postgres connection pool plein Connection timed out Bump database.connectionPoolSize dans config
Heap OOM OutOfMemoryError: Java heap space Bump resources.limits.memory + -Xmx JVM
Keycloak token expire en pod-to-pod 401 Unauthorized sur webhooks Vérifier KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true (L04)
Mauvaise DB state après upgrade relation does not exist Relancer le job openmetadata-migrate
Jetty header too small HTTP 431 Request Header Too Large Set SERVER_MAX_REQUEST_HEADER_SIZE=64KiB (L07)

Fix d'urgence (< 5 min)

Rolling restart 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
# Expected: JSON avec {"version":"1.12.x"}

Fix pérenne (R02)

L07 — Jetty header size

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 store sa config OIDC en DB au premier boot. Les env vars ne sont PAS ré-appliquées au restart. Pour reconciler, utiliser le Helm hook 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

  • Playwright test @authenticated : alice peut ouvrir catalog. sans re-login
  • PrometheusRule précoce : alerter à 2% d'erreurs 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 CronJob S8-D
  • OpenSearch resources adequate (>= 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 — Jetty header 8KiB trop petit pour JWT Keycloak — bump 64KiB

Liens utiles