Installation client — AKKO sur votre propre cluster Kubernetes¶

Cette page est le guide canonique d'installation pour les clients et partenaires qui font tourner AKKO sur leur propre cluster Kubernetes. Elle cible le chemin une-commande install-akko-client.sh : un script unique transforme un cluster fraîchement provisionné en une plateforme AKKO complète sous un seul domaine wildcard.

Public visé : ingénieurs plateforme, SRE et administrateurs qui possèdent le cluster cible. Budget temps : 30 minutes en main, plus 10 à 25 minutes d'attente automatisée pendant que les pods démarrent.

Résumé en cinq commandes

git clone https://github.com/AKKO-p/AKKO && cd AKKO
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=180s deployment --all -n cert-manager
# Option A — production : le client apporte son propre AD/LDAP
bash helm/scripts/install-akko-client.sh --domain=monentreprise.example \
  --customer-values=values-monentreprise.yaml
# Option B — démo / PoC : LLDAP intégré avec 50 personas
bash helm/scripts/install-akko-client.sh --domain=monentreprise.example --with-demo-ldap
kubectl -n akko get pods

1. Pré-requis¶

Le script applique les contrôles de pré-vol (Phase 1) et s'arrête avec un message explicite si l'un des éléments ci-dessous manque. Provisionnez-les d'abord.

1.1 Cluster¶

Exigence	Minimum	Notes
API Kubernetes	1.28+	Testé sur 1.28 à 1.30. EKS / GKE / AKS / OVHcloud Managed / OpenShift 4.14+ / kubeadm vanilla / k3s / k3d tous supportés.
Workers	2 nœuds	1 nœud fonctionne pour le dev mais ne laisse aucune capacité de réserve.
CPU par worker	8 vCPU	4 vCPU minimum, mais Spark / Trino / OpenMetadata seront en queue.
Mémoire par worker	32 Go	24 Go minimum. OpenMetadata + OpenSearch consomment à eux seuls 2,5 Go.
Runtime de conteneurs	containerd 1.7+ ou CRI-O 1.28+	Le shim Docker n'est plus supporté par Kubernetes amont.
Architecture	amd64 ou arm64	Clusters Apple Silicon supportés. Toutes les images custom sont multi-arch.

1.2 Stockage¶

Exigence	Détail
StorageClass par défaut	L'une doit porter l'annotation `storageclass.kubernetes.io/is-default-class=true`. Le pré-vol émet un avertissement si elle manque.
Mode du provisionneur	`ReadWriteOnce` suffit — chaque PVC est lié à un seul pod.
Expansion de volume	Recommandée (`allowVolumeExpansion: true`) pour pouvoir agrandir Postgres sans snapshot.
Marge de capacité	200 Go cluster-wide pour une démo, 1 To+ en production.

Un driver CSI managé (gp3 sur EKS, pd-balanced sur GKE, premium-LRS sur AKS, Longhorn sur bare-metal) fonctionne d'emblée.

1.3 Réseau¶

Exigence	Détail
Contrôleur d'ingress	Traefik 2 (déployé par le chart) ou votre propre contrôleur. Si vous fournissez le vôtre, désactivez le Traefik bundle via `traefik.enabled=false` et pointez un wildcard `*.<domaine>` sur votre LoadBalancer.
DNS wildcard	Un enregistrement `*.<domaine>` A ou CNAME pointant sur l'ingress du cluster.
Sortie HTTPS	Le cluster doit pouvoir joindre le registre choisi (mirror Harbor ou Docker Hub / GHCR). Les installations air-gapped sont documentées séparément dans le guide d'administration.
TLS	cert-manager 1.14+ avec un `ClusterIssuer` opérationnel. Le pré-vol émet un avertissement quand cert-manager manque.

1.4 Outillage CLI sur l'hôte d'installation¶

Outil	Minimum	Installation
`helm`	3.14	`brew install helm` ou votre gestionnaire de paquets
`kubectl`	1.28	`brew install kubectl`
`git`	n'importe	`apt install git` / `brew install git`
`openssl`	1.1 ou 3.x	préinstallé sur Linux et macOS
`bash`	4+	macOS livre 3.2 — installez le bash GNU via Homebrew si vous exécutez depuis un Mac

Vérifiez avec :

helm version --short
kubectl version --client
bash --version

Sortie attendue : helm renvoie v3.14.x+, kubectl renvoie v1.28.x+, bash renvoie 4.x ou 5.x.

2. Configuration du fournisseur d'identité¶

Le sprint 61.1 (ADR-045) découpe AKKO en trois périmètres. Savoir lequel est lequel détermine la façon dont vous configurez l'authentification utilisateur.

