Init Jobs — Bootstrap de la plateforme¶

Aperçu¶

AKKO utilise un ensemble de Jobs Kubernetes pour initialiser la plateforme à chaque helm install ou helm upgrade. Ces jobs créent les schémas PostgreSQL, les buckets object storage, les catalogues Iceberg Polaris, les clients OAuth Keycloak, les dashboards Superset et les fonctions IA. Tous les jobs sont idempotents — ils peuvent s'exécuter plusieurs fois sans effet de bord.

Les jobs d'initialisation sont empaquetés dans le sous-chart akko-init et remplacent le besoin d'étapes de configuration manuelles après le déploiement.

Architecture¶

helm install / upgrade
        |
        v
  +------------------+
  | akko-init chart  |
  +--------+---------+
           |
  +--------+--------+--------+--------+--------+--------+--------+--------+
  |        |        |        |        |        |        |        |        |
  v        v        v        v        v        v        v        v        v
postgres postgres minio   polaris keycloak keycloak superset  ai     bootstrap
 -init   -data    -init   -init  -clients  -sync  -bootstrap func   -admin
         -init

Jobs¶

Job	Fonction	Dépend de
postgres-init	Crée les bases de données d'infrastructure (keycloak, airflow, superset, polaris, openmetadata, mlflow, jupyterhub) et les extensions	PostgreSQL (infra)
postgres-data-init	Crée les bases de données fonctionnelles (banking, healthcare, geospatial, rag) avec les extensions PostGIS + pgvector et les données de démonstration	PostgreSQL (data)
minio-init	Crée les buckets S3 (akko-warehouse, akko-production, akko-projects, akko-shared, akko-users) et les politiques d'accès	object storage
polaris-init	Crée le catalogue Iceberg `akko-warehouse` et les namespaces (banking, healthcare, retail, telecom, manufacturing, raw, staging, analytics)	Apache Polaris
keycloak-clients	Configure les URIs de redirection OAuth2 pour tous les services derrière oauth2-proxy, en utilisant des patterns de domaine génériques	Keycloak
keycloak-sync	Synchronise les utilisateurs LDAP depuis directory service dans Keycloak (quand directory service est activé)	Keycloak, directory service
superset-bootstrap	Crée les datasets, charts et le dashboard de démonstration dans Superset via l'API	Superset, Trino
ai-functions	Installe les fonctions PL/Python IA dans PostgreSQL Data (fonctions SQL alimentées par LLM)	PostgreSQL (data), LiteLLM
bootstrap-admin	Crée l'utilisateur admin initial et assigne les rôles RBAC	Keycloak

Idempotence¶

Chaque job utilise CREATE ... IF NOT EXISTS, PUT (et non POST), ou des patterns équivalents. Cela signifie :

Première installation : tout est créé de zéro
Mises à jour suivantes : les ressources existantes sont laissées intactes, seules les ressources manquantes sont créées
Aucune perte de données : les jobs ne font jamais de DROP ou DELETE sur les données existantes

-- Exemple : postgres-init ensure.sql
CREATE DATABASE keycloak WITH OWNER = akko_admin;
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE SCHEMA IF NOT EXISTS banking;

Configuration¶

Activer / désactiver les jobs¶

Chaque job peut être activé ou désactivé individuellement :

akko-init:
  polaris:
    enabled: true
  minio:
    enabled: true
  ollama:
    enabled: true
  superset:
    enabled: true
  keycloak:
    enabled: true
  aiFunctions:
    enabled: true
  keycloakClients:
    enabled: true

Namespaces Polaris¶

Le job d'initialisation Polaris crée des namespaces pour l'organisation des données :

akko-init:
  polaris:
    catalog:
      name: akko-warehouse
      namespaces:
        - banking
        - healthcare
        - retail
        - telecom
        - manufacturing
        - raw
        - staging
        - analytics

Buckets object storage¶

akko-init:
  minio:
    buckets:
      - akko-warehouse
      - akko-production
      - akko-projects
      - akko-shared
      - akko-users

CronJobs de sauvegarde¶

Le chart init inclut également des CronJobs de sauvegarde optionnels pour PostgreSQL et object storage :

