Passer au contenu principal
Cette page recense les problèmes que nous rencontrons le plus souvent lors de l’installation et de l’exploitation courante, ainsi que les commandes de diagnostic et les correctifs associés. Chaque entrée suit la structure Symptôme → Diagnostic → Correctif. Si vous rencontrez un blocage, récupérez les logs de l’opérateur, l’état de la ressource Vantage et l’état de toute application ArgoCD en échec avant de contacter votre ABBYY account team :

​
opérateur et CRD

​
Forcer une nouvelle tentative après correction d’un problème de manque de ressources

Symptôme. Vous avez corrigé la cause sous-jacente d’un échec (ajout d’un secret Key Vault manquant, attribution des autorisations RBAC, réparation d’une base de données), mais l’opérateur n’a pas relancé la réconciliation. Diagnostic. L’opérateur réagit aux événements sur la ressource Vantage elle-même ; les changements d’état en dehors de la ressource (autorisations Key Vault, stratégies réseau, services externes) ne déclenchent pas de réconciliation. Les ressources Vantage sont mutables, mais pour relancer l’installation de Vantage, la ressource doit être annotée avec vantage.abbyy.com/reprocess (n’importe quelle valeur). Correction. Annotez la ressource Vantage avec vantage.abbyy.com/reprocess (n’importe quelle valeur) pour forcer une nouvelle réconciliation depuis la phase de prévérification :
Mettez à jour la valeur de l’annotation (par exemple, un horodatage) chaque fois que vous souhaitez réessayer. L’opérateur ne réconcilie à nouveau que lorsque la valeur de l’annotation change.

​
Ressource Vantage bloquée sur Progressing

Symptôme. kubectl describe vantages.vantage.abbyy.com $release_name -n $install_namespace affiche Progressing=True pendant une période prolongée, et Ready ne passe jamais à True. Diagnostic. Inspectez status.degradationReasons[] dans la ressource ; l’opérateur y signale le composant défaillant. Vérifiez ensuite l’application ArgoCD correspondante :
Correctif. Résolvez l’erreur de synchronisation ArgoCD à l’origine du problème. Causes courantes : un chart Helm en amont requiert une valeur dont le cluster ne dispose pas encore (secret Key Vault manquant, échec du téléchargement de l’image), ou un ingress gateway est absent. Une fois le problème corrigé, annotez la ressource Vantage avec vantage.abbyy.com/reprocess pour relancer l’installation (Forcer une nouvelle tentative).

​
L’opérateur ne prend jamais en compte une nouvelle ressource Vantage

Symptôme. Vous appliquez une ressource Vantage et kubectl get vantages l’affiche, mais l’opérateur n’indique jamais aucun statut. Diagnostic. Vérifiez que l’opérateur est en cours d’exécution et effectue la réconciliation :
Correctif. L’opérateur surveille les ressources Vantage à l’échelle du cluster ; le chart n’expose aucune valeur permettant de restreindre les namespaces qu’il surveille. Si l’opérateur s’exécute, mais que les logs ne montrent aucune tentative de réconciliation pour votre ressource, vérifiez que la CRD utilise la version attendue par l’opérateur (vantage.abbyy.com/v1alpha1) et qu’une seule instance de l’opérateur est installée dans le cluster. Pour voir les valeurs réellement acceptées par le chart, exécutez helm show values $charts_uri/vantage-operator --version $operator_version (Valeurs du chart Helm).

​
L’application de la CRD échoue avec une erreur de validation

Symptôme. kubectl apply rejette la ressource Vantage avec un message de validation CEL. Diagnostic. Le message d’erreur provient des règles CEL de la CRD. Les causes les plus fréquentes sont un bloc ociMigration avec enabled: true mais sans destination, ou un bloc techcore avec keepPreviousVersion: true mais sans previousVersion. Correctif. Renseignez le champ indiqué dans le message de validation. Voir l’API reference pour l’ensemble des règles de validation.

​
Migration OCI

​
Le job de migration OCI ne démarre jamais

Symptôme. La ressource Vantage reste à l’état Progressing ; aucun job nommé $release_name-oci-migration n’existe dans votre namespace d’installation. Diagnostic. Vérifiez la prévérification de l’opérateur dans les logs de l’opérateur, ainsi que les motifs de dégradation de la ressource. Le job n’est créé qu’une fois la prévérification validée. Correction. Résolvez la prévérification qui échoue. Lors de la prévérification, la configuration est validée, y compris la configuration des secrets ; commencez donc par vérifier que chaque alias Obligatoire existe dans votre fournisseur de secrets (Secrets and Key Vault).

​
La tâche de migration OCI s’exécute mais échoue

