Aller au contenu

Installation

Lancez AKKO sur votre machine locale en moins de 10 minutes avec Helm et k3d.

Prérequis

Avant de commencer, assurez-vous d'avoir les outils suivants installés :

Outil Version minimum Fonction
Docker Desktop 4.30+ Runtime de conteneurs (ou containerd sur Linux)
kubectl 1.28+ CLI Kubernetes
Helm 3.14+ Gestionnaire de packages pour Kubernetes
k3d 5.6+ Kubernetes local léger (encapsule k3s)
Git 2.30+ Cloner le dépôt
OS -- macOS (ARM ou Intel) ou Linux

Tout installer sur macOS

brew install kubectl helm k3d git

Sur Linux, suivez les instructions d'installation officielles de chaque outil ou utilisez le gestionnaire de paquets de votre distribution.

Configuration système requise

Ressource Minimum Recommandé
RAM 8 Go 16 Go (requis pour le profil governance)
Mémoire Docker 8 Go 16 Go
Disque 20 Go 40 Go (images + volumes persistants)
CPU 4 cœurs 8 cœurs

Mémoire Docker Desktop

L'allocation mémoire par défaut de Docker Desktop (2 Go) n'est pas suffisante. Allez dans Docker Desktop > Settings > Resources et définissez la mémoire à au moins 8 Go pour les services de base, ou 16 Go si vous prévoyez d'activer le profil governance (OpenMetadata + OpenSearch).

Installation rapide

Deux commandes pour passer de zéro à une plateforme de données souveraine pleinement opérationnelle :

1. Cloner le dépôt

git clone https://github.com/AKKO-p/AKKO.git akko && cd akko

2. Déployer AKKO

bash helm/scripts/deploy.sh

Le script de déploiement crée le cluster k3d, construit les 12 images personnalisées, les importe, génère les secrets, et exécute l'installation Helm complète avec tous les fichiers de valeurs requis (values-dev.yaml, values-domain.yaml, values-dev-secrets.yaml) et le realm Keycloak.

Le premier déploiement prend du temps

Le tout premier lancement télécharge environ 15 Go d'images de conteneurs et construit 12 images personnalisées. Les déploiements suivants sont bien plus rapides puisque les images sont en cache. Comptez 10 à 15 minutes au premier lancement selon votre connexion internet.

Vérifier l'installation

Vérifier l'état des pods

kubectl get pods -n akko

Tous les pods devraient atteindre le statut Running ou Completed dans les 2 à 3 minutes. Vous devriez voir 25+ pods.

Ouvrir le cockpit

Naviguez vers :

https://akko.local

Le cockpit est le portail central. Il affiche des cartes d'état de santé pour chaque service. Toutes les cartes devraient passer au vert dans les 1 à 2 minutes suivant le démarrage.

URLs des services

Tous les services sont accessibles via des sous-domaines *.akko.local via l'ingress Traefik :

Service URL
Cockpit https://akko.local
JupyterHub https://lab.akko.local
Superset https://bi.akko.local
Airflow https://orchestrator.akko.local
Trino https://federation.akko.local
Interface Spark https://compute.akko.local
Console stockage objet https://storage.akko.local
Dashboards https://metrics.akko.local
Prometheus https://prometheus.akko.local
Ollama https://ollama.akko.local
Polaris https://polaris.akko.local
Keycloak https://identity.akko.local
Traefik https://traefik.akko.local
AKKO Docs https://docs.akko.local
OpenMetadata https://catalog.akko.local (governance)

Configuration de domaine personnalisé

Par défaut, AKKO utilise *.akko.local. Pour utiliser un domaine personnalisé, exécutez le script de génération de domaine :

bash helm/scripts/generate-domain-values.sh monentreprise.internal

Cela génère values-domain.yaml et realm-domain.json avec toutes les URLs mises à jour. Puis redéployez :

bash helm/scripts/deploy.sh

Toutes les règles d'ingress, les URIs de redirection Keycloak, et les URLs de services seront automatiquement mises à jour vers *.monentreprise.internal.

Résolution DNS

Pour le développement local, ajoutez des entrées dans /etc/hosts :

