Dépannage de l'installation

Ce runbook couvre les échecs que vous êtes le plus susceptible de rencontrer lors d'un premier helm install et explique comment vous rétablir de chacun d'eux. La plupart partagent une même cause racine : lors d'une installation à neuf, le chart Helm applique en même temps le plan de contrôle Dapr, les jobs de migration de base de données et toutes les applications, si bien que tout ce qui empêche un pod de devenir Ready peut bloquer le reste.

Tout au long de ce guide, remplacez <ns> par l'espace de noms de votre release (l'espace de noms de la plateforme — par exemple scrydon-platform).

Triage rapide

# Overall pod health — look for anything not Running/2-of-2
kubectl -n <ns> get pods -o wide

# Helm release state — "failed" means --wait gave up on a not-ready resource
helm -n <ns> history <release>

# What blocked the install (the message names the offending resource)
helm -n <ns> status <release>

Un nombre de pods de 1/2 ou 0/2 (application + sidecar Dapr), une release en STATUS: failed ou des pods en CrashLoopBackOff / ContainerStatusUnknown renvoient tous à l'un des cas ci-dessous.

« Auth server unreachable » dans l'interface de la plateforme

La plateforme affiche un message plein écran « Reconnexion en cours… » :

Reconnexion en cours… — Scrydon n'a pas pu joindre le service d'authentification. Il revient généralement de lui-même — nous continuons d'essayer et restaurerons votre session dès qu'il sera disponible.

L'écran se reconnecte de lui-même : il revérifie l'état de santé d'api-platform avec un backoff progressif (3 s → 5 s → 8 s → toutes les 15 s, affiché sous forme de compte à rebours) et restaure automatiquement la session dès que le service est de nouveau sain — aucune action de l'utilisateur n'est nécessaire. Réessayer maintenant force une tentative immédiate.

Dépliez « Détails pour les administrateurs » sur cet écran pour obtenir un diagnostic d'une ligne de la cause — par exemple magasin de secrets indisponible (le cas du sidecar Dapr ci-dessous), migrations en attente ou connexion impossible. Le diagnostic se met à jour automatiquement tant que l'écran continue ses vérifications : vous pouvez ainsi voir une panne passer d'une catégorie à l'autre (par exemple connexion → migrations en attente) à mesure que la pile démarre.

Cela signifie presque toujours l'une de deux choses : le serveur d'authentification (api-platform) est joignable, mais un appel adossé à la base de données a renvoyé une 500 — lors d'une installation à neuf parce que la base de données n'a jamais été migrée (le schéma est vide) — ou bien api-platform a démarré sans son sidecar Dapr et ne peut donc pas déchiffrer les secrets (voir Pods bloqués sans sidecar Dapr).

Confirmer

# api-platform is up and serving (these should be 200)
kubectl -n <ns> logs deploy/api-platform -c api-platform --tail=20   # "Auth server is ready to accept requests."

# The setup-status call the platform makes — a 500 here is the smoking gun
kubectl -n <ns> run authchk --rm -it --restart=Never --image=curlimages/curl:8.7.1 -- \
  curl -s -m 6 -X POST -H "Content-Type: application/json" -d '{}' \
  http://svc-api-platform.<ns>.svc.cluster.local/api/auth/config/get-setup-status

Si les journaux d'api-platform contiennent relation "user" does not exist (ou n'importe quel relation … does not exist), le schéma est absent.

Cause

Sur les charts actuels, la migration d'authentification de la première installation s'exécute dans le Job ordinaire auth-bootstrap-<revision>, et API Platform attend la sentinelle de sa table de preuves avant de démarrer. Un schéma d'authentification absent signifie donc que le Job de bootstrap a échoué ou n'a pas pu joindre PostgreSQL ; ce problème n'est plus masqué derrière un hook de disponibilité post-installation. Les releases de chart plus anciennes utilisaient un hook d'authentification post-install,pre-upgrade et pouvaient l'ignorer lorsqu'un autre Deployment ne devenait jamais Ready.

Correctif

1. Inspectez kubectl -n <ns> logs job/auth-bootstrap-<revision> et corrigez l'erreur de base de données, d'identifiants ou de migration signalée.