+----------------------------+---------------------------+--------------------------+
| Périmètre                  | Namespace                 | Propriétaire             |
+----------------------------+---------------------------+--------------------------+
| Cœur AKKO                  | akko                      | AKKO le livre            |
|                            |                           | (ce chart umbrella)      |
| Identité (LDAP / AD)       | <choix client>            | LE CLIENT apporte son AD |
| Sources de données         | <choix client>            | LE CLIENT apporte ses BD |
+----------------------------+---------------------------+--------------------------+

Le chart cœur AKKO ne livre JAMAIS de serveur LDAP. Les installations en production fédèrent Keycloak sur l'AD / OpenLDAP / 389DS / Microsoft Entra ID existant du client. Deux modes d'installation sont supportés.

2.1 Option A — Le client apporte son AD / LDAP (production)¶

À utiliser quand vous faites tourner AKKO au-dessus d'un annuaire d'entreprise existant. Pré-requis :

Élément	Détail
Endpoint LDAP joignable	`ldap://` (port 389) ou `ldaps://` (port 636) joignable depuis le namespace `akko`. Ouvrez la `EgressNetworkPolicy` ou la règle de pare-feu correspondante.
Compte de service	Un bind DN avec accès lecture seule au sous-arbre des utilisateurs. Ne réutilisez jamais un DN admin humain.
Accès lecture seule	Keycloak opère la fédération en mode `READ_ONLY` par défaut. AKKO n'écrit jamais dans l'annuaire client.
Mapping groupe → rôle	Le client publie les groupes AD/LDAP qui doivent accorder l'accès à chaque rôle plateforme AKKO.

Étape 1 — Préparer le mot de passe de bind LDAP. Le script d'installation propose deux options ; choisissez-en une.

Option 1.a — --ldap-bind-pwd-file (recommandée, Sprint 119). Écrivez le mot de passe de bind dans un fichier mono-ligne en mode 0600 puis passez son chemin au script. Le script crée le Secret akko-keycloak-bind dans le namespace akko avant helm install, et le pré-flight vérifie que le fichier n'est pas vide.

# 1. Écrire le mot de passe dans un fichier sécurisé (chmod 0600).
umask 077
printf '%s' '<votre-mot-de-passe-de-bind-LDAP>' > /tmp/akko-ldap-bind.txt

# 2. Passer le fichier via le nouveau flag (voir Étape 3 ci-dessous).
#    Le script crée le Secret akko/akko-keycloak-bind pour vous.

Option 1.b — créer le Secret manuellement. Utile lorsque vous gérez les credentials via Sealed Secrets, External Secrets Operator, Vault, etc.

kubectl create namespace akko --dry-run=client -o yaml | kubectl apply -f -
kubectl -n akko create secret generic akko-keycloak-bind \
  --from-literal=bind-password='<votre-mot-de-passe-de-bind-LDAP>'

Les deux chemins fonctionnent ; le chart a juste besoin que le Secret existe au moment où le hook post-install User Federation s'exécute. Le pré-flight Sprint 119 INTERROMPT l'installation avec un message de remédiation clair si userFederation.enabled: true est défini dans --customer-values mais qu'aucune des deux options ci-dessus n'a été appliquée.

Étape 2 — Copier le template de valeurs client et décommenter / remplir le bloc akko-keycloak.userFederation :

cp helm/examples/values-customer-template.yaml values-monentreprise.yaml
$EDITOR values-monentreprise.yaml

Exemple Active Directory :

akko-keycloak:
  userFederation:
    enabled: true
    provider: ldap
    vendor: ad
    displayName: corp-ad
    url: "ldaps://dc01.corp.local:636"
    bindDn: "CN=svc-keycloak,OU=Service Accounts,DC=corp,DC=local"
    bindCredentialSecret:
      name: akko-keycloak-bind
      key: bind-password
    baseDn:  "DC=corp,DC=local"
    usersDn: "CN=Users,DC=corp,DC=local"
    customUserSearchFilter: "(&(objectclass=user)(!(objectclass=computer)))"
    uuidLDAPAttribute: "objectGUID"
    usernameLDAPAttribute: "sAMAccountName"
    userObjectClasses: "user"
    editMode: READ_ONLY
    syncRegistrations: false
    importEnabled: true
    fullSyncPeriod: 86400
    changedSyncPeriod: 300
    compositeMappings:
      - { childRole: "DataPlatformAdmins", parentRole: "akko-admin"    }
      - { childRole: "DataEngineers",      parentRole: "akko-engineer" }
      - { childRole: "BusinessAnalysts",   parentRole: "akko-analyst"  }
      - { childRole: "DataStewards",       parentRole: "akko-steward"  }
      - { childRole: "ReadOnlyConsumers",  parentRole: "akko-viewer"   }

Exemple OpenLDAP / 389DS :

