Aller au contenu

Configuration

Cette page couvre les variables d'environnement d'AKKO, la configuration TLS, les profils de déploiement, les exigences en ressources et les erreurs de configuration courantes.

Kubernetes-first

AKKO se déploie via Helm sur Kubernetes. Pour la configuration Kubernetes, consultez le guide Déploiement Kubernetes.

Variables d'environnement

Toute la configuration se trouve dans un fichier .env unique, à la racine du projet. Il est généré automatiquement par scripts/generate-secrets.sh à l'aide de valeurs aléatoires cryptographiquement sûres (via openssl rand).

# Générer le fichier .env (ignoré s'il existe déjà)
./scripts/generate-secrets.sh

Ne jamais committer les secrets

Les chemins suivants sont listés dans .gitignore et ne doivent jamais être committés :

  • .env -- tous les mots de passe, jetons et clés
  • traefik/certs/ -- clé privée et certificat TLS
  • traefik/acme/ -- état Let's Encrypt (si utilisé)

Variables principales

Variable Usage Valeur par défaut
AKKO_DOMAIN Domaine de base pour le routage *.domain localhost
AKKO_VERSION Label de version de la plateforme 0.1.0
POSTGRES_PASSWORD Mot de passe du superutilisateur PostgreSQL aléatoire
POSTGRES_AKKO_PASSWORD Mot de passe de l'utilisateur applicatif akko aléatoire
MINIO_ROOT_USER / MINIO_ROOT_PASSWORD Identifiants administrateur object storage (S3) akko-admin / aléatoire
KEYCLOAK_ADMIN_PASSWORD Mot de passe de la console d'administration Keycloak aléatoire
KEYCLOAK_DB_PASSWORD Mot de passe de l'utilisateur PostgreSQL pour Keycloak aléatoire
KC_CLIENT_SECRET_* Secrets des clients OAuth2 (JupyterHub, Superset, Airflow, Dashboards, oauth2-proxy, OpenMetadata) hexadécimal aléatoire
POLARIS_ROOT_SECRET Identifiant de démarrage Apache Polaris hexadécimal aléatoire
SUPERSET_SECRET_KEY Clé secrète Flask de Superset hexadécimal aléatoire
SUPERSET_ADMIN_PASSWORD Mot de passe administrateur Superset aléatoire
AIRFLOW_ADMIN_PASSWORD Mot de passe administrateur Airflow aléatoire
AIRFLOW__CORE__FERNET_KEY Clé de chiffrement Fernet d'Airflow aléatoire
GRAFANA_ADMIN_PASSWORD Mot de passe administrateur Dashboards aléatoire
JUPYTERHUB_SECRET_TOKEN Jeton d'authentification du proxy JupyterHub hexadécimal aléatoire
OLLAMA_MODEL Modèle LLM par défaut pour Ollama qwen2.5:3b
OLLAMA_HOST Point d'accès API Ollama (interne) http://ollama:11434
MINIO_ENDPOINT Point d'accès API object storage (interne) http://minio:9000
TRINO_MEMORY Taille du tas JVM de Trino 4GB
OM_AIRFLOW_PASSWORD Mot de passe Airflow pour l'ingestion OpenMetadata aléatoire
OM_INGESTION_BOT_JWT JWT du bot OpenMetadata (doit être remplacé après le premier démarrage) provisoire

Regénérer les secrets

Le script est idempotent -- il n'écrasera pas un fichier .env existant :

[*] .env already exists, skipping secrets generation.
    Delete .env to regenerate all secrets.

Pour regénérer tous les secrets :

rm .env
./scripts/generate-secrets.sh

Persistance des mots de passe PostgreSQL

PostgreSQL stocke les mots de passe dans son volume de données. Si vous regénérez .env, les nouveaux mots de passe ne prendront pas effet pour les utilisateurs de base de données existants. Vous devez les mettre à jour manuellement :

kubectl exec -n akko statefulset/akko-postgresql -- psql -U postgres -c \
  "ALTER USER akko WITH PASSWORD 'new-password';"

Cela s'applique à tous les utilisateurs de la base : postgres, akko, keycloak_user.

Domaine personnalisé

Par défaut, AKKO utilise le domaine akko.local (par ex. lab.akko.local, bi.akko.local). Ce domaine est configurable via global.domain dans les valeurs Helm.

Pour utiliser un domaine personnalisé :

  1. Définissez le domaine dans votre fichier de valeurs Helm : 

    global:
  domain: akko.example.com

  2. Déployez ou mettez à jour : 

    helm upgrade akko helm/akko/ -n akko -f your-values.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json

  3. Assurez-vous que le DNS résout *.akko.example.com vers l'IP d'ingress de votre cluster.

Communication inter-services