2. Relancez les migrations. La reprise la plus propre consiste à laisser le hook pre-upgrade auth-migration-<revision> de Helm les exécuter — il s'exécute avant l'attente de disponibilité :

   bash

   helm -n <ns> upgrade <release> <chart> --reuse-values

3. Vérifiez que le schéma existe, puis rechargez la plateforme :

   bash

   kubectl -n <ns> exec deploy/db -c postgres -- psql -U postgres -d auth -c '\dt' | head

Consultez Migrations de base de données → Les migrations ne se sont jamais exécutées lors d'une installation à neuf pour la reprise manuelle basée sur un job si vous ne pouvez pas exécuter helm upgrade.

Pods bloqués en 1/1 sans sidecar Dapr

Juste après une installation à neuf, certains pods démarrent en 1/1 (sans sidecar daprd) tandis que d'autres sont en 2/2. Redémarrer les pods 1/1 les fait passer en 2/2.

Cause

Dapr injecte son sidecar via un webhook de mutation (dapr-sidecar-injector). Le webhook n'injecte que dans les pods créés après son enregistrement et son passage à Ready. Un unique helm install crée en même temps le plan de contrôle Dapr et les Deployments applicatifs : tout pod applicatif planifié avant que l'injecteur soit prêt ne reçoit donc aucun sidecar. Les services qui dépendent de Dapr échouent alors à leurs vérifications de disponibilité.

Correctif

1. Vérifiez que le plan de contrôle est sain. Avec le Dapr intégré (dapr.installControlPlane: true, la valeur par défaut), il s'exécute dans l'espace de noms de la release, et non dans dapr-system :

   bash

   kubectl -n <ns> get pods | grep dapr     # dapr-operator, dapr-sidecar-injector, dapr-sentry, dapr-placement, dapr-scheduler
   kubectl get mutatingwebhookconfigurations | grep dapr

2. Une fois l'injecteur Ready, redéployez les applications pour qu'elles reçoivent leurs sidecars :

   bash

   kubectl -n <ns> rollout restart deployment

api-table bloqué en 1/2 (échec de la disponibilité)

api-table reste en 1/2 (son sidecar daprd est prêt, mais pas le conteneur applicatif). Sa sonde de disponibilité dépend de trois dépendances — Postgres, StarRocks et le sidecar Dapr.

Diagnostiquer

POD_IP=$(kubectl -n <ns> get pod -l app=api-table -o jsonpath='{.items[0].status.podIP}')
kubectl -n <ns> run rtest --rm -it --restart=Never --image=curlimages/curl:8.7.1 -- \
  curl -s -m 8 http://$POD_IP:7500/api/table/health/ready
# => {"status":"not_ready","checks":{"postgresql":true,"starrocks":false,"dapr":true,"opa":true,...},"stalled":[]}

L'objet checks nomme la dépendance en échec. starrocks:false est le cas le plus fréquent lors d'une installation à neuf.

stalled liste les vérifications qui n'ont pas répondu du tout dans le budget alloué à chaque vérification (READINESS_CHECK_TIMEOUT_MS, 3000 ms par défaut). Une dépendance présente dans stalled est également signalée à false, mais cela signifie « n'a jamais répondu » plutôt que « a répondu non » : cherchez un pool de connexions bloqué ou un backend figé, pas une erreur de configuration. Si la sonde elle-même expire au niveau du kubelet (Readiness probe failed: ... context deadline exceeded dans les événements du pod) au lieu de renvoyer une 503, augmentez le timeoutSeconds de la sonde au-delà du budget ; ce budget existe pour que la sonde puisse nommer la dépendance au lieu d'expirer silencieusement.

Corriger StarRocks (starrocks:false)

