Aller au contenu principal

Installation

Guides pas à pas par méthode (Kubernetes avec Helm, paquets OS, Docker Compose, make, site déconnecté) : Installer la Navin Platform.

1. Pile locale (Docker Compose)​

cd deploy/compose
cp .env.example .env        # remplacer toutes les valeurs CHANGE_ME_ (openssl rand -hex 32)
docker compose config -q
docker compose up -d
docker compose --profile gpu up -d vllm        # option GPU NVIDIA
docker compose --profile ollama up -d ollama   # option CPU

Le service migrate exécute python -m eai.migrate avant le démarrage du control plane. Keycloak importe le realm enterprise-ai depuis deploy/keycloak/realm-enterprise-ai.json. OPA charge le bundle deploy/policies/opa. seaweedfs-init crée par l'API S3 de SeaweedFS le bucket WORM eai-audit-worm (object lock, mode COMPLIANCE), eai-artifacts et opik.

Premier compte du portail : EAI_BOOTSTRAP_ADMIN_USERNAME et EAI_BOOTSTRAP_ADMIN_PASSWORD de .env (navin / navin par défaut). Le control plane le crée au premier démarrage sur le tenant EAI_BOOTSTRAP_TENANT avec les rôles platform_admin et tenant_admin ; à la première connexion (http://localhost:3300, onglet Identifiant), le portail impose un nouveau mot de passe et le mot de passe d'installation cesse de fonctionner. Un redémarrage ne réinitialise jamais ce compte. En Kubernetes, mettez ces deux variables dans le secret du control plane le temps de la première connexion, puis retirez-les. En production (EAI_ENVIRONMENT=prod), le control plane refuse de démarrer avec un mot de passe d'installation faible (navin, l'identifiant, moins de 12 caractères, sans lettres et chiffres) : choisissez une valeur forte et à usage unique.

Le Makefile de la racine du dépôt propose les mêmes opérations : make docker-env (fichier .env avec des secrets locaux aléatoires), make docker-start ou make <service>-start service par service, make docker-status, make <service>-logs. Voir le README (README.md).

Charger le modèle OpenFGA :

fga store create --name enterprise-ai --api-url http://localhost:8082
fga model write --store-id <id> --file deploy/policies/openfga/model.fga
python3 tools/policies/fga_build.py --check

2. Kubernetes on-prem avec GPU (Helm + Argo CD)​

Prérequis : Kubernetes >= 1.27, nœuds GPU NVIDIA étiquetés, stockage CSI, un S3 compatible (Ceph RGW, SeaweedFS ou le stockage objet de votre infrastructure), Harbor.

  1. Socle (opérateurs) avec OpenTofu/Terraform : 
    cd deploy/terraform/envs/onprem-gpu
    tofu init -backend-config=backend.hcl
    tofu plan -var kube_context=<contexte-dedie>
    tofu apply
    Installe namespaces, Cilium (WireGuard, mutual auth SPIRE), cert-manager, GPU Operator + DCGM, KEDA, Kyverno, CloudNativePG, Velero, Argo CD.
  2. OpenBao : déployer puis deploy/openbao/bootstrap.sh (KV v2, transit, auth kubernetes, politiques).
  3. SPIRE : deploy/spire/server.conf, agent.conf, registration-entries.yaml.
  4. GitOps : kubectl apply -f deploy/argocd/appproject.yaml -f deploy/argocd/repository-toolhive.yaml -f deploy/argocd/applicationset.yaml (repository-toolhive.yaml déclare le registre OCI des charts ToolHive, voir mcp-runtime.md). Les vagues de synchronisation appliquent infra (-3), données (-2), plateforme (-1), applications (0).
  5. Chart applicatif (sans Argo CD) : 
    helm dependency build deploy/helm/enterprise-ai
    helm upgrade --install enterprise-ai deploy/helm/enterprise-ai -n enterprise-ai \
      -f deploy/helm/enterprise-ai/values-prod.yaml -f deploy/helm/enterprise-ai/values-onprem-gpu.yaml
    Chaque entrée de vllm.models crée un Deployment vLLM (limite nvidia.com/gpu, nodeSelector, tolerations) et un ScaledObject KEDA sur vllm:num_requests_waiting.

3. Installation air-gapped (miroir Harbor)​

  1. Sur une machine connectée, lister les images : helm template ... | grep image: | sort -u plus les images des opérateurs.
  2. Copier vers Harbor : skopeo copy --all docker://vllm/vllm-openai:v0.33.0 docker://<harbor-host>/mirror/vllm/vllm-openai:v0.33.0 (idem pour chaque image), vérifier les signatures cosign et re-signer avec la clé interne (politique Kyverno key-based-mirror).
  3. Charts : helm pull puis helm push <chart>.tgz oci://<harbor-host>/charts. Positionner helm_repository_mirror (Terraform) et global.imageRegistry (Helm).
  4. Modèles : télécharger les poids (Hugging Face) hors ligne, les copier sur le PVC de cache (HF_HUB_OFFLINE=1 est forcé dans les pods vLLM).
  5. Base de vulnérabilités Trivy : trivy --download-db-only puis transfert de ~/.cache/trivy.
  6. Désactiver tout egress fournisseur (ne pas activer les étiquettes eai.io/provider-*) ; seuls les modèles locaux restent disponibles.

Déploiement GitOps (Argo CD)​

Un cluster Kubernetes par environnement (dev, staging, prod). Le module Terraform deploy/terraform/modules/platform-bootstrap installe le socle (Cilium, cert-manager, Kyverno, KEDA, CloudNativePG, Velero, opérateur GPU, Argo CD). Il crée aussi tous les namespaces de la plateforme avec leur niveau Pod Security, puis enregistre le cluster local dans Argo CD avec le label eai.io/environment (secret cluster-in-cluster du namespace argocd).

Argo CD installe ensuite tout le reste depuis ce dépôt : deploy/argocd/applicationset.yaml génère une Application par composant pour chaque cluster enregistré avec ce label. L'ApplicationSet n'active pas CreateNamespace : les namespaces viennent du module Terraform et de deploy/cilium/namespaces.yaml, avec leur niveau Pod Security. Un composant dont le namespace manque échoue au lieu de s'installer sans ce niveau. Tous les environnements utilisent values-prod.yaml (les services tiers tournent avec les mêmes valeurs TLS partout) ; les tags d'images propres à chaque environnement viennent de deploy/gitops/<env>/image-tags.yaml.

Couche (eai.io/layer)Composants
infrapolitiques Cilium et Kyverno, émetteurs cert-manager, KEDA, Velero, External Secrets, kube-prometheus-stack (CRD du Prometheus Operator), SPIRE, CRD ToolHive
dataOpenBao, PostgreSQL (CloudNativePG), Redis, NATS, Qdrant, Temporal, ClickHouse, Keycloak, OpenFGA, OPA
platformAPISIX, LiveKit, Grafana Alloy, OpenTelemetry Collector, OpenSearch (journaux et Security Analytics), Jaeger, Opik, règles d'alerte, ToolHive Operator (Runtime MCP, mcp-runtime.md)
appschart deploy/helm/enterprise-ai (Control Plane, portail, workers, LiteLLM, vLLM)

Chaque chart tiers est épinglé à une version exacte dans l'ApplicationSet. Ses valeurs viennent du dépôt, et l'en-tête de chaque fichier de valeurs indique le dépôt, le chart et la version. Toutes les images viennent du miroir Harbor (<harbor-host>/mirror/...) avec un tag exact.

Prérequis avant la première synchronisation

  1. Miroir Harbor alimenté avec les images de tous les fichiers de valeurs. En mode déconnecté, publiez aussi les charts dans <harbor-host>/charts (déjà autorisé par l'AppProject) et remplacez repo dans l'ApplicationSet.
  2. Secrets dans OpenBao, synchronisés par External Secrets : les noms et les clés attendus sont documentés en tête de chaque fichier de valeurs. Inventaire complet et ordre d'amorçage : secrets.md.
  3. Stockage objet compatible S3 de votre infrastructure (Ceph RGW ou toute API S3), joignable en HTTPS : remplacez <s3-host> dans EAI_S3_ENDPOINT, networkSecurity.objectStorageFQDNs (deploy/helm/enterprise-ai/values.yaml), les valeurs Opik (pièces jointes), Velero et la sauvegarde CloudNativePG. SeaweedFS ne tourne que dans la pile docker compose.

Installation

# 1. Socle, une fois par cluster : module platform-bootstrap avec environment = dev, staging ou prod
terraform init && terraform apply
# 2. Projet Argo CD et ApplicationSet
kubectl -n argocd apply -f deploy/argocd/appproject.yaml -f deploy/argocd/repository-toolhive.yaml -f deploy/argocd/applicationset.yaml

En dev et staging, la synchronisation est automatique. Une ressource dont la CRD ou le namespace vient d'une couche précédente est réessayée (10 tentatives, attente jusqu'à 10 minutes), jusqu'à convergence. À la première installation, OpenBao démarre scellé : initialisez-le dès qu'il tourne (docs/operations/secrets.md) ; les secrets et les pods qui en dépendent suivent d'eux-mêmes.

En prod, la synchronisation est manuelle, couche après couche :

argocd app sync -l eai.io/environment=prod,eai.io/layer=infra
argocd app wait -l eai.io/environment=prod,eai.io/layer=infra --health --timeout 1800
argocd app sync -l eai.io/environment=prod,eai.io/layer=data
# Première installation : OpenBao démarre scellé. Initialisez-le et descellez-le, lancez
# deploy/openbao/bootstrap.sh puis écrivez les entrées de docs/operations/secrets.md.
argocd app wait -l eai.io/environment=prod,eai.io/layer=data --health --timeout 1800
for layer in platform apps; do
  argocd app sync -l eai.io/environment=prod,eai.io/layer=$layer
  argocd app wait -l eai.io/environment=prod,eai.io/layer=$layer --health --timeout 1800
done

La fenêtre de gel de l'AppProject (du vendredi 18 h, pendant 62 h) bloque les synchronisations automatiques de prod ; une synchronisation manuelle reste possible.

Avec un Argo CD central qui gère plusieurs clusters, enregistrez chaque cluster avec son environnement (argocd cluster add <contexte> --label eai.io/environment=<env>) et ajoutez son adresse dans destinations de deploy/argocd/appproject.yaml.