akko-keycloak:
  userFederation:
    enabled: true
    vendor: other
    url: "ldap://ldap.corp.internal:389"
    bindDn: "cn=keycloak,ou=services,dc=corp,dc=internal"
    bindCredentialSecret:
      name: akko-keycloak-bind
      key: bind-password
    baseDn:  "dc=corp,dc=internal"
    usersDn: "ou=people,dc=corp,dc=internal"
    customUserSearchFilter: "(objectclass=inetOrgPerson)"
    uuidLDAPAttribute: "entryUUID"
    usernameLDAPAttribute: "uid"
    userObjectClasses: "inetOrgPerson"
    editMode: READ_ONLY

Microsoft Entra ID (Azure AD) ne se câble pas via User Federation — c'est un IdP OIDC. Câblez-le via les Identity Providers Keycloak (chemin Entra du Sprint 61.4, voir docs/admin/external-idp.md). La surface valeurs est akko-keycloak.identityProviders[], pas userFederation.

Étape 3 — Lancer l'installation. Si vous avez utilisé Option 1.a (--ldap-bind-pwd-file), passez le flag en ligne de commande pour que le script crée le Secret en Phase 3c :

bash helm/scripts/install-akko-client.sh \
  --domain=monentreprise.example \
  --customer-values=values-monentreprise.yaml \
  --ldap-bind-pwd-file=/tmp/akko-ldap-bind.txt

Si vous avez utilisé Option 1.b (Secret déjà créé), omettez --ldap-bind-pwd-file ; le pré-flight détecte le Secret akko/akko-keycloak-bind existant et continue :

bash helm/scripts/install-akko-client.sh \
  --domain=monentreprise.example \
  --customer-values=values-monentreprise.yaml

Le pré-vol détecte le bloc userFederation et saute l'avertissement « pas d'IdP ». La vérification smoke en fin d'installation exerce la redirection cockpit → Keycloak.

2.2 Option B — LLDAP de démo intégré (essayer AKKO sans AD)¶

À utiliser pour les PoC, journées démo, ateliers d'onboarding, évaluations internes. Le chart standalone helm/akko-demo-ad provisionne LLDAP dans son propre namespace (akko-demo-ad) avec 50 personas répartis sur 4 unités organisationnelles et 5 rôles plateforme AKKO.

bash helm/scripts/install-akko-client.sh \
  --domain=akko.dev \
  --with-demo-ldap

Le script :

Installe helm/akko-demo-ad dans le namespace akko-demo-ad avec des mots de passe admin + utilisateurs aléatoires.
Mirroring du mot de passe admin de démo dans akko/akko-demo-ad-federation pour que la User Federation Keycloak se binde avec succès.
Installe l'umbrella AKKO avec l'overlay userFederation de démo pré-câblé dans values-netcup.yaml (ou tout autre overlay que vous empilez par-dessus).

Personas de référence (le suffixe correspond au rôle plateforme AKKO) :

Utilisateur	Prénom	Nom	Rôle AKKO
`alice_admin`	Alice	Martin	`akko-admin`
`bob_engineer`	Bob	Lefevre	`akko-engineer`
`carol_analyst`	Carol	Petit	`akko-analyst`
`dave_steward`	Dave	Bernard	`akko-steward`
`eve_viewer`	Eve	Dubois	`akko-viewer`

Les mots de passe de login sont aléatoires par install. Lisez-les depuis le Secret demo-ad :

kubectl -n akko-demo-ad get secret akko-demo-ad \
  -o jsonpath='{.data.default-user-password}' | base64 -d

Ou — si vous avez utilisé le mécanisme de mots de passe par utilisateur dans helm/akko-demo-ad/values.yaml bootstrap.userPasswords — utilisez celui que vous avez défini là (le fichier de valeurs canonique de démo livre alice / alice123, bob / bob123, etc., pour la lisibilité en walkthrough live).

N'utilisez jamais --with-demo-ldap en production. Quiconque dispose de l'URL externe du cluster et du mot de passe seed (auto-généré mais découvrable) peut se connecter en tant qu'alice_admin et obtenir akko-admin.

3. Installation en cinq commandes¶

Le dépôt fournit un point d'entrée unique à helm/scripts/install-akko-client.sh. Il déroule neuf phases : pré-vol, valeurs par domaine, génération des secrets, nettoyage optionnel du cluster, helm install --atomic, attente des pods, vérification des Jobs d'init, smoke test, rapport de déploiement.

# Étape 1 — Cloner le dépôt
git clone https://github.com/AKKO-p/AKKO
cd AKKO

# Étape 2 — Installer cert-manager (sauter si déjà présent)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=180s deployment --all -n cert-manager

# Étape 3 — Pointer le DNS wildcard sur l'IP de l'ingress
#   (utilisez votre fournisseur DNS — exemple ci-dessous avec un CNAME fictif)
#   *.monentreprise.example  CNAME  k8s-ingress.monentreprise.example.