Symptôme. kubectl -n $install_namespace get jobs affiche la tâche de migration, mais elle n’atteint pas l’état Complete. Diagnostic. Inspectez les logs de la tâche :
Correction. La plupart des échecs sont liés à l’authentification : soit le job n’a pas pu récupérer depuis le registre source (vérifiez le secret credentialsRef.name ou le nom d’utilisateur/mot de passe de chaque entrée vantage.ociMigration.sources[]), soit il n’a pas pu envoyer vers la destination (vérifiez les identifiants de vantage.ociMigration.destination et le RBAC de l’identité de charge de travail si vous utilisez Azure Workload Identity). Si le pod du job ne parvient jamais à récupérer son image, voir Pods bloqués dans ImagePullBackOff.

​
Téléchargement d’images

​
Pods bloqués dans ImagePullBackOff

Symptôme. Les pods de l’opérateur, le pod du job de migration OCI ou les pods de charge de travail Vantage signalent ImagePullBackOff ou ErrImagePull, et kubectl describe pod affiche une erreur unauthorized: authentication required provenant de votre registry. Diagnostic. Recherchez les pods en échec et l’erreur du registry :
Correctif. Donnez au composant en échec l’autorisation de tirer depuis votre registre :
  • Pods de l’opérateur : mettez à niveau la release vantage-operator avec --set "manager.imagePullSecrets[0].name=my-pull-secret".
  • Job de migration OCI : exécutez le job avec un ServiceAccount associé au secret de pull (vantage.ociMigration.serviceAccountName=my-service-account), ou référencez le secret dans l’entrée source (vantage.ociMigration.sources[0].credentialsRef.name=my-pull-secret).
  • Charges de travail Vantage : ajoutez le secret de pull aux imagePullSecrets du ServiceAccount nommé par vantage.serviceAccountName. Si le pod en échec signale un autre ServiceAccount, y compris default, accordez l’autorisation de pull à ce ServiceAccount ou configurez le composant pour qu’il utilise le ServiceAccount Vantage prévu.
  • Sur AKS : au lieu d’utiliser des secrets de pull, accordez AcrPull sur le registre à l’identité du kubelet du cluster.
Voir l’accès Azure pour le pull d’images ou l’accès au registre autogéré pour la configuration complète.

​
Secrets

​
Les pods ne démarrent pas avec MountVolume.SetUp failed for volume "secrets-store"

Symptôme. Les pods Vantage ne démarrent pas ; les événements associés au pod indiquent des échecs de montage du pilote CSI. Diagnostic. Le Secrets Store CSI driver n’a pas pu récupérer un secret dans le Key Vault. Causes les plus fréquentes :
  • L’identité sélectionnée par vantage.secrets.azure.identityMode ne dispose pas d’un accès en lecture au secret ou au certificat nommé.
  • Un nom d’objet Key Vault ne correspond pas à l’alias attendu par Vantage, et aucune mise en correspondance objects n’a été fournie.
  • Le provider Azure du pilote CSI n’est pas installé.
Correction. Vérifiez que l’identité configurée dispose des permissions get pour chaque alias répertorié dans Secrets et Key Vault. Si les noms de vos objets Key Vault diffèrent des alias, fournissez une mise en correspondance objects dans vantage.secrets.azure. Voir Modes d’identité pour savoir quelle identité est utilisée dans chaque mode.

​
Les secrets TLS associés sont manquants

Symptôme. Les services d’authentification ne démarrent pas et l’un des quatre alias de secret TLS est absent de votre Key Vault. Diagnostic. Vantage requiert quatre éléments encodés au format PEM, stockés sous forme de Key Vault secrets : un certificat et une clé privée pour la signature d’authentification, ainsi qu’un certificat et une clé privée pour les jetons d’authentification désactivés. Correctif. Vérifiez que les quatre alias existent : authSigningTlsCrt, authSigningTlsKey, authDeactivatedTlsCrt, authDeactivatedTlsKey. Voir Secrets and Key Vault → Alias de certificats.

​
Échec du provider Secret Kubernetes lors de la prévérification

Symptôme. Une installation autogérée échoue pendant la prévérification avec une erreur de Secret manquant, de clé manquante ou forbidden. Diagnostic. L’opérateur lit les Secrets natifs dans $install_namespace pendant la prévérification. Le Secret indiqué peut ne pas exister, une mise en correspondance objects peut pointer vers un nom incorrect, le Secret peut ne pas contenir la clé de données attendue, ou le RoleBinding créé par le chart peut ne pas faire référence au ServiceAccount de l’opérateur installé. Vérifiez les autorisations de l’opérateur sur l’un des Secrets concernés :
Correctif. Vérifiez que chaque Secret existe dans le namespace d’installation, puis comparez vantage.secrets.kubernetes.objects à l’inventaire des alias de secret. Si l’autorisation échoue, vérifiez que les valeurs operator.namespace et operator.controllerManagerServiceAccount du chart Vantage correspondent à l’opérateur installé. Si un contrôleur de secrets externe crée les Secrets, attendez qu’il signale une synchronisation réussie avant de forcer un nouveau reconcile de l’opérateur.

