Catalog Manager Pro¶

AKKO Catalog Manager Pro est le backend en libre-service et la page cockpit qui permettent aux administrateurs d'enregistrer de nouveaux catalogues Trino à l'exécution. Il s'appuie sur la gestion dynamique des catalogues de Trino 480 (catalog.management=dynamic) : ajouter ou supprimer un catalogue est sans downtime et ne nécessite aucun helm upgrade.

Conception complète : ADR-021 (see docs/adr/ADR-021-catalog-manager-pro.md).

Connecteurs supportés (15)¶

Catégorie	Connecteurs
Relationnel	PostgreSQL, MySQL, SQL Server, Oracle
Lakehouse	Iceberg (REST), Hive + HDFS + Kerberos (Cloudera CDP 7.1.9), Delta Lake
Cloud DW	Snowflake, BigQuery, Redshift, Databricks
NoSQL	MongoDB, Cassandra, Elasticsearch
Streaming	Kafka

Architecture¶

Cockpit Admin → page Catalogs
    │ HTTPS + JWT Keycloak
    ▼
nginx (akko-cockpit)  /api/cockpit/catalog-manager/
    │  forwarde X-User-Id / Authorization Bearer
    ▼
Backend FastAPI (akko-catalog-manager, stack Apache 2.0)
    │   1. vérifie le JWT → impose le rôle akko-admin
    │   2. dry-run de la connexion via Trino /v1/catalog/test
    │   3. stocke les credentials dans un Secret K8s (jamais ConfigMap)
    │   4. POST /v1/catalog à Trino 480 — dynamique, sans restart
    │   5. génère le fragment de règle OPA (le watcher akko-opa le prend)
    │   6. déclenche l'ingestion OpenMetadata (best-effort)
    │   7. émet un audit JSON structuré → logs layer
    ▼
Trino 480  +  OpenMetadata  +  OPA

Ajouter un catalogue (cockpit)¶

Se connecter au cockpit avec un utilisateur ayant le rôle akko-admin.
Ouvrir l'entrée de sidebar Data Catalogs.
Cliquer sur + Add catalog.
Remplir le formulaire :
Nom (minuscules, [a-z0-9-], ≤ 40 caractères). Ex. client-pg-01.
Connecteur : choisir dans le menu déroulant.
Host / Port / Database / User / Password : paramètres de connexion.
Rôles autorisés : liste de rôles Keycloak (séparés par virgules) autorisés à interroger ce catalogue (règle OPA auto-générée). Par défaut : akko-admin,akko-engineer,akko-analyst.
Cliquer sur Test connection pour faire un dry-run.
Cliquer sur Register catalog — le catalogue est actif dans Trino en < 2 s.

Ajouter un catalogue (API)¶

curl -X POST https://cockpit.mon-entreprise.example/api/cockpit/catalog-manager/api/admin/catalogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "client-pg-01",
    "connector": "postgresql",
    "properties": {
      "connection-url": "jdbc:postgresql://db.customer.example:5432/sales",
      "connection-user": "trino_readonly"
    },
    "credentials": {
      "connection-password": "<masqué>"
    },
    "description": "Miroir lecture seule des ventes client",
    "allow_roles": ["akko-admin", "akko-engineer", "akko-analyst"]
  }'

Réponse : 201 Created avec les métadonnées du catalogue. Trino le voit immédiatement — lancer SHOW SCHEMAS FROM "client-pg-01" pour vérifier.

Hive + HDFS + Kerberos (Cloudera CDP 7.1.9) — bout-en-bout¶

Entièrement automatisé depuis v2026.04 — aucun opérateur ne touche jamais à du YAML, du kubectl ou au coordinator Trino. Ci-dessous la chaîne complète que le backend exécute quand vous validez le formulaire Kerberos.

Flux backend¶

Le formulaire du cockpit encode le keytab en base64 et l'envoie avec le krb5.conf collé sous credentials.kerberos.*.
akko-catalog-manager lit ces champs :
Décode le keytab base64, l'intègre dans le Secret partagé akko-catalog-keytabs sous la clé <catalog>.keytab (read-modify-write ; plusieurs catalogs Kerberos cohabitent).
Stocke le contenu krb5.conf dans le ConfigMap partagé akko-catalog-krb5-conf.
Le coordinator Trino monte déjà ces deux objets à /etc/security/keytabs/ et /etc/krb5.conf (voir helm/akko/values-trino.yaml). Kubernetes rafraîchit le mount automatiquement — typiquement en 30-60 s.
Le backend attend 45 s (configurable), puis lance le dry-run Trino. Si kinit échoue toute l'opération est rollback.
Les propriétés du catalog Trino sont enrichies automatiquement :
hive.metastore.authentication.type = KERBEROS
hive.hdfs.authentication.type = KERBEROS
hive.hdfs.impersonation.enabled = true
hive.metastore.client.principal = akko-trino@$AKKO_KERBEROS_REALM
hive.metastore.client.keytab = /etc/security/keytabs/<catalog>.keytab
La règle OPA live + l'ingestion OpenMetadata suivent le même chemin que pour les catalogs non-Kerberos.