# Étape 4 — Lancer l'installation (15 à 25 minutes walltime)
#   Production : se câbler à l'AD du client (voir section 2.1)
bash helm/scripts/install-akko-client.sh --domain=monentreprise.example \
  --customer-values=values-monentreprise.yaml
#   Démo / PoC : LLDAP intégré avec 50 personas (voir section 2.2)
bash helm/scripts/install-akko-client.sh --domain=monentreprise.example --with-demo-ldap

# Étape 5 — Vérifier
kubectl -n akko get pods

Sortie finale attendue de l'étape 4 :

[install-akko] ===== Phase 9/9 — Summary =====
[install-akko]  AKKO platform installed on https://*.monentreprise.example/
[install-akko]  Cockpit       : https://cockpit.monentreprise.example/
[install-akko]  Identity      : https://identity.monentreprise.example/
[install-akko]  Report        : /root/akko-host-config/deployment-report-20260529-150201.md
[install-akko]  Secrets file  : helm/examples/values-dev-secrets.yaml

Le rapport de déploiement généré sous ~/akko-host-config/ contient chaque URL, chaque mot de passe admin et la procédure de troubleshooting. Conservez-le sous permissions restrictives (le script applique 0600).

4. Référence des flags CLI¶

Le script accepte un jeu de flags stable. Aucun n'est positionnel ; seul --domain est obligatoire.

Flag	Type	Défaut	Effet
`--domain=<fqdn>`	requis	—	Domaine wildcard. Chaque URL de service en dérive (`cockpit.<fqdn>`, `identity.<fqdn>`, etc.).
`--namespace=<ns>`	optionnel	`akko`	Namespace Kubernetes. Créé avec `--create-namespace`.
`--release=<name>`	optionnel	`akko`	Nom de release Helm. Utile pour faire tourner plusieurs installations isolées sur le même cluster.
`--chart=<path>`	optionnel	`helm/akko`	Chemin local du chart. Ignoré si `--from-harbor` est positionné.
`--clean`	flag	off	Lance `helm uninstall` puis `kubectl delete ns` AVANT l'installation. À manier avec soin — détruit les données.
`--dry-run`	flag	off	Exécute uniquement `helm template`, sans apply. Utile pour la revue de changement.
`--from-harbor`	flag	off	Récupère le chart OCI depuis Harbor au lieu du système de fichiers local.
`--harbor-url=<url>`	optionnel	`oci://harbor.akko-ai.com/akko-charts/akko`	Surcharge le registre OCI.
`--chart-version=<v>`	optionnel	latest	Épingle une version de chart spécifique lors d'un pull depuis Harbor.
`--no-rollback`	flag	rollback activé	Désactive le rollback automatique lorsque le smoke échoue. À utiliser pendant le débogage pour conserver l'état cassé sur le cluster.
`--skip-preflight`	flag	pré-vol activé	Saute les contrôles de pré-vol de la Phase 1. Non recommandé hors CI.
`--skip-smoke`	flag	smoke activé	Saute le smoke test à cinq endpoints.
`--timeout=<dur>`	optionnel	`30m`	`helm install --timeout`. Augmentez sur les clusters à froid qui doivent télécharger toutes les images en série.
`--secrets-file=<f>`	optionnel	`helm/examples/values-dev-secrets.yaml`	Réutilise un fichier de valeurs secrets existant (production : conservez ce fichier dans Vault / SOPS / SealedSecrets, jamais en git).
`--customer-values=<f>`	optionnel	—	Superpose ce fichier de valeurs client APRÈS la pile standard (priorité la plus élevée). Usage typique : une copie remplie de `helm/examples/values-customer-template.yaml` portant `akko-keycloak.userFederation` et l'issuer OIDC client. Voir section 2.1.
`--with-demo-ldap`	flag	off	Mode DÉMO / PoC : installe le chart standalone `helm/akko-demo-ad` dans son propre namespace AVANT la release principale et crée automatiquement le Secret `akko/akko-demo-ad-federation`. À NE JAMAIS utiliser en production. Voir section 2.2.
`-h`, `--help`	flag	—	Affiche le bloc d'usage embarqué dans le script.

4.1 Codes de sortie¶

Le script termine non nul à la moindre défaillance. Câblez ces codes dans votre signal CI.

Code	Signification
`0`	Installation réussie, tous les endpoints smoke OK.
`1`	Pré-vol échoué (cluster injoignable, pas de StorageClass, etc.).
`2`	`helm install` échoué. Pas de rollback automatique parce que rien n'a été déployé.
`3`	Installation réussie mais smoke test en échec. Rollback automatique sauf si `--no-rollback`.
`4`	Jobs d'initialisation (bootstrap Polaris, import realm Keycloak, seed catalogue) non terminés.
`5`	Arguments CLI invalides.