​
Bases de données

​
Les charges de travail PostgreSQL indiquent que DataProvider est introuvable

Symptôme. Les pods de démarrage de la base de données ou de migration échouent avec le message DataProvider '<value>' not found. Diagnostic. vantage.databaseProvider est sensible à la casse. Le provider runtime PostgreSQL doit être nommé exactement PostgreSQL. Correctif. Définissez :
Des valeurs comme Postgresql et PostgreSql ne sont pas valides à l’exécution. Appliquez les valeurs corrigées et forcez une nouvelle tentative.

​
Le schéma PostgreSQL n’est pas à jour

Symptôme. Plusieurs services ne parviennent pas à démarrer et affichent postgres database schema is not up to date, ou présentent des conflits de version de migration. Diagnostic. Plusieurs services utilisent la même base de données logique PostgreSQL. Chaque service conserve son propre historique de migration et doit utiliser une base de données distincte. Correctif. Créez une base de données distincte pour chaque alias de base de données. Pour les charges de travail qui utilisent la clé générique Database__ConnectionString, créez des Secrets Kubernetes distincts et mettez chaque alias en correspondance avec vantage.secrets.kubernetes.objects. Voir PostgreSQL and per-service Secrets.

​
ArgoCD

​
L’application ArgoCD affiche OutOfSync après l’installation

Symptôme. kubectl get application -A indique que l’une des applications gérées par l’opérateur est OutOfSync, alors même que l’opérateur a par ailleurs signalé l’état Ready. Diagnostic. Examinez le status.conditions[] de l’application :
Correction. Si la dérive est due à des modifications manuelles apportées aux objets gérés par l’opérateur, annulez-les ; ces objets appartiennent à l’opérateur et seront resynchronisés. Si la dérive concerne une valeur du chart, mettez-la à jour via la ressource Vantage (ou la release Helm vantage-selfhosted). Ne modifiez jamais directement l’objet ArgoCD Application sous-jacent.

​
Synchronisation d’ArgoCD ApplicationSet bloquée

Symptôme. Les applications ArgoCD ne progressent jamais dans leurs phases de synchronisation. Diagnostic. Vérifiez que les synchronisations progressives d’ApplicationSet sont activées dans votre installation ArgoCD :
Correctif. Activez les synchronisations progressives selon la documentation d’ArgoCD, puis redémarrez le contrôleur ApplicationSet.

​
KEDA et Prometheus

​
Les ressources ScaledObject ne peuvent pas créer de HPA

Symptôme. KEDA signale Ready=False ou ScaledObjectCheckFailed, et ArgoCD indique que les applications de charge de travail concernées sont dégradées. Diagnostic. Vérifiez la version installée de KEDA ainsi que les événements ScaledObject :
Les charts de charge de travail Vantage actuels nécessitent KEDA 2.17.x ; KEDA 2.18 et les versions ultérieures ont supprimé un champ de scaler utilisé par ces charts. Correctif. Installez KEDA 2.17.3, puis resynchronisez les applications ArgoCD concernées.

​
Les métriques HPA affichent <unknown>

Symptôme. Les ressources KEDA existent, mais kubectl get hpa affiche <unknown> pour les métriques Vantage et les charges de travail ne se redimensionnent pas comme prévu. Diagnostic. Les ressources ScaledObject interrogent http://prometheus-operated.observability.svc.cluster.local:9090. Le Service peut être absent, le ServiceMonitor de Vantage peut ne pas être sélectionné, ou le maillage de services peut bloquer la collecte. Correctif. Vérifiez que le Service Prometheus existe, que ses cibles Vantage sont UP et que les valeurs du chart observability sont définies au niveau supérieur :
Voir Autoscaling avec KEDA pour le comportement des déclencheurs et la vérification, et Monitoring avec Prometheus pour la configuration d’Istio et de Linkerd.

​
Installation du Skill

​
Les Skills sont absents après que l’installation a indiqué Ready