echo '127.0.0.1 akko.local cockpit.akko.local identity.akko.local lab.akko.local bi.akko.local orchestrator.akko.local federation.akko.local compute.akko.local minio.akko.local polaris.akko.local grafana.akko.local prometheus.akko.local catalog.akko.local docs.akko.local experiments.akko.local ollama.akko.local traefik.akko.local' | sudo tee -a /etc/hosts

Alternativement, utilisez un outil DNS wildcard comme dnsmasq pour résoudre tous les sous-domaines *.akko.local.

Certificats TLS

Auto-signé (par défaut)

AKKO génère un certificat auto-signé wildcard pour *.akko.local lors du déploiement. Ceci convient au développement local et aux environnements isolés.

Apporter votre propre certificat

Pour utiliser votre propre certificat TLS, créez un Secret Kubernetes et référencez-le dans vos valeurs :

kubectl create secret tls akko-tls \
  --cert=chemin/vers/tls.crt \
  --key=chemin/vers/tls.key \
  -n akko

# surcharge de valeurs
global:
  tls:
    secretName: akko-tls

cert-manager (production)

Pour les déploiements en production avec des certificats Let's Encrypt automatiques, installez cert-manager et configurez un ClusterIssuer. Consultez le guide Déploiement Kubernetes pour des instructions détaillées.

Safari et les certificats auto-signés

Comme AKKO utilise des certificats TLS auto-signés pour le développement local, Safari (et les autres navigateurs) afficheront un avertissement de sécurité lors de la première visite.

Approuver le certificat sur macOS

Pour éviter les avertissements répétés dans Safari :

  1. Exportez le certificat depuis le cluster : 
    kubectl get secret akko-tls -n akko -o jsonpath='{.data.tls\.crt}' | base64 -d > akko.crt
  2. Ouvrez Trousseau d'accès (Keychain Access)
  3. Glissez akko.crt dans le trousseau Système
  4. Double-cliquez sur le certificat importé
  5. Développez Confiance et réglez Lors de l'utilisation de ce certificat sur Toujours approuver
  6. Fermez et redémarrez Safari

Dans Chrome ou Firefox, vous pouvez simplement cliquer sur « Avancé » puis « Continuer » sur chaque domaine *.akko.local.

Profil Governance

Pour activer OpenMetadata (catalogue de données) et OpenSearch, mettez à jour avec les flags governance :

helm upgrade akko helm/akko/ \
  -f helm/examples/values-dev.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json \
  --set openmetadata.enabled=true \
  --set akko-opensearch.enabled=true

Le profil governance nécessite 16 Go+

OpenMetadata Server (~1 Go) + OpenSearch (~512 Mo heap + mémoire native) provoqueront des redémarrages OOM si Docker Desktop est configuré avec moins de 16 Go de RAM.

Désinstallation

Supprimer le release AKKO :

helm uninstall akko -n akko

Pour supprimer également toutes les données persistantes (réinitialisation complète) :

helm uninstall akko -n akko
kubectl delete pvc --all -n akko

Pour supprimer entièrement le cluster k3d :

k3d cluster delete akko

Problèmes courants

Conflits de port sur 80 ou 443

k3d mappe les ports 80 et 443 du cluster vers votre hôte. Si un autre processus (Apache, Nginx, un autre cluster k3d) utilise ces ports, la création du cluster échouera. Vérifiez avec :

lsof -i :80
lsof -i :443

Arrêtez le processus en conflit avant d'exécuter k3d-create.sh.

Pods bloqués en Pending ou CrashLoopBackOff

Vérifiez les événements du pod pour plus de détails :

kubectl describe pod <nom-du-pod> -n akko
kubectl logs <nom-du-pod> -n akko

Causes courantes : mémoire insuffisante (augmentez l'allocation Docker Desktop), erreurs de téléchargement d'images (relancez build-images.sh), ou PVCs manquants.

Erreurs mémoire Docker ou OOM kills

Si des services redémarrent en boucle, vérifiez l'allocation mémoire de Docker Desktop. Les workers Spark et OpenMetadata sont gourmands en mémoire. Augmentez à 8 Go minimum (16 Go pour le profil governance).

kubectl ne peut pas se connecter au cluster

Assurez-vous que votre kubeconfig pointe vers le cluster k3d :

kubectl config use-context k3d-akko
kubectl cluster-info

Si le cluster a été supprimé, recréez-le avec k3d-create.sh.

Prochaines étapes