Le chart fournit un StarRocks à pod unique (infra.starrocks.enabled: true, l'image allin1). Deux problèmes l'empêchent couramment de servir des requêtes :

• Facteur de réplication. STARROCKS_REPLICATION_NUM vaut "1" par défaut, ce qui correspond au backend à pod unique. Ce n'est que s'il a été surchargé au-delà du nombre de BE actifs que les écritures/requêtes sur les tables échouent avec « tablet replica … not enough » ou « replication num should be less than or equal to the number of available BE nodes » — remettez-le à 1 pour le déploiement à pod unique (ou à votre nombre réel de BE pour un cluster externe) :

  yaml

  apiTable:
    starrocks:
      replicationNum: "1"   # single-pod StarRocks has one backend

• Démarrage à froid. StarRocks met plus de temps qu'api-table à accepter des connexions. Vérifiez que le FE est démarré et qu'un backend est actif, puis laissez api-table refaire sa sonde (il réessaie toutes les 10 s) :

  bash

  kubectl -n <ns> logs deploy/starrocks-fe --tail=30 | grep -i 'alive\|backend'

Si StarRocks n'est réellement pas nécessaire, désactivez les tables gérées avec apiTable.enabled: false et infra.starrocks.enabled: false.

daprd redémarre en boucle avec address already in use

Un pod est en 1/2 et son conteneur daprd redémarre avec :

Failed to listen for gRPC server on TCP address :50002 with error: listen tcp :50002: bind: address already in use

et un helm upgrade --wait qui a redéployé le pod se termine par context deadline exceeded.

Cause

Le conteneur de l'application et daprd partagent un même espace de noms réseau. daprd écoute sur 50001 et 50002, qui se trouvent dans la plage de ports éphémères par défaut de Linux (32768–60999). Si l'application ouvre une connexion sortante (par exemple vers Postgres) avant que daprd ne se lie à ses ports, le noyau peut attribuer à cette connexion le port local 50002, et daprd ne peut pas démarrer.

Correctif

Les charts publiés après v1.3.25-rc.36 réservent ces ports dans chaque pod où Dapr est activé (dapr.reserveSidecarPorts: true, la valeur par défaut). Avec un chart plus ancien, ou si ce paramètre est désactivé, supprimez le pod concerné. Son remplaçant obtient de nouveaux ports éphémères. Pour confirmer quel processus détient le port, lisez /proc/net/tcp dans le conteneur de l'application : C352 correspond au port 50002 en hexadécimal.

Le nettoyage des workflows journalise workflow is stalled

Le balayage de rétention des workflows journalise, à chaque exécution et pour les mêmes instances :

Error purging workflow <instance-id>: 2 UNKNOWN: failed to purge workflow state: workflow is stalled

Cause

Dapr marque une instance de workflow comme bloquée (stalled) lorsque le code désormais déployé ne peut pas rejouer son historique. La raison habituelle est un déploiement qui a modifié le code du workflow (PATCH_MISMATCH). Les instances de ce journal étaient déjà terminées : un événement les a réveillées après leur achèvement, elles ont été rejouées sur le nouveau code, puis se sont bloquées. Dapr les signale toujours comme terminées, mais refuse de purger une instance bloquée sauf si la purge est forcée, et le SDK JavaScript de Dapr ne peut pas envoyer de purge forcée. Le balayage échouait donc sur ces instances à chaque exécution, et leur état n'était jamais supprimé.

Correctif

Les versions postérieures à v1.3.25-rc.39 forcent la purge, mais uniquement lorsque Dapr la refuse parce que l'instance est bloquée. Une purge que Dapr refuse pour toute autre raison, par exemple un workflow encore en cours d'exécution, n'est jamais forcée. Chaque purge forcée journalise Workflow <instance-id> is stalled; purging it with force et enregistre l'événement d'audit habituel workflow.purged. Aucune étape manuelle n'est nécessaire. Les erreurs cessent dès le premier balayage après la mise à niveau.

La release Helm affiche failed

helm history indique failed avec un message tel que :

Release "scrydon" failed: resource Deployment/<ns>/api-table not ready

Cause

helm install --wait a attendu que chaque ressource devienne Ready et un Deployment ne l'est jamais devenu (couramment api-table en attente de StarRocks, ou un pod tué par manque de mémoire — voir ci-dessous). Lorsque l'attente échoue, la release est marquée failed. Les migrations de première installation de chaque service s'exécutent dans des Jobs de bootstrap ordinaires, et non dans des hooks : elles ne sont donc pas sautées — vérifiez-les avec kubectl get jobs -A. Jusqu'au chart 1.3.25 inclus, les migrations d'agentic, d'analytics, de cortex et d'ontology étaient des hooks post-install, qu'une attente en échec saute ; ces applications échouent alors avec relation "…" does not exist tant qu'elles ne se sont pas exécutées.

Correctif

1. Résolvez l'échec de disponibilité nommé dans le message (les sections ci-dessus couvrent les cas habituels).

2. Relancez helm upgrade pour ramener la release à l'état deployed. Ses hooks de migration pre-upgrade exécutent les migrations ignorées, et ne font rien pour un schéma déjà à jour :

   bash

   helm -n <ns> upgrade <release> <chart> --reuse-values

Pods tués par manque de mémoire ou en boucle de plantage (un seul petit nœud)

Symptômes : pods en CrashLoopBackOff ou ContainerStatusUnknown, exit code 137, tous les pods échouant à leur sonde de disponibilité en même temps peu après l'installation.

Cause

L'ensemble de la pile (toutes les applications + le plan de contrôle Dapr + Postgres + StarRocks + le stockage d'objets) a été planifié sur un seul nœud sous-dimensionné. Lorsque tous les pods démarrent en même temps, les limites mémoire sont surengagées et le kubelet tue des pods pour manque de mémoire (OOM), ce qui provoque une tempête de démarrages à froid.