4.2 Invocations courantes¶

# Installation production sur domaine client, chart tiré depuis Harbor
bash helm/scripts/install-akko-client.sh \
  --domain=acme.cloud \
  --from-harbor \
  --chart-version=2026.05.1 \
  --timeout=45m \
  --secrets-file=/etc/akko/secrets.yaml

# Dry-run pour revue de changement (pas d'apply)
bash helm/scripts/install-akko-client.sh \
  --domain=staging.acme.cloud \
  --dry-run | tee install-plan.txt

# Wipe + réinstall sur un cluster de dev
bash helm/scripts/install-akko-client.sh \
  --domain=akko.dev \
  --clean \
  --no-rollback

5. Personnalisation¶

Le chart est en couches : chaque personnalisation passe par des fichiers de valeurs Helm, jamais par une modification de code.

5.1 Schéma des fichiers de valeurs par couche¶

helm/examples/
├── values-domain.yaml       # généré par generate-domain-values.sh
├── values-dev-secrets.yaml  # généré par install-akko-client.sh
├── values-netcup.yaml       # overlay de production de référence
└── realm-domain.json        # realm Keycloak généré

Pour superposer votre propre overlay de production, déposez un fichier à côté des autres et passez-le explicitement :

bash helm/scripts/install-akko-client.sh \
  --domain=acme.cloud \
  --secrets-file=helm/examples/my-secrets.yaml

helm upgrade akko helm/akko -n akko \
  -f helm/examples/values-netcup.yaml \
  -f helm/examples/values-domain.yaml \
  -f helm/examples/my-secrets.yaml \
  -f helm/examples/my-overrides.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-domain.json

5.2 Réglages courants¶

Besoin	Levier de valeurs
Surcharger la StorageClass par défaut d'un service	`<service>.persistence.storageClass: longhorn`
Épingler le registre d'images (mirror / air-gap)	`global.image.registry: registry.internal/akko`
Désactiver une couche (par ex. retirer IA / ML)	`ollama.enabled: false`, `litellm.enabled: false`, `akko-aden.enabled: false`
Apporter votre propre contrôleur d'ingress	`traefik.enabled: false` et créez vos propres ressources `Ingress`
Apporter votre propre passerelle LLM	`litellm.enabled: false` et `global.llmGateway.url: https://votre-gateway/v1`
Activer l'injection Linkerd par service	`global.serviceMesh.linkerdInject.<svc>: true`
Surcharges de ressources	`<service>.resources.requests.memory: 4Gi`, etc.
Postgres externe pour les services stateful	`<service>.externalDatabase.host: pg.internal`, credentials dans un Secret

5.3 Apportez vos propres secrets¶

En production, ne laissez jamais le script générer les secrets. À la place :

Provisionnez les 31 mots de passe via Vault / SOPS / SealedSecrets / External Secrets Operator.
Matérialisez-les dans un fichier de valeurs qui respecte le schéma documenté en tête du fichier auto-généré.
Passez ce fichier via --secrets-file=....

Le script ne génère des secrets que lorsque le fichier cible est absent. Un fichier existant est réutilisé tel quel.

6. Vérification¶

Le smoke test de Phase 7 est intentionnellement minimal (cinq appels HTTP). Déroulez la cascade complète ci-dessous avant de déclarer l'installation terminée.

6.1 Pods Ready¶

kubectl -n akko get pods -o wide
kubectl -n akko get pods --no-headers | awk '{print $3}' | sort | uniq -c

Attendu : chaque pod du namespace akko est en Running ou Completed. Zéro CrashLoopBackOff, zéro ImagePullBackOff, zéro Pending après 10 minutes. Le cluster de démonstration de référence affiche 55 Running et 12 Completed.

6.2 Jobs d'initialisation¶

kubectl -n akko get jobs

Attendu : chaque Job affiche 1/1 sous COMPLETIONS. Les Jobs incluent typiquement l'import du realm Keycloak, le bootstrap du catalogue Polaris, le seed d'OpenMetadata, l'ingestion du catalogue, le chargement des données de démo.

6.3 Endpoints publics¶

Le rapport de déploiement liste l'ensemble des URL. Vérifiez les cinq surfaces critiques :

DOMAIN=monentreprise.example
for host in cockpit identity federation catalog bi; do
  printf '%-12s ' "${host}"
  curl -sk -o /dev/null -w 'HTTP %{http_code}\n' "https://${host}.${DOMAIN}/"
done

Sortie attendue :

cockpit      HTTP 200
identity     HTTP 200
federation   HTTP 401     # Trino exige un token Bearer — 401 est sain
catalog      HTTP 200
bi           HTTP 302     # Superset redirige le trafic non authentifié

6.4 Connexion persona¶