Toute communication inter-services utilise les noms DNS de services Kubernetes (par ex. akko-akko-keycloak:8080, akko-postgresql, akko-minio:9000), jamais les URL de domaine externe.

Certificats TLS

Les certificats auto-signés sont générés automatiquement par scripts/generate-certs.sh :

# Génère traefik/certs/akko.crt et traefik/certs/akko.key
./scripts/generate-certs.sh

Le certificat couvre *.${AKKO_DOMAIN} (SAN wildcard), de sorte que tous les sous-domaines sont servis en HTTPS par Traefik.

Safari et les certificats auto-signés

Safari exige une approbation manuelle pour les certificats auto-signés :

  1. Ouvrez Trousseaux d'accès (Keychain Access)
  2. Glissez traefik/certs/akko.crt dans le trousseau Système
  3. Double-cliquez sur le certificat, développez Confiance, définissez sur Toujours faire confiance
  4. Redémarrez Safari

Chrome et Firefox afficheront un avertissement mais vous permettront de continuer.

Profils de déploiement

AKKO utilise des toggles de sous-charts Helm pour gérer les services optionnels gourmands en ressources. Chaque sous-chart peut être activé ou désactivé indépendamment dans votre fichier values.yaml.

Profil par défaut (Core)

helm install akko helm/akko/ -n akko --create-namespace \
  -f helm/examples/values-dev.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json

Cela déploie environ 20 services principaux : Traefik, PostgreSQL, object storage, Polaris, Trino, Spark, JupyterHub, Superset, Airflow, Keycloak, Dashboards, Prometheus, Ollama, oauth2-proxy, cockpit, AKKO Docs et les jobs d'initialisation.

Profil Gouvernance

Activez OpenMetadata et OpenSearch dans votre fichier de valeurs :

# values-governance.yaml
openmetadata:
  enabled: true
akko-opensearch:
  enabled: true

Puis déployez :

helm upgrade akko helm/akko/ -n akko \
  -f helm/examples/values-dev.yaml \
  -f values-governance.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json

Ajoute OpenMetadata (serveur) et OpenSearch. Ces services consomment beaucoup de mémoire et nécessitent des ressources cluster supplémentaires.

Exigences en ressources

Profil RAM Docker Desktop minimum Recommandé
Par défaut (core) 8 Go 10 Go
Gouvernance 16 Go 20 Go

OpenMetadata + OpenSearch OOM

Avec moins de 16 Go alloués à Docker Desktop, les services du profil gouvernance entreront dans une boucle de redémarrage. OpenSearch seul nécessite environ 1 Go (mémoire heap + native) et échouera à 768 Mo.

Reconstruction des images personnalisées

AKKO compile quatre images Docker personnalisées localement. Après avoir modifié leurs Dockerfiles, vous devez les reconstruire :

# Reconstruire toutes les images personnalisées et les pousser dans le registre k3d :
bash helm/scripts/build-images.sh

# Puis mettre à jour :
helm upgrade akko helm/akko/ -n akko -f helm/examples/values-dev.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json

Les pods utilisent imagePullPolicy: Always en dev

En mode k3d dev, les images personnalisées utilisent pullPolicy: Always, donc les pods récupèrent automatiquement les nouvelles images au redémarrage. Pour déclencher un rollout après avoir poussé de nouvelles images :

kubectl rollout restart deploy/<nom-du-service> -n akko

Épinglage des versions

Chaque image Docker utilise un tag de version explicite. Il n'y a aucun tag latest dans le chart Helm. Cela garantit des déploiements reproductibles et rend explicite les versions exactes utilisées.

L'affichage Tech Stack du cockpit est généré dynamiquement par scripts/generate-versions.sh, qui écrit branding/cockpit/versions.json.

./scripts/generate-versions.sh

Séquence de démarrage

La méthode recommandée pour démarrer AKKO est le script d'entrée :

./scripts/start.sh [--governance]

Ce script exécute les étapes suivantes dans l'ordre :

  1. Générer les secrets -- exécute generate-secrets.sh (ignoré si .env existe)
  2. Générer les certificats TLS -- exécute generate-certs.sh (ignoré si les certificats existent)
  3. Créer la base Keycloak -- démarre PostgreSQL, crée la base keycloak si absente
  4. Construire les images personnalisées -- construit akko-postgres, akko-spark, akko-notebook
  5. Générer le manifeste des versions -- exécute generate-versions.sh
  6. Déployer avec Helm -- exécute helm install akko helm/akko/ -n akko --create-namespace -f helm/examples/values-dev.yaml --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json
  7. Afficher les URL -- affiche les URL de tous les services

Les sidecars d'initialisation (postgres-init, polaris-init, minio-init, superset-init) s'exécutent automatiquement via depends_on et sont idempotents -- ils créent les bases de données, catalogues, buckets et tableaux de bord uniquement s'ils n'existent pas déjà.