Aller au contenu principal

Manuel d'installation client (bundle de release signé)

Ce manuel décrit l'installation d'Enterprise AI à partir du bundle de release signé et reproductible, y compris sur un site sans accès Internet. Chaque commande ci-dessous a été exécutée sur la machine de build ; les limites sont indiquées à la fin. Version anglaise : docs/operations/en/installation-handbook.md. Notes de version de la même version : docs/release/RELEASE_NOTES-<version>.md.

1. Outils de release (machine connectée)​

bash tools/oci/fetch.sh                 # cosign 2.6.5, trivy, kubeconform, kyverno (sha256 vérifiés)
bash tools/components/fetch-syft.sh     # syft 1.55.0
bash tools/release/fetch-tools.sh       # gitea 28.2.0, act_runner 5.2.4, Tekton v1.18.0, chart Harbor 1.19.4, schémas

Toutes les versions sont épinglées et chaque fichier est vérifié par sha256 (somme publiée par le projet amont, ou empreinte figée dans le script pour les fichiers sans somme publiée).

2. Construire le bundle​

bash tools/release/build.sh                 # /tmp/eai-release/<version>/ et release/manifests/<version>.json
bash tools/release/verify-reproducible.sh   # deux constructions, comparaison de chaque sha256
bash tools/release/sign.sh                  # SBOM Syft par artefact, signatures Cosign, scans Trivy et verdict

Le bundle contient : chart Helm empaqueté, manifestes rendus (values, values-prod, values-onprem-gpu), manifestes plateforme (Argo CD, Kyverno, KEDA, Velero, Tekton, Harbor), migrations SQL, documentation hors ligne, wheels et sdists Python (control plane et SDK), paquets npm du SDK TypeScript, archive source du module Go, jars Java, paquets RPM et DEB de navin-manager, packs, SBOM des composants, notices de licence et manifeste de verrouillage.

Reproductibilité : SOURCE_DATE_EPOCH (1700000000 par défaut), entrées tar triées, propriétaire 0:0, dates fixes, en-têtes gzip sans date ni nom, sources copiées dans un répertoire temporaire. verify-reproducible.sh affiche compared 36 artefacts, 0 differences.

Signatures : sign.sh génère une paire de clés Cosign sous /tmp/eai-release-keys (variable EAI_SIGN_KEY_DIR, jamais versionnée) et signe manifest.json, chaque artefact et chaque SBOM (cosign sign-blob, sans journal de transparence). En production, la clé de signature est celle du client (HSM ou OpenBao), pas une clé de test.

Verdict Trivy : sign.sh s'arrête en erreur si un résultat HIGH ou CRITICAL n'est pas justifié dans tools/release/trivy-exceptions.yaml (champs id, justification, owner). Le verdict est écrit dans scans/gate.json.

3. Transfert et vérification sur le site isolé​

Copier le répertoire du bundle (support amovible), puis :

bash tools/release/verify.sh /chemin/du/bundle                   # sha256, signatures, SBOM et verdict Trivy
bash tools/release/verify.sh --integrity-only /chemin/du/bundle  # sha256, signatures et SBOM seulement

La clé publique utilisée par défaut est cosign.pub du bundle ; passer en second argument la clé publique reçue par un autre canal pour une vérification indépendante.

4. Preuve d'installation sans réseau​

navin-manager/server/.venv/bin/python navin-manager/packaging/offline/build-bundle.py \
    --out /tmp/eai-airgap/mirror --services opa --methods binary --skip-agent --bundle /tmp/eai-airgap/bundle.tar
bash tools/release/airgap-check.sh /tmp/eai-release/1.0.0 /tmp/eai-airgap/bundle.tar release/airgap/<date>.json

airgap-check.sh se relance dans unshare -rn (espace de noms réseau vide, seule l'interface lo existe), vérifie qu'une connexion TCP vers 1.1.1.1:443 et une résolution DNS échouent, puis vérifie le bundle signé, vérifie et extrait le miroir navin-manager, exécute un binaire du miroir, installe les wheels avec pip --no-index, rend le chart empaqueté et extrait les migrations SQL. La preuve est écrite dans release/airgap/<date>.json.

5. Validation hors ligne des contrôles du cluster​

helm template eai deploy/helm/enterprise-ai -f deploy/helm/enterprise-ai/values-prod.yaml > /tmp/r-values-prod.yaml
KUBECONFIG=/tmp/eai-nokube/config HOME=/tmp/eai-nokube /tmp/toolchains/kyverno apply \
    deploy/policies/kyverno/cluster-policies.yaml deploy/policies/kyverno/pod-network-security.yaml \
    --resource /tmp/r-values-prod.yaml
/tmp/toolchains/kubeconform -strict -summary \
    -schema-location '/tmp/toolchains/kube-schemas/{{.ResourceKind}}{{.KindSuffix}}.json' \
    -schema-location '/tmp/toolchains/kube-schemas/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
    /tmp/r-values-prod.yaml deploy/keda deploy/velero deploy/argocd deploy/cilium deploy/tekton
helm lint /tmp/toolchains/release-dl/harbor-1.19.4.tgz -f deploy/harbor/values.yaml

Important : lancer Kyverno avec un KUBECONFIG vide. Sans cela, la règle de vérification des signatures d'images essaie de lire la clé publique dans le cluster du contexte courant.

6. Intégration continue locale (Gitea et act_runner)​

bash tools/ci/gitea-local.sh   # Gitea sur un port libre, SQLite sous /tmp, runner hôte, preuve release/ci-runs/<date>.json

Limites​

  • Les effets d'exécution sur un cluster (contrôleur Tekton, Harbor, envoi et récupération d'images, Kyverno en admission, Cilium, KEDA, HPA, Velero sauvegarde et restauration, synchronisation Argo CD) exigent un cluster de recette : non vérifiés ici.
  • La preuve sans réseau couvre la vérification du bundle, le miroir navin-manager et l'installation des wheels sans dépendances (--no-deps) ; les dépendances Python tierces viennent du wheelhouse navin-manager (--methods python), non inclus dans cette preuve.
  • Les valeurs values-onprem-gpu.yaml utilisent des images sans empreinte (vllm-openai:v0.33.0) refusées par la politique Kyverno eai-verify-image-signatures.