Le realm Keycloak bundle provisionne cinq personas (alice, bob, carol, dave, erin) mappés aux cinq rôles plateforme (akko-admin, akko-engineer, akko-analyst, akko-viewer, akko-steward). Récupérez le mot de passe de bootstrap dans le rapport de déploiement sous Admin credentials, puis connectez-vous au cockpit :

https://cockpit.<votre-domaine>/

Vous devriez atterrir sur la page d'accueil, voir les huit tuiles de services toutes vertes, et trouver dans le bandeau du haut la pastille de rôle correspondant à votre persona.

6.5 Requête de test ADEN¶

Cliquez sur le bouton Ask AKKO (bandeau supérieur du cockpit), ou ouvrez https://aden.<votre-domaine>/, puis soumettez :

Combien y a-t-il eu de transactions bancaires de plus de 10 000 EUR le mois dernier ?

Comportement attendu : ADEN traduit la question en SQL contre la fédération Trino bundle, retourne une réponse numérique, expose le SQL exécuté ainsi que le lignage des données, et permet d'épingler le résultat à un dashboard BI. Réponse end-to-end sous 12 secondes sur le cluster de référence.

7. Dépannage¶

La matrice suivante regroupe les classes d'échec les plus courantes. Chacune possède une recette de remédiation déterministe.

#	Symptôme	Cause probable	Remédiation
1	`helm install --atomic` se bloque puis rollback avec `Pod akko-cockpit-backend CreateContainerConfigError, Secret akko-cockpit-backend-creds not found`	Un hook post-upgrade crée une Secret nécessaire au boot. Les installations vierges n'atteignent jamais le hook parce que `--atomic` avorte avant.	Le `templates/secrets.yaml` de l'umbrella embarque un pattern `lookup`+stub pour ces Secrets. Si vous avez patché le chart, restaurez le stub. Sinon relancez l'installation — la seconde exécution trouve le stub existant et progresse.
2	Un service est injoignable via l'ingress avec HTTP 502, alors que le pod est `1/1 Running` et répond in-cluster	La NetworkPolicy du service oublie la règle d'autorisation pour Traefik.	Vérifiez avec `kubectl -n akko get netpol <svc> -o yaml`. Si la règle manque, le chart forké a divergé — ré-incluez le helper `akko.networkpolicy.traefikIngress` ou supprimez temporairement la policy : `kubectl -n akko delete netpol <svc>`.
3	Le KPI cockpit affiche `Federation Down`, alors que le pod Trino est `1/1 Running`	Trino refuse les requêtes portant `X-Forwarded-For` parce que `http-server.process-forwarded` vaut `false` par défaut.	Positionnez `trino.config.processForwarded: true` dans votre overlay puis `helm upgrade`. Déjà activé par défaut dans `values-netcup.yaml`.
4	Un pod exécute une vieille image malgré un `docker push` frais et un `kubectl rollout restart`	Le cache containerd épingle le digest sous `docker.io/library/<image>:<tag>` parce que le spec du pod n'a pas de préfixe de registre, alors que le tag mutable n'a été mis à jour que sur le miroir local.	Référencez toujours les images par nom de registre pleinement qualifié. Positionnez `image.pullPolicy: Always` sur chaque tag mutable. Purgez le cache avec `crictl rmi <image>:<tag>` sur le nœud affecté.
5	`helm upgrade` réussit mais revient silencieusement à l'ancienne image	Tag mutable + `pullPolicy: IfNotPresent` + cache containerd se combinent pour conserver le premier digest téléchargé.	Même remédiation que l'item 4 — positionnez `pullPolicy: Always` pour chaque image custom `akko-*`. Déjà appliqué dans `values-netcup.yaml`.
6	`helm template` produit des upstreams en `*.default.svc.cluster.local` et nginx échoue avec `host not found in upstream`	`helm template` retombe par défaut sur le namespace `default`, indépendamment du contexte kubectl actif.	Passez toujours `-n akko` (ou votre namespace de release) à `helm template`. Le script d'installation le fait déjà.
7	Le Job d'init Superset échoue avec `ImportError: jose.exceptions` ou `joserfc not found`	L'image Bitnami Superset livre `joserfc 0.9` alors que le chemin OIDC importe `jose.exceptions`.	Surchargez l'image vers `apache/superset:3.1.1` ou veillez à ce que `superset.bootstrapScript` embarque le shim de compatibilité documenté (voir `helm/akko/charts/akko-init/templates/init-superset-job.yaml`).
8	Trino journalise `EventListener could not be created` et le pod redémarre	Le jar event listener OpenLineage est absent ou la cible OpenMetadata est injoignable au boot.	L'ordre de boot compte : OpenMetadata doit être Ready avant Trino. Soit ajoutez un init container qui attend, soit positionnez `trino.eventListener.enabled: false` et ré-activez après la mise en service du catalogue.
9	`cert-manager` n'émet aucun certificat, les ingresses restent sur le cert auto-signé Traefik par défaut	Le `ClusterIssuer` cert-manager manque ou le challenge DNS / HTTP01 n'atteint pas le cluster.	Inspectez `kubectl describe clusterissuer letsencrypt-prod`. Pour HTTP01, vérifiez que le port 80 atteint Traefik. Pour DNS01, vérifiez le Secret de credentials dans le namespace `cert-manager`.
10	L'import du realm Keycloak échoue avec `Realm akko already exists, import skipped` après une réinstallation `--clean`	Le PVC Postgres a été conservé alors que les lignes DB Keycloak persistent.	`--clean` supprime le namespace mais ne récupère pas toujours les PV en politique `Retain`. Supprimez les PV résiduels : `kubectl get pv \\| grep akko` puis `kubectl delete pv <name>`.
11	Les utilisateurs ne peuvent pas se connecter / Keycloak affiche une liste d'utilisateurs vide / le cockpit redirige vers Keycloak puis renvoie « Invalid user »	Aucun fournisseur d'identité configuré. L'admin Keycloak peut se connecter mais aucun SSO utilisateur ne fonctionne.	Vérifiez la configuration du fournisseur d'identité dans `values-customer.yaml` (bloc `akko-keycloak.userFederation` décommenté + Secret `akko-keycloak-bind` créé), ou passez `--with-demo-ldap` pour installer l'AD de démo intégré. Voir section 2.
12	L'installation `--with-demo-ldap` réussit mais Keycloak logue `LDAPAuthenticationException: Could not authenticate`	Le Secret `akko/akko-demo-ad-federation` porte le mauvais mot de passe (la ré-exécution n'est pas idempotente sur plusieurs appels `--with-demo-ldap` avec `--clean`).	Relancez le script avec `--clean` pour que le Secret demo-ad soit régénéré et ré-mirroré. Alternative : `kubectl -n akko-demo-ad get secret akko-demo-ad -o jsonpath='{.data.admin-password}' \\| base64 -d` puis `kubectl -n akko create secret generic akko-demo-ad-federation --from-literal=bind-password=<valeur> --dry-run=client -o yaml \\| kubectl apply -f -`.

