Vérification et dépannage
Cette page décrit les procédures courantes de vérification et de dépannage pour les déploiements Avatar installés avec le chart Helm. Elles s'appliquent aussi bien après une installation initiale qu'après une mise à jour.
Toutes les commandes ci-dessous supposent que la release se trouve dans le namespace avatar.
Adaptez -n si vous l'avez installée ailleurs.
Vérification rapide
Tout est en fonctionnement
kubectl -n avatar get pods
kubectl -n avatar get jobs
kubectl -n avatar get ingress
Vous devez voir les pods de l'API, du web, de l'ordonnanceur et des workers Dask, du serveur et du
worker Authentik en Running, les StatefulSets SeaweedFS en Running si seaweedfs.enabled vaut
true, le pod avatar-connector en Running si connector.enabled vaut true, et le Job avatar-authentik-db-init-<version-du-chart> en Complete.
Santé de l'API
L'API expose un point de contrôle de santé sans authentification à travers l'ingress :
curl https://<votre-domaine>/api/health
La réponse attendue est {"message":"ok"}. Un échec ici vient généralement de l'ingress ou du TLS
plutôt que de l'API — vérifiez depuis l'intérieur du cluster pour distinguer les deux :
kubectl -n avatar run curl --rm -it --image=curlimages/curl --restart=Never \
-- curl -s http://avatar-api:8000/health
Tests manuels
Afficher les vérifications manuelles
Vérification complète de la configuration
Pour un contrôle exhaustif de tous les services et de la configuration, utilisez le point d'accès
/health/config-full-check avec une clé d'API administrateur :
AUTH_HEADER="Authorization: api-key-v1 $AVATAR_API_KEY"
curl -s https://<votre-domaine>/api/health/config-full-check -H "$AUTH_HEADER" | python3 -m json.tool
Ce point d'accès exécute simultanément toutes les vérifications suivantes et renvoie un rapport JSON détaillé :
- Variables d'environnement et secrets
- Connectivité à la base de données et migrations en attente
- Accessibilité du stockage et accès en lecture/écriture
- Configuration email
- Page de connexion web et cohérence du front-end
- Disponibilité du back-end (workers)
- Télémétrie
Il renvoie HTTP 200 si toutes les vérifications passent, 207 en cas d'avertissement, et 500 si
l'une échoue. Le corps de la réponse contient toujours le détail de chaque vérification, quel que
soit le statut global.
Si vous n'avez pas encore créé d'utilisateur et ne pouvez pas vous authentifier, utilisez d'abord le contrôle de santé basique ci-dessus. Consultez Gestion des utilisateurs pour créer un utilisateur, et récupérer l'accès administrateur si vous êtes bloqué.
Migrations de base de données
Un échec de migration se manifeste par un pod de l'API qui ne sort jamais de Init.
kubectl -n avatar logs deploy/avatar-api -c init-avatar-api
Vérification des emails
Les emails sont envoyés par Authentik. Envoyez un email de test depuis le worker Authentik :
kubectl -n avatar get deploy | grep authentik
kubectl -n avatar exec deploy/<deploiement-worker-authentik> -- ak test_email <VOTRE_ADRESSE_EMAIL>
Les noms des déploiements Authentik sont préfixés par le nom de la release Helm : ils dépendent donc du nom que vous lui avez donné.
Vérifiez que l'email arrive bien dans votre boîte et qu'aucune erreur n'apparaît dans la sortie de la commande.
Chiffrement SeaweedFS
Si vous utilisez le SeaweedFS du chart, vérifiez que le déploiement lit et écrit correctement dans le bucket chiffré.
Assurez-vous qu'il n'y a pas d'erreurs SSE-S3 :
kubectl -n avatar logs -l app.kubernetes.io/name=seaweedfs,app.kubernetes.io/component=s3 --tail=100
En cas d'erreurs, storage.sseKek ne correspond pas à la clé détenue par le filer. Lisez-la et
comparez :
kubectl -n avatar exec -it seaweedfs-master-0 -- weed shell
> fs.cat /etc/s3/sse_kek
Si elles diffèrent, positionnez storage.sseKek sur la valeur détenue par le filer et mettez la
release à jour. Ne conservez pas la nouvelle clé : elle rendrait tous les objets stockés
indéchiffrables.
Plus d'informations dans le wiki SeaweedFS.
Vérification approfondie
Test du flux de connexion
- Ouvrez
https://<votre-domaine>/webdans un navigateur - Vous devez être redirigé vers Authentik, sur
https://<votre-domaine>/sso/ - Connectez-vous avec le compte
akadmincréé lors du parcours de premier administrateur - Vérifiez que vous revenez dans l'interface Avatar et qu'elle affiche la bonne version
Un aller-retour réussi confirme que le blueprint Authentik a enregistré le fournisseur OAuth avec
les sso.clientId et sso.clientSecret qu'utilise l'API.
Test d'avatarisation
- Téléversez un petit jeu de données de test
- Configurez et lancez un traitement d'avatarisation
- Vérifiez que le traitement se termine correctement
- Téléchargez et inspectez les résultats
C'est la seule vérification qui sollicite les workers Dask et le stockage objet de bout en bout.
Si une vérification échoue
Commencez par le tableau de symptômes ci-dessous, qui couvre les défaillances propres à une installation Helm.
| Symptôme | Correctif |
|---|---|
helm install échoue en nommant une valeur | Une valeur obligatoire est vide. Le message indique laquelle. |
Les pods Authentik restent en Init:0/1 | La base de données n'est pas joignable. Consultez les journaux du Job d'amorçage, puis database.host et les identifiants administrateur. |
Le Job d'amorçage échoue sur GRANT | Le rôle Authentik existe déjà. Positionnez authentikDatabase.createDatabase: false et créez la base à la main. |
| La connexion échoue à l'échange de jeton | Le fournisseur enregistré porte d'anciens sso.clientId / sso.clientSecret. Redémarrez le serveur et le worker Authentik, puis appliquez de nouveau le blueprint. |
La connexion échoue avec CERTIFICATE_VERIFY_FAILED | Renseignez le certificat de votre autorité dans api.caBundle. |
La connexion échoue, et /sso/application/o/<slug>/.well-known/openid-configuration répond 404 | sso.providerAppName a été surchargée. Retirez la surcharge. |
/sso/if/flow/initial-setup/ répond 404 | Un administrateur existe déjà. Connectez-vous avec ce compte. |
| Un utilisateur désactivé dans Authentik conserve des clés d'API fonctionnelles | Les clés partent au prochain reconcile périodique et non immédiatement : le webhook n'atteint pas l'API. Vérifiez que le worker Authentik a bien AVATAR_AUTHENTIK_BLUEPRINT_API_WEBHOOK_URL dans son environnement. |
Pods Dask en InvalidImageName | Un tag d'image Dask est vide. Renseignez-le avec api.image.tag. |
Les écritures dans un bucket utilisateur échouent en InternalError | storage.sseKek n'est pas renseignée ou a changé — voir Chiffrement SeaweedFS. |
Pods en ImagePullBackOff | imageCredentials.dockerConfigJson est absent, mal formé, ou ne couvre pas quay.io/octopize. |
Rien n'atteint la plateforme avec networkPolicy.enabled | networkPolicy.ingressController.podSelector ne correspond pas aux pods de votre contrôleur, ou celui-ci est dans un autre namespace et namespaceSelector n'est pas renseignée. |
Les StatefulSets SeaweedFS restent Pending | Aucune StorageClass par défaut, ou elle ne peut pas satisfaire la taille demandée. |
Pods rejetés avec violates PodSecurity "restricted" | Partez de example-values-restricted.yaml — voir Pod Security Standard restricted. Les pods Dask sont toujours rejetés. |
cannot verify user is non-root | Renseignez runAsUser avec runAsNonRoot: true — 1000 pour l'API, 1001 pour le client web. |
CERTIFICATE_VERIFY_FAILED dans un worker Dask | api.caBundle n'atteint pas les workers. Voir Calcul. |
Un pod reste Pending après avoir renseigné nodeSelector ou tolerations | Chaque charge de travail a les siennes. Vérifiez celle qui est bloquée. |
Les pods web servent mais journalisent EACCES sous /app/.next | runAsUser vaut 1000. L'image web s'exécute sous l'uid 1001, groupe 65533. |
Les pods SeaweedFS bloquent au démarrage après l'ajout de fsGroup | Positionnez fsGroupChangePolicy: OnRootMismatch sur les contextes de sécurité SeaweedFS. |
field is immutable sur le Job d'amorçage | Une valeur authentikDatabase.* a changé, ou database.existingSecret / authentikDatabase.existingSecret a été activée, sans bump de version du chart. Supprimez le Job, ou bumpez la version. |
connector.enabled needs networkPolicy.enabled | Positionnez networkPolicy.enabled: true. Le connecteur n'est généré qu'avec ses network policies. Voir Connecteur de bases de données. |
connector.image.tag is empty | Fixez connector.image.tag (ou connector.image.digest). |
| Tester sur une connexion indique que la base de données est injoignable | Le trafic sortant du connecteur exclut les réseaux privés. Ajoutez le réseau de la base de données à connector.networkPolicy.allowedDatabaseCIDRs. |
| L'enregistrement d'une connexion renvoie 503 | databaseConnections.encryptionKeys est vide. Voir Connecteur de bases de données. |
| Une exécution sur base de données échoue : il manque des tables dans la cible | L'exécution ne crée pas de tables. Restaurez d'abord le schéma dans la cible. |
Créer ou récupérer un utilisateur
Les utilisateurs Avatar sont gérés entièrement dans Authentik — il n'y a pas d'annuaire interne distinct. Consultez Gestion des utilisateurs, y compris pour récupérer l'accès administrateur si vous êtes bloqué.
Collecter les informations de diagnostic
Si un problème ne peut pas être résolu, collectez les éléments suivants avant de contacter le support Octopize :
# Statut des pods et événements récents
kubectl -n avatar get pods -o wide > diagnostics-pods.txt
kubectl -n avatar get events --sort-by=.lastTimestamp > diagnostics-events.txt
# Journaux des composants Avatar
for d in $(kubectl -n avatar get deploy -o name); do
kubectl -n avatar logs "$d" --all-containers --prefix --tail=20000
done > diagnostics-logs.txt 2>&1
# Manifestes rendus, avec les valeurs qui les ont produits
helm -n avatar get manifest avatar > diagnostics-manifest.yaml
Vérifiez les fichiers de diagnostic à la recherche de données sensibles (mots de passe, jetons, secrets) avant de les partager avec le support. Les manifestes rendus contiennent les objets Secret créés par le chart.
Fournissez ces fichiers accompagnés d'une description du problème lorsque vous contactez le support Octopize.