akko-init:
  backup:
    postgres:
      enabled: false         # Activer en production
      schedule: "0 2 * * *"  # 2h du matin quotidien
      retention: 7           # Conserver 7 sauvegardes
    minio:
      enabled: false
      schedule: "0 4 * * *"
      retention: 7

Chart Helm¶

helm/akko/charts/akko-init/
├── Chart.yaml
├── values.yaml
├── files/                          # Scripts SQL, fichiers de config
└── templates/
    ├── _helpers.tpl
    ├── postgres-init-job.yaml
    ├── postgres-ensure-configmap.yaml
    ├── postgres-data-init-job.yaml
    ├── postgres-data-ensure-configmap.yaml
    ├── minio-init-job.yaml
    ├── polaris-init-job.yaml
    ├── keycloak-clients-job.yaml
    ├── keycloak-sync-job.yaml
    ├── superset-bootstrap-job.yaml
    ├── ai-functions-job.yaml
    ├── bootstrap-admin-job.yaml
    ├── backup-postgres-cronjob.yaml
    ├── backup-minio-cronjob.yaml
    ├── backup-pvc.yaml
    └── serviceaccount.yaml

Utilisation des ressources¶

Les jobs d'initialisation sont éphémères et légers :

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    cpu: 200m
    memory: 128Mi

Les jobs s'exécutent jusqu'à complétion et sont nettoyés par Kubernetes après succès (ttlSecondsAfterFinished).

Dépannage¶

Job en échec — Pod en état d'erreur¶

Symptômes : Un pod de job affiche Error ou BackoffLimitExceeded. La plateforme est partiellement initialisée.

Cause : Le service cible (PostgreSQL, object storage, Keycloak, etc.) n'était pas prêt lorsque le job s'est exécuté. Les politiques réseau ou les secrets peuvent être mal configurés.

Solution :

# Vérifier quels jobs ont échoué
kubectl get jobs -n akko -l app.kubernetes.io/instance=akko | grep -v "1/1"

# Consulter les logs du job en échec
kubectl logs -n akko job/<nom-du-job> --tail=50

# Relancer un job spécifique en le supprimant (Helm le recrée au prochain upgrade)
kubectl delete job -n akko <nom-du-job>
helm upgrade akko helm/akko/ -n akko -f helm/examples/values-dev.yaml

PostgreSQL Init : permission refusée¶

Symptômes : Le job postgres-init échoue avec permission denied ou role does not exist.

Cause : Les identifiants superutilisateur PostgreSQL dans le secret Helm ne correspondent pas à ce qui est configuré dans le pod PostgreSQL.

Solution :

# Consulter les logs du job d'init
kubectl logs -n akko job/akko-postgres-init --tail=30

# Vérifier que le secret correspond à la config PostgreSQL
kubectl get secret -n akko akko-postgresql -o jsonpath='{.data.postgres-password}' | base64 -d

# Si les identifiants ont changé, le volume PostgreSQL conserve l'ancien mot de passe
# Il peut être nécessaire de faire un ALTER USER dans le pod PostgreSQL actif
kubectl exec -n akko deploy/akko-postgresql -- psql -U postgres -c "ALTER USER akko_admin WITH PASSWORD 'newpassword';"

object storage Init : le bucket existe déjà¶

C'est normal et attendu. Le job d'init object storage utilise mc mb --ignore-existing, donc les buckets préexistants sont silencieusement ignorés.

Polaris Init : échec de création du catalogue¶

Symptômes : Le job polaris-init échoue avec HTTP 500 ou connexion refusée.

Cause : Polaris est peut-être encore en train d'initialiser son schéma de base de données. Le job a besoin que Polaris soit totalement prêt.

Solution :

# Vérifier la disponibilité de Polaris
kubectl get pods -n akko -l app.kubernetes.io/name=akko-polaris

# Consulter les logs de polaris-init
kubectl logs -n akko job/akko-polaris-init --tail=30

# Relancer le job
kubectl delete job -n akko akko-polaris-init
helm upgrade akko helm/akko/ -n akko -f helm/examples/values-dev.yaml

Licence¶

Tout le code des jobs d'initialisation fait partie de la plateforme AKKO : Apache 2.0.