7.1 Commandes de diagnostic de première ligne¶

Imprimez cette carte au mur :

NS=akko
kubectl -n $NS get pods -o wide | grep -v Running
kubectl -n $NS get events --sort-by=.lastTimestamp | tail -20
kubectl -n $NS describe pod <pod-en-échec>
kubectl -n $NS logs <pod-en-échec> --previous
helm history akko -n $NS
helm get values akko -n $NS > /tmp/akko-values.yaml

8. Opérations de jour 2¶

8.1 Mise à niveau Helm¶

bash helm/scripts/install-akko-client.sh \
  --domain=monentreprise.example \
  --from-harbor \
  --chart-version=2026.05.2 \
  --secrets-file=/etc/akko/secrets.yaml \
  --no-rollback

Le script utilise helm upgrade --install, donc le même point d'entrée gère les mises à niveau. Le flag --no-rollback est recommandé en production : une décision manuelle de rollback est plus sûre qu'un rollback automatique qui détruit l'état semi-convergé pendant une session de débogage.

Avant toute mise à niveau :

helm history akko -n akko — confirmez la révision actuelle et que la précédente est saine.
velero backup create akko-pre-upgrade-$(date +%s) --include-namespaces akko — snapshot.
Lancez d'abord avec --dry-run, comparez à votre overlay.
Lancez la vraie mise à niveau dans une fenêtre de maintenance.

8.2 Rotation des secrets¶

# Rotation du mot de passe admin Keycloak
kubectl -n akko create secret generic akko-keycloak-new \
  --from-literal=admin-password=$(openssl rand -base64 32)

# Patcher le déploiement pour récupérer la nouvelle Secret
kubectl -n akko set env deploy/akko-keycloak \
  KEYCLOAK_ADMIN_PASSWORD=$(kubectl -n akko get secret akko-keycloak-new \
    -o jsonpath='{.data.admin-password}' | base64 -d)

# Vérifier
kubectl -n akko rollout status deploy/akko-keycloak

Pour les Secrets service-à-service (client secrets OIDC, mots de passe Postgres, secret root Polaris), suivez le runbook de rotation documenté dans docs/admin/security.md. Le chart supporte helm upgrade --reuse-values --set <chemin>=<nouvelle-valeur> pour toutes les clés global.auth.*.

8.3 Mise à l'échelle¶

Le chart expose des compteurs de réplicas pour les services stateless :