Correctif

• Respectez les Exigences en ressources — 8 vCPU / 40 Go minimum pour la pile complète par défaut — et privilégiez au moins deux nœuds afin que l'ordonnanceur puisse répartir la charge et que le plan de contrôle ne soit pas en concurrence avec les applications.

• Sur Azure, la mise à l'échelle d'un pool de nœuds peut échouer avec InsufficientVCPUQuota. Vérifiez et augmentez votre quota régional de vCPU pour la famille de VM avant la mise à l'échelle :

  bash

  az aks nodepool scale --cluster-name <cluster> --resource-group <rg> --name <pool> --node-count 3
  # ERROR: (ErrCode_InsufficientVCPUQuota) … request a quota increase in the Azure portal

• Pour fonctionner avec une empreinte plus réduite, supprimez des composants optionnels — voir Helm → Allègement pour les installations à faibles ressources.

La première installation ne converge jamais sur un petit cluster

Symptômes : helm install --wait expire. db (ou un autre pod) est resté Pending avec 0/N nodes are available: … Insufficient cpu ou Insufficient memory, les Jobs <service>-bootstrap-<revision> ont échoué avec DeadlineExceeded, et api-platform reste bloqué en Init.

kubectl -n <ns> get jobs
kubectl -n <ns> get events --field-selector reason=FailedScheduling

Cause

Lors d'une première installation, les Jobs d'amorçage des schémas tournent en même temps que les workloads, et ils ont besoin de db. Quand les nœuds ne peuvent pas accueillir les deux, le scheduler place les pods qu'il atteint en premier. Si db reste en attente, les Jobs ne peuvent pas le joindre et échouent à leur délai de 10 minutes. db est planifié une fois qu'ils ont disparu, mais les schémas qu'attendent les autres services n'ont jamais été créés. La page Ressources donne le pic qu'une première installation demande.

Correctif

1. Ajoutez de la capacité de nœud, ou désactivez les composants dont vous n'avez pas besoin — voir Helm → Allègement pour les installations à faibles ressources. Les Jobs de migration de l'étape suivante doivent eux aussi pouvoir être planifiés.

2. Lancez helm upgrade. Ses hooks de migration pre-upgrade créent les schémas manquants :

   bash

   helm -n <ns> upgrade <release> <chart> --reuse-values

Impossible d'atteindre /setup (redirection vers la connexion)

Si /setup renvoie directement vers /auth/sign-in sur une installation toute neuve où aucun administrateur n'existe encore, le serveur d'authentification indique que la configuration est déjà terminée. Vérifiez-le avec l'appel get-setup-status présenté plus haut. Les acteurs de service system+…@scrydon.internal créés par les migrations ne terminent pas la configuration ; la réponse attendue est {"setupCompleted":false} tant que le premier administrateur humain n'existe pas. Une réponse true sans utilisateur humain indique une base de données d'authentification incohérente ou des versions d'application mélangées. Contactez le support — ne modifiez pas les tables d'authentification à la main.