PostgreSQL¶

Aperçu¶

AKKO déploie deux instances PostgreSQL distinctes pour imposer une séparation stricte entre les métadonnées d'infrastructure et les données métier. Les deux instances utilisent l'image personnalisée akko-postgres, qui intègre les extensions PostGIS (géospatial) et pgvector (embeddings IA).

Architecture¶

  ┌─────────────────────────────────┐
  │  akko-postgresql (infra)        │
  │  Bases de données :             │
  │    keycloak, airflow, superset, │
  │    polaris, openmetadata,       │
  │    mlflow, jupyterhub, litellm  │
  └─────────────────────────────────┘

  ┌─────────────────────────────────┐
  │  akko-postgresql-data (métier)  │
  │  Bases de données :             │
  │    analytics, geospatial, rag   │
  │  Extensions :                   │
  │    PostGIS, pgvector            │
  └─────────────────────────────────┘

Deux instances PostgreSQL — Obligatoire

Ne jamais mélanger données d'infrastructure et données métier dans le même serveur. Cette séparation permet des sauvegardes/restaurations, mises à l'échelle et politiques de sécurité indépendantes. Les bases d'infrastructure contiennent l'état des services (sessions, DAGs, dashboards) ; les bases métier contiennent les données analytiques utilisateur.

Ports¶

Instance	Port	Fonction	Exposé
akko-postgresql	5432	Bases de données de métadonnées d'infrastructure	Interne uniquement
akko-postgresql-data	5432	Bases de données métier/analytiques	Interne uniquement (exposé à Trino pour la fédération)

Bases de données¶

akko-postgresql (Infrastructure)¶

Base de données	Utilisée par	Fonction
`keycloak`	Keycloak	Realm SSO, utilisateurs, sessions
`airflow`	Airflow	Métadonnées des DAGs, état des tâches, connexions
`superset`	Superset	Dashboards, graphiques, jeux de données, utilisateurs
`polaris`	Polaris	Métadonnées du catalogue Iceberg
`openmetadata`	OpenMetadata	Catalogue de gouvernance des données
`mlflow`	MLflow	Suivi des expériences, registre de modèles
`jupyterhub`	JupyterHub	État utilisateur, données du spawner
`litellm`	LiteLLM	Configuration de la passerelle IA, logs d'utilisation

akko-postgresql-data (Métier)¶

Base de données	Extensions	Fonction
`analytics`	—	Données d'intelligence métier, tables de démo bancaire
`geospatial`	PostGIS	Données géographiques, requêtes spatiales
`rag`	pgvector	Embeddings vectoriels pour les pipelines RAG

Extensions¶

PostGIS¶

PostGIS ajoute des types géospatiaux (geometry, geography) et des fonctions (ST_Distance, ST_Within, etc.) pour l'analyse spatiale. Activé dans la base geospatial.

pgvector¶

pgvector ajoute le type vector et des opérateurs (<-> distance cosinus, <#> produit scalaire) pour le stockage d'embeddings IA et la recherche par similarité. Activé dans la base rag.

postgres/init/05-pgvector.sql

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS embeddings (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(768),
    metadata JSONB
);

Configuration¶

Image personnalisée¶

docker/postgres/Dockerfile

FROM postgres:16.6
RUN apt-get update && apt-get install -y \
    postgresql-16-postgis-3 \
    postgresql-16-pgvector

L'image est construite sous le nom akko-postgres:2026.03.

Scripts d'initialisation¶

L'initialisation des bases suit deux mécanismes :

Scripts postgres/init/ — exécutés une seule fois quand le volume de données est vide (comportement standard docker-entrypoint-initdb.d)
Sidecar ensure.sql — exécuté à chaque déploiement pour garantir que les extensions, schémas et tables existent (idempotent, survit aux redémarrages)

Première fois vs À chaque fois

Les scripts dans postgres/init/ ne s'exécutent qu'au premier démarrage (volume vide). Pour tout ce qui doit toujours exister (extensions, schémas), utilisez l'approche sidecar ensure.sql qui s'exécute à chaque helm upgrade.

Chart Helm¶

PostgreSQL est déployé via le sous-chart personnalisé akko-postgres (remplace Bitnami pour éviter les conflits de version et garantir le support PostGIS/pgvector) :

helm/akko/charts/akko-postgres/
├── Chart.yaml
├── values.yaml
├── files/
│   ├── ensure.sql
│   └── init-scripts/
└── templates/
    ├── statefulset.yaml
    ├── service.yaml
    ├── secret.yaml
    └── configmap.yaml

Valeurs clés¶

values.yaml

akko-postgres:
  enabled: true
  image:
    repository: akko-postgres
    tag: "2026.03"
  persistence:
    enabled: true
    size: 20Gi
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: "1"
      memory: 1Gi

Dépannage¶

Problèmes courants

Mot de passe incorrect après rotation des secrets : PostgreSQL persiste les mots de passe dans son volume de données. Si vous changez le secret dans Kubernetes, vous devez aussi exécuter ALTER USER ... PASSWORD '...' dans la base en cours d'exécution. Redémarrer le pod seul ne suffit pas.
Extension introuvable (pgvector ou PostGIS) : Assurez-vous d'utiliser l'image personnalisée akko-postgres:2026.03, pas l'image vanilla postgres. Vérifiez avec kubectl exec statefulset/akko-postgresql-data -- psql -c "SELECT * FROM pg_available_extensions WHERE name IN ('vector','postgis')".
Connexion refusée depuis les services : Vérifiez le nom DNS du service (akko-postgresql pour l'infra, akko-postgresql-data pour le métier) et le port (5432). Vérifiez que le pod du StatefulSet est en cours d'exécution et que la sonde de disponibilité passe.