Service	Levier	Défaut
Cockpit	`akko-cockpit.replicaCount`	1
ADEN	`akko-aden.replicaCount`	1
Superset	`superset.supersetNode.replicaCount`	1
Worker Trino	`trino.server.workers`	2
Worker Spark	`akko-spark.worker.replicas`	2
OAuth2 Proxy	`oauth2-proxy.replicaCount`	2

Les services stateful (Postgres, OpenSearch, Polaris, Keycloak) restent singleton dans le chart par défaut. Pour les topologies HA, voir docs/admin/governance-architecture.md.

8.4 Sauvegarde et restauration¶

# Sauvegarde Postgres
kubectl -n akko exec sts/akko-postgresql -- \
  pg_dumpall -U postgres > backup-$(date +%F).sql

# Snapshot du stockage objet (SeaweedFS / gateway S3)
kubectl -n akko exec deploy/akko-seaweedfs-filer -- \
  weed backup -dir=/data -dest=/backup

Pour la reprise après sinistre point-in-time, branchez Velero sur une cible S3 distante et snapshottez le namespace akko quotidiennement. Le DR playbook dans docs/admin/dr-playbook.md couvre le scénario complet DORA Article 11.

8.5 Supervision¶

Le chart livre une couche d'observabilité (Prometheus + Perses + VictoriaLogs + Fluent-Bit + Alertmanager). Points d'accès :

Surface	URL
Dashboards	`https://metrics.<domaine>/` (Perses)
Logs	`https://logs.<domaine>/` (UI VictoriaLogs)
Alertes	`https://alerts.<domaine>/` (Alertmanager)

Les alertes par défaut se déclenchent sur PodNotReady, CertExpiresSoon, PVCFull, TrinoQueryLatencyP95High. Personnalisez les règles sous helm/akko/charts/akko-observability/configs/alerts/.

9. Désinstallation¶

9.1 Désinstallation propre (conservation des données)¶

helm uninstall akko -n akko --wait --timeout 5m

Les PersistentVolumes sont conservés grâce à la politique de récupération par défaut. Réinstaller sous le même nom de release les rattache. Empruntez ce chemin lorsque vous migrez entre versions de chart ou que vous voulez tester des credentials frais sans perdre le catalogue.

9.2 Désinstallation complète (effacement des données)¶

helm uninstall akko -n akko --wait --timeout 5m
kubectl delete ns akko --wait --timeout 5m
kubectl get pv -o json \
  | jq -r '.items[] | select(.spec.claimRef.namespace=="akko") | .metadata.name' \
  | xargs -r kubectl delete pv
kubectl delete clusterrole,clusterrolebinding -l app.kubernetes.io/part-of=akko --ignore-not-found

Après cette séquence le cluster retrouve son état pré-installation. Vérifiez avec kubectl get all -A | grep akko qui doit retourner vide.

9.3 Désinstallation de cert-manager (optionnel)¶

Si cert-manager a été installé uniquement pour AKKO et n'est pas utilisé par une autre charge :

kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml

Annexe A — Échelle de boot¶

Le chart impose un ordre de boot à quatre niveaux. Le connaître aide à interpréter les défaillances transitoires pendant l'installation :

L0 — Fondation : Postgres, Keycloak, SeaweedFS, Polaris atteignent Ready.
L1 — Bootstrap : le secrets.yaml de l'umbrella crée les Secrets placeholder dont les pods L2 ont besoin au premier boot.
L2 — Plateforme : Cockpit, Trino, Airflow, Superset, ADEN, OpenMetadata, JupyterHub démarrent en parallèle.
L3 — Hooks post-install : les vrais client_secrets OIDC remplacent les placeholders, les redirect URIs sont patchés, le catalogue est ingéré, les données de démo sont seedées.

Si l'installation échoue entre L1 et L3, relancez le script. L'umbrella chart est idempotent et la seconde passe termine les hooks.

Annexe B — Où atterrissent les artefacts¶

Artefact	Emplacement
Rapport de déploiement	`~/akko-host-config/deployment-report-<timestamp>.md` (mode 0600)
Secrets générés	`helm/examples/values-dev-secrets.yaml` (mode 0600, gitignoré)
Valeurs de domaine générées	`helm/examples/values-domain.yaml`
Realm Keycloak généré	`helm/examples/realm-domain.json`
Release Helm	`helm list -n akko`
Charges de travail	`kubectl -n akko get all`

Annexe C — Documentation associée¶

docs/admin/customer-onboarding.md — checklist d'onboarding pour un nouveau client.
docs/admin/external-idp.md — câbler votre IDP d'entreprise dans Keycloak.
docs/admin/air-gapped.md — playbook de déploiement en environnement isolé.
docs/admin/dr-playbook.md — procédure de reprise après sinistre (DORA Article 11).
docs/admin/security.md — signature d'images, SBOM, mTLS, chiffrement au repos.
docs/admin/runbooks/index.md — runbooks opérationnels pour les incidents en production.