Champs attendus côté opérateur¶

Champ	Exemple	Notes
URI Metastore	`thrift://hms.client.example:9083`	Joignable depuis le pod Trino
Principal de service	`hive/_HOST@CLIENT.LOCAL`	`_HOST` est expansé par nœud HMS
Keytab (upload fichier)	`akko-trino.keytab`	Doit contenir `akko-trino@CLIENT.LOCAL`
krb5.conf (textarea)	contenu de `/etc/krb5.conf`	Realms + hosts KDC
Rôles autorisés	`akko-admin, akko-engineer, akko-analyst`	Règle OPA auto-générée

Fenêtre de propagation — 45 s¶

Kubernetes prend jusqu'à 60 s pour rendre visible un Secret mis à jour dans un pod montant. Le backend attend 45 s avant le dry-run ; l'opérateur ne voit qu'un seul spinner. Surcharger avec AKKO_KEYTAB_PROPAGATION_SECONDS=60 sur le Deployment catalog-manager.

Utiliser le cluster de démo¶

demos/cloudera-simulation/ livre une stack Kerberized Cloudera-like tournant sur le même hôte Netcup. Démarrage : docker compose up -d && ./seed/seed.sh, puis au choix :

Uploader exports/akko-trino.keytab et coller exports/krb5.conf dans le formulaire du cockpit, ou
Lancer AKKO_ADMIN_TOKEN=<jwt> demos/cloudera-simulation/bootstrap-akko-catalog.sh qui poste le même payload sur l'API REST.

Le pipeline bout-en-bout est exercé par tests/post-deploy/05-cloudera-federation-e2e.sh (PASS/FAIL avec assertion de partition pruning).

Lister / supprimer un catalogue¶

Depuis le cockpit : le tableau affiche chaque catalogue enregistré, sa santé et un bouton Remove. La suppression désenregistre le catalogue de Trino et supprime le Secret K8s.

Depuis l'API :

curl -H "Authorization: Bearer $TOKEN" \
  https://cockpit.mon-entreprise.example/api/cockpit/catalog-manager/api/admin/catalogs
# → tableau JSON de {name, connector, allow_roles, health}

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://cockpit.mon-entreprise.example/api/cockpit/catalog-manager/api/admin/catalogs/client-pg-01
# → 204 No Content

Observabilité¶

Prometheus / VictoriaMetrics scrape /metrics toutes les 30 s :

akko_catalog_operations_total{operation="create|delete|test", result="success|failed"}
akko_catalog_operation_duration_seconds{operation=...}

Audit JSON (logs layer / logs layer) :

{
  "audit_type": "CATALOG_MANAGER",
  "event": "CATALOG_CREATED",
  "name": "client-pg-01",
  "connector": "postgresql",
  "user": "alice",
  "allow_roles": ["akko-admin", "akko-engineer", "akko-analyst"],
  "timestamp": 1713542400.123
}

Dépannage¶

Symptôme	Cause probable	Correctif
401 sur POST	Pas connecté avec le rôle `akko-admin`	Vérifier le rôle JWT via le menu utilisateur du cockpit
400 "connection test failed"	Mauvais host / port / creds / firewall	Lancer le test depuis un pod Trino : `kubectl exec ... -- nc -zv <host> <port>`
Catalogue visible au cockpit mais pas dans Trino	Coordinator Trino pas en 480, ou `catalog.management=static`	Bumper `values-trino.yaml` en 480 + ajouter `catalog.management=dynamic`
OpenMetadata vide pour le nouveau catalogue	Endpoint d'ingestion injoignable	Redéclencher via `POST /api/admin/catalogs/{name}/reindex` (roadmap)

Considération commerciale¶

Catalog Manager Pro est une fonctionnalité first-class d'AKKO qui remplace Starburst Mission Control pour l'onboarding data en self-service. Tous les composants sont sous licences permissives (Apache 2.0 FastAPI, Apache 2.0 Trino 480, MIT httpx/pydantic) — redistribution commerciale sans risque.