Symptôme. La ressource Vantage indique Ready et Vantage est accessible, mais les Skills attendus sont absents et aucun élément lié aux Skills n’apparaît dans ArgoCD. Diagnostic. Les Skills sont installés par un job Kubernetes distinct qui n’est pas visible dans ArgoCD ; il n’apparaît donc jamais dans argocd app list (y compris dans la capture de diagnostic en haut de cette page). Le job peut encore être en cours d’exécution après Ready ; vous pouvez utiliser Vantage en attendant. Vérifiez le job :
Correctif. Si le job est toujours en cours d’exécution, attendez qu’il atteigne l’état Complete. Si le job a échoué, examinez ses logs pour identifier l’erreur sous-jacente et la corriger ; si l’échec persiste, capturez les logs du job ainsi que les logs de l’opérateur pour votre ABBYY account team.

​
Maillage de services et ingress

​
503 au niveau de l’ingress, trafic de l’application bloqué

Symptôme. https://$your_vantage_hostname renvoie 503 alors même que les pods sont indiqués comme Ready. Diagnostic. Sur AKS avec l’ingress Istio intégré, la passerelle externe peut être défaillante ou le Secret TLS peut ne pas correspondre à ingress.tls.secretName. Avec un ingress géré par le client, il se peut que le contrôleur n’ait pas de route correspondante, que le nom ou le port du Service backend soit incorrect, ou que le certificat TLS ne soit pas prêt. Correctif. Pour Istio, vérifiez la passerelle et le Secret TLS :
Vérifiez qu’un Secret de type kubernetes.io/tls existe dans le namespace de la passerelle externe, avec le nom indiqué pour le chart, et que son certificat est valide pour dnsRecord. Pour un ingress géré par le client, examinez les logs du contrôleur et l’état de la route. Vérifiez que le nom d’hôte de la route correspond à vantage.dnsRecord, que TLS est prêt et que chaque Service backend existe dans $install_namespace. Voir Configurer l’ingress et TLS.

​
Les redirections de connexion ou les métadonnées OIDC utilisent http://

Symptôme. Vantage est accessible via HTTPS, mais la connexion de l’administrateur de la plateforme échoue, ou /auth2/.well-known/openid-configuration annonce un émetteur et des points de terminaison en http://. Diagnostic. La terminaison TLS s’effectue au niveau du contrôleur d’ingress, mais les charges de travail d’authentification ne prennent pas en compte le protocole HTTPS transmis. Correctif. Vérifiez que l’ingress envoie X-Forwarded-Proto: https et que les conteneurs d’application pour auth-identity, auth-adminapi2, api-gateway et api-registry ont :
Si le chart de votre charge de travail n’expose pas ce paramètre d’environnement, appliquez votre mutation d’admission approuvée avant de redémarrer les pods concernés. Voir Schéma HTTPS transmis.

​
Les cibles de scraping Prometheus apparaissent comme DOWN pour /metrics-text

Symptôme. Dans Prometheus dans le mesh, les cibles de l’application Vantage apparaissent comme DOWN. Diagnostic. Sur Istio, il se peut que le pod Prometheus n’ait pas de sidecar ou que les certificats de sortie d’Istio ne soient pas écrits dans /etc/prom-certs/. Sur Linkerd, une stratégie d’autorisation stricte peut bloquer les collectes en texte brut provenant d’un Prometheus non maillé.
Correctif. Avec Istio, vérifiez que le pod Prometheus contient trois conteneurs (prometheus, config-reloader, istio-proxy) et que l’annotation proxy.istio.io/config avec OUTPUT_CERTS: /etc/istio-output-certs est bien présente. Avec Linkerd, injectez le namespace observability ou configurez le ServiceMonitor et Prometheus avec les certificats client requis par votre stratégie. Consultez Monitoring avec Prometheus.

​
Opérations courantes

​
Après la mise à niveau, l’opérateur indique la nouvelle version, mais Vantage est toujours sur l’ancienne

Symptôme. status.installedVantageVersion reste inchangé après la mise à niveau des release Helm. Diagnostic. Les release vantage-operator et vantage-selfhosted ne sont peut-être pas sur la même nouvelle version, ou ArgoCD est peut-être encore en train d’appliquer les modifications propres à chaque composant. Vérifiez les deux release Helm ainsi que l’état de synchronisation de l’application ArgoCD. Correctif. Mettez les deux charts à niveau vers la même version, puis attendez que les applications ArgoCD aient terminé leur synchronisation. Si l’opérateur affiche une condition Degraded, suivez le motif de dégradation jusqu’au composant défaillant, corrigez-le, puis annotez la ressource Vantage avec vantage.abbyy.com/reprocess pour relancer la tentative (Forcer une nouvelle tentative). Voir Upgrading.

​
Et ensuite

Architecture

Ce que fait l’opérateur à chaque réconciliation, avec un contexte utile pour le diagnostic.

Limites connues

Les contraintes actuelles qui définissent ce qui constitue réellement un bogue… ou non.