Skip to content

Runbook: PolarisAPIExceptions

Alerte : PolarisAPIExceptions (PrometheusRule, severity critical)

Symptôme :

Apache Polaris (Iceberg catalog) retourne des exceptions > 2% des requêtes. Les queries Trino, Spark et dbt écrivent/lisent des tables Iceberg échouent.

Severity : 🔴 critical — impacts TOUT le data lakehouse

Diagnostic

1. État des pods Polaris

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get pod -n akko -l app.kubernetes.io/name=polaris
kubectl describe pod -n akko -l app.kubernetes.io/name=polaris | tail -30

2. Logs serveur

kubectl logs -n akko -l app.kubernetes.io/name=polaris --tail=200 | \
  grep -iE "error|exception|stack" | head -30

3. Health endpoint

kubectl port-forward -n akko svc/akko-polaris 8181:8181 &
curl -f http://localhost:8181/q/health
# Attendu : {"status": "UP"}

4. Backend PostgreSQL

kubectl exec -n akko akko-postgresql-0 -- \
  psql -U postgres -d polaris -c "SELECT count(*) FROM public.tables;"

5. Backend object storage

kubectl exec -n akko akko-minio-0 -- \
  mc ls local/akko-warehouse/ | head -10

Causes fréquentes + fix

Cause Symptôme Fix
Postgres pool épuisé unable to acquire JDBC connection Bump quarkus.datasource.jdbc.max-size (default 20)
object storage credentials expirés AccessDenied, InvalidAccessKeyId Régénérer creds + kubectl rollout restart Polaris
S3 bucket not found NoSuchBucket Recréer : mc mb local/akko-warehouse
OPA policy bloque 403 Forbidden, user not authorized Vérifier bundle OPA: kubectl logs -n akko opa --tail=50
Namespace PII supprimé en cours de query namespace not found Vérifier DROP NAMESPACE n'est pas en cours
DB migration manquée column X does not exist Relancer polaris-init job
Keycloak JWT mal validé 401 Unauthorized Vérifier quarkus.oidc.auth-server-url correct (L04)

Fix d'urgence (< 5 min)

Rolling restart

kubectl rollout restart deploy/akko-polaris -n akko
kubectl rollout status deploy/akko-polaris -n akko --timeout=180s

Test Trino → Polaris end-to-end

kubectl exec -n akko deploy/akko-trino -- \
  trino --execute="SHOW SCHEMAS FROM iceberg"
# Doit retourner au moins : default, banking

Vérifier object storage writable

kubectl exec -n akko akko-minio-0 -- \
  mc cp /etc/hostname local/akko-warehouse/healthcheck.txt && \
  mc cat local/akko-warehouse/healthcheck.txt

Fix pérenne (R02)

Augmenter le pool DB

# helm/akko/charts/akko-polaris/values.yaml
env:
  - name: QUARKUS_DATASOURCE_JDBC_MAX_SIZE
    value: "50"          # was 20
  - name: QUARKUS_DATASOURCE_JDBC_INITIAL_SIZE
    value: "5"

HA multi-replicas

Polaris est stateless (état en DB+object storage), donc scalable horizontalement :

replicaCount: 2
podDisruptionBudget:
  enabled: true
  minAvailable: 1

Monitoring OPA cohabitation

OPA bloque silencieusement. Vérifier dans Dashboards le dashboard "OPA decisions" (ratio allow/deny par principal).

Prévention

  • PrometheusRule granulaire : 
    - alert: PolarisDBPoolExhausted
  expr: hikaricp_pending_connections{pool="polaris"} > 5
  for: 2m
  severity: warning
- alert: PolarisMinIOSlow
  expr: histogram_quantile(0.95, rate(polaris_minio_latency_seconds_bucket[5m])) > 1
  severity: warning
  • Smoke test hebdomadaire : CREATE TABLE → INSERT → SELECT → DROP depuis Trino
  • Backup DB polaris + object storage warehouse via CronJob S8-D
  • OPA bundle versioning pour rollback rapide si une policy bloque

Lessons learned

  • Polaris + Keycloak backchannel-dynamic (L04) est critique en k3d ou lorsque pod-to-pod DNS différent de user DNS.
  • polaris-init DOIT être idempotent — voir l'architecture sidecar (R06).

Liens utiles