Zum Hauptinhalt springen
Auf dieser Seite finden Sie die Fehler, die uns bei der Installation und im laufenden Betrieb am häufigsten begegnen, zusammen mit den Diagnosebefehlen und den entsprechenden Lösungen. Jeder Eintrag folgt dem Schema Symptom → Diagnose → Behebung. Wenn Sie nicht weiterkommen, erfassen Sie vor der Kontaktaufnahme mit Ihrem ABBYY Account Team die Operator-Protokolle, den Status der Vantage-Ressource sowie den Status aller fehlgeschlagenen ArgoCD-Anwendungen:

​
Operator und CRD

​
Einen erneuten Versuch erzwingen, nachdem ein Ressourcenproblem behoben wurde

Symptom. Sie haben die eigentliche Ursache eines Fehlers behoben (ein fehlendes Key Vault-Secret hinzugefügt, RBAC-Berechtigungen erteilt, eine Datenbank repariert), aber der Operator hat nicht erneut reconciliiert. Diagnose. Der Operator reagiert auf Ereignisse an der Vantage-Ressource selbst; Statusänderungen außerhalb der Ressource (Key Vault-Berechtigungen, Netzwerkrichtlinien, externe Services) lösen keine Reconciliierung aus. Vantage-Ressourcen sind veränderbar, aber um die Installation von Vantage erneut anzustoßen, muss die Ressource mit vantage.abbyy.com/reprocess annotiert werden (beliebiger Wert). Behebung. Annotieren Sie die Vantage-Ressource mit vantage.abbyy.com/reprocess (beliebiger Wert), um ab der Preflight-Phase eine neue Reconciliierung zu erzwingen:
Aktualisieren Sie den Wert der Annotation (z. B. einen Zeitstempel) jedes Mal, wenn Sie einen erneuten Versuch auslösen möchten. Der Operator reconciliiert nur dann erneut, wenn sich der Wert der Annotation ändert.

​
Vantage-Ressource bleibt in Progressing hängen

Symptom. kubectl describe vantages.vantage.abbyy.com $release_name -n $install_namespace zeigt über längere Zeit Progressing=True an, und Ready wird nie True. Diagnose. Prüfen Sie status.degradationReasons[] der Ressource; der Operator weist dort auf die fehlschlagende Komponente hin. Prüfen Sie anschließend die entsprechende ArgoCD-Anwendung:
Behebung. Beheben Sie den zugrunde liegenden ArgoCD-Synchronisierungsfehler. Häufige Ursachen: Ein Helm-Chart benötigt einen Wert, über den der Cluster noch nicht verfügt (Key Vault secret fehlt, Fehler beim Image Pull), oder ein Ingress-Gateway ist nicht vorhanden. Nachdem das zugrunde liegende Problem behoben wurde, versehen Sie die Vantage-Ressource mit der Annotation vantage.abbyy.com/reprocess, um die Installation erneut anzustoßen (Erneuten Versuch erzwingen)).

​
Der Operator erkennt eine neue Vantage-Ressource nicht

Symptom. Sie wenden eine Vantage-Ressource an, und kubectl get vantages zeigt sie an, aber der Operator meldet nie einen Status. Diagnose. Prüfen Sie, ob der Operator läuft und die Reconciliierung durchführt:
Behebung. Der Operator überwacht Vantage-Ressourcen im gesamten Cluster; das Chart bietet keinen Wert, mit dem sich einschränken lässt, welche Namespaces überwacht werden. Wenn der Operator läuft, die Protokolle aber keine Reconciliierungsversuche für Ihre Ressource zeigen, vergewissern Sie sich, dass die CRD die vom Operator erwartete Version hat (vantage.abbyy.com/v1alpha1) und dass im Cluster genau eine Operator-Instanz installiert ist. Um die Werte anzuzeigen, die das Chart tatsächlich akzeptiert, führen Sie helm show values $charts_uri/vantage-operator --version $operator_version aus (Helm-Chart-Werte).

​
Anwenden der CRD schlägt mit einem Validierungsfehler fehl

Symptom. kubectl apply lehnt die Vantage-Ressource mit einer CEL-Validierungsmeldung ab. Diagnose. Die Fehlermeldung stammt aus den CEL-Regeln der CRD. Häufige Ursachen sind ein ociMigration-Block mit enabled: true, aber ohne destination, oder ein techcore-Block mit keepPreviousVersion: true, aber ohne previousVersion. Lösung. Setzen Sie das Feld, das in der Validierungsmeldung genannt wird. Siehe API-Referenz für die vollständigen Validierungsregeln.

​
OCI-Migration

​
OCI-Migrationsjob startet nie

Symptom. Die Vantage-Ressource bleibt auf Progressing; in Ihrem Installations-Namespace gibt es keinen Job namens $release_name-oci-migration. Diagnose. Prüfen Sie die Preflight-Prüfungen des Operators in den Operator-Protokollen sowie die Degradierungsgründe der Ressource. Der Job wird erst erstellt, wenn die Preflight-Prüfungen erfolgreich abgeschlossen sind. Behebung. Beheben Sie die fehlgeschlagene Preflight-Prüfung. Während der Preflight-Prüfungen wird die Konfiguration geprüft, einschließlich der Secrets-Konfiguration. Prüfen Sie daher zuerst, ob jeder erforderliche Alias in Ihrem Secrets-Provider vorhanden ist (Secrets and Key Vault).

​
OCI-Migrationsjob läuft, schlägt aber fehl

Symptom. kubectl -n $install_namespace get jobs zeigt den Migrationsjob an, aber er erreicht nicht den Status Complete. Diagnose. Überprüfen Sie die Protokolle des Jobs:
Behebung. Die meisten Fehler hängen mit der Authentifizierung zusammen: Der Job konnte entweder nicht aus der Quell-Registry abrufen (prüfen Sie bei jedem Eintrag in vantage.ociMigration.sources[] das Secret credentialsRef.name oder den Benutzernamen/das Kennwort) oder nicht an das Ziel pushen (prüfen Sie die Anmeldedaten für vantage.ociMigration.destination und das RBAC der Workload Identity, wenn Sie Azure Workload Identity verwenden). Wenn der Job-Pod sein Image selbst gar nicht erst abrufen kann, siehe Pods bleiben in ImagePullBackOff hängen.

​
Image-Pulls

​
Pods hängen in ImagePullBackOff

Symptom. Operator-Pods, der Pod des OCI-Migrationsjobs oder Vantage-Workload-Pods melden ImagePullBackOff oder ErrImagePull, und kubectl describe pod zeigt unauthorized: authentication required aus Ihrer Registry an. Diagnose. Ermitteln Sie die betroffenen Pods und den Registry-Fehler:
Behebung. Geben Sie der fehlschlagenden Komponente Pull-Zugriff auf Ihre Registry:
  • Operator-Pods: Aktualisieren Sie das Release vantage-operator mit --set "manager.imagePullSecrets[0].name=my-pull-secret".
  • OCI migration job: Führen Sie den Job mit einem ServiceAccount aus, der das Pull-Secret enthält (vantage.ociMigration.serviceAccountName=my-service-account), oder verweisen Sie im Source-Eintrag auf das Secret (vantage.ociMigration.sources[0].credentialsRef.name=my-pull-secret).
  • Vantage-Workloads: Fügen Sie das Pull-Secret zu den imagePullSecrets des ServiceAccounts hinzu, der in vantage.serviceAccountName angegeben ist. Wenn der fehlschlagende Pod einen anderen ServiceAccount meldet, einschließlich default, gewähren Sie diesem ServiceAccount Pull-Zugriff oder konfigurieren Sie die Komponente so, dass sie den vorgesehenen Vantage-ServiceAccount verwendet.
  • Unter AKS: Gewähren Sie statt Pull-Secrets der Kubelet-Identität des Clusters AcrPull für die Registry.
Siehe Azure-Image-Pull-Zugriff oder Zugriff auf die selbstverwaltete Registry für die vollständige Einrichtung.

​
Secrets

​
Pods starten nicht mit MountVolume.SetUp failed for volume "secrets-store"

Symptom. Vantage-Pods starten nicht; die Ereignisse des Pods zeigen Mount-Fehler des CSI-Treibers. Diagnose. Der Secrets Store CSI driver konnte kein Secret aus dem Key Vault abrufen. Die häufigsten Ursachen:
  • Die von vantage.secrets.azure.identityMode ausgewählte Identität hat keinen Lesezugriff auf das angegebene Secret oder Zertifikat.
  • Ein Key Vault-Objektname stimmt nicht mit dem Alias überein, den Vantage erwartet, und es wurde kein objects-Mapping angegeben.
  • Der Azure-Provider für den CSI-Treiber ist nicht installiert.
Behebung. Prüfen Sie, ob die konfigurierte Identität für jeden unter Secrets and Key Vault aufgeführten Alias über die Berechtigung get verfügt. Wenn Ihre Key Vault-Objektnamen von den Aliasen abweichen, geben Sie unter vantage.secrets.azure ein objects-Mapping an. Unter Identitätsmodi finden Sie, welche Identität in den einzelnen Modi verwendet wird.

​
Zugehörige TLS-Secrets fehlen

Symptom. Die Auth-Services starten nicht, und einer der vier TLS-Secret-Aliasse fehlt in Ihrem Key Vault. Diagnosis. Vantage benötigt vier PEM-kodierte Dateien, die als Key Vault-Secrets gespeichert sind: ein Zertifikat und einen privaten Schlüssel für die Auth-Signierung sowie ein Zertifikat und einen privaten Schlüssel für deaktivierte Auth-Token. Fix. Vergewissern Sie sich, dass alle vier Aliasse vorhanden sind: authSigningTlsCrt, authSigningTlsKey, authDeactivatedTlsCrt, authDeactivatedTlsKey. Siehe Secrets and Key Vault → Zertifikatsaliasse.

​
Kubernetes Secret-Provider schlägt beim Preflight fehl

Symptom. Eine selbstverwaltete Installation schlägt beim Preflight mit einem Fehler wegen eines fehlenden Secrets, eines fehlenden Schlüssels oder forbidden fehl. Diagnose. Der Operator liest beim Preflight native Secrets in $install_namespace. Das angegebene Secret existiert möglicherweise nicht, ein objects-Mapping verweist möglicherweise auf den falschen Namen, das Secret enthält möglicherweise nicht den erwarteten Schlüssel, oder das vom Chart erstellte RoleBinding verweist möglicherweise nicht auf das installierte Operator-ServiceAccount. Prüfen Sie die Berechtigung des Operators für eines der betroffenen Secrets:
Lösung. Vergewissern Sie sich, dass jedes Secret im Installations-Namespace vorhanden ist, und vergleichen Sie dann vantage.secrets.kubernetes.objects mit dem Inventar der Secret-Aliase. Wenn die Autorisierung fehlschlägt, stellen Sie sicher, dass die Werte operator.namespace und operator.controllerManagerServiceAccount des Vantage-Chart den installierten Operator angeben. Wenn ein externer Secrets-Controller die Secrets erstellt, warten Sie, bis er eine erfolgreiche Synchronisierung meldet, bevor Sie eine neue Reconciliierung des Operators erzwingen.

​
Datenbanken

​
PostgreSQL-Workloads melden „DataProvider nicht gefunden“

Symptom. Datenbankstart- oder Migrations-pods schlagen mit DataProvider '<value>' not found fehl. Diagnose. vantage.databaseProvider berücksichtigt Groß- und Kleinschreibung. Der PostgreSQL-Runtime-Provider heißt exakt PostgreSQL. Behebung. Setzen Sie:
Werte wie Postgresql und PostgreSql sind zur Laufzeit ungültig. Übernehmen Sie die korrigierten Werte und erzwingen Sie einen erneuten Versuch.

​
PostgreSQL-Schema ist nicht auf dem neuesten Stand

Symptom. Mehrere Services starten nicht und melden postgres database schema is not up to date oder Konflikte bei den Migrationsversionen. Diagnose. Mehrere Services verwenden dieselbe logische PostgreSQL-Datenbank. Jeder Service verwaltet seinen eigenen Migrationsverlauf und muss eine eigene Datenbank verwenden. Behebung. Erstellen Sie für jeden Datenbankalias eine separate Datenbank. Für Workloads, die den generischen Schlüssel Database__ConnectionString verwenden, erstellen Sie separate Kubernetes Secrets und ordnen Sie jeden Alias mit vantage.secrets.kubernetes.objects zu. Siehe PostgreSQL und Secrets pro Service.

​
ArgoCD

​
ArgoCD-Anwendung zeigt nach der Installation OutOfSync an

Symptom. kubectl get application -A meldet für eine der vom Operator verwalteten Anwendungen OutOfSync, obwohl der Operator ansonsten bereits Ready gemeldet hat. Diagnose. Sehen Sie sich die status.conditions[] der Anwendung an:
Behebung. Wenn die Abweichung auf manuelle Änderungen an vom Operator verwalteten Objekten zurückzuführen ist, setzen Sie diese zurück; diese Objekte gehören dem Operator und werden von ihm erneut synchronisiert. Wenn die Abweichung in einem Chart-Wert liegt, aktualisieren Sie ihn über die Vantage-Ressource (oder das Helm-Release vantage-selfhosted). Bearbeiten Sie das zugrunde liegende ArgoCD-Objekt Application niemals direkt.

​
ArgoCD-ApplicationSet-Sync hängt fest

Symptom. ArgoCD-Anwendungen kommen in ihren Synchronisierungswellen nie voran. Diagnose. Prüfen Sie, ob Progressive Syncs für ApplicationSet in Ihrer ArgoCD-Installation aktiviert sind:
Behebung. Aktivieren Sie Progressive Syncs entsprechend der ArgoCD-Dokumentation und starten Sie den ApplicationSet-Controller neu.

​
KEDA und Prometheus

​
ScaledObject-Ressourcen können keine HPAs erstellen

Symptom. KEDA meldet Ready=False oder ScaledObjectCheckFailed, und ArgoCD zeigt die Anwendungen der betroffenen Workloads als Degraded an. Diagnose. Überprüfen Sie die installierte KEDA-Version und die ScaledObject-Ereignisse:
Die aktuellen Vantage-Workload-Charts erfordern KEDA 2.17.x; in KEDA 2.18 und höher wurde ein von diesen Charts verwendetes Scaler-Feld entfernt. Behebung. Installieren Sie KEDA 2.17.3 und synchronisieren Sie anschließend die betroffenen ArgoCD-Anwendungen erneut.

​
HPA-Metriken zeigen <unknown>

Symptom. KEDA-Ressourcen sind vorhanden, aber kubectl get hpa zeigt für Vantage-Metriken <unknown> an, und Workloads skalieren nicht wie erwartet. Diagnose. Die ScaledObject-Ressourcen fragen http://prometheus-operated.observability.svc.cluster.local:9090 ab. Möglicherweise fehlt der Service, der Vantage-ServiceMonitor wird nicht ausgewählt oder das Service-Mesh blockiert das Scraping. Lösung. Vergewissern Sie sich, dass der Prometheus-Service vorhanden ist, seine Vantage-Ziele UP sind und die Werte des observability-Chart auf oberster Ebene definiert sind:
Siehe Autoskalierung mit KEDA für das Triggerverhalten und die Verifizierung sowie Überwachung mit Prometheus für die Istio- und Linkerd-Konfiguration.

​
Skill-Installation

​
Skills fehlen, obwohl die Installation Ready meldet

Symptom. Die Vantage-Ressource meldet Ready und Vantage ist erreichbar, aber die erwarteten Skills fehlen, und in ArgoCD ist nichts zu Skills zu sehen. Diagnosis. Skills werden über einen separaten Kubernetes-Job installiert, der in ArgoCD nicht angezeigt wird. Deshalb erscheint er nie in argocd app list (einschließlich der Diagnoseerfassung oben auf dieser Seite). Der Job kann auch nach Ready noch laufen; Sie können Vantage in der Zwischenzeit trotzdem verwenden. Prüfen Sie den Job:
Behebung. Wenn der Job noch ausgeführt wird, warten Sie, bis er den Status Complete erreicht. Wenn der Job fehlgeschlagen ist, prüfen Sie seine Protokolle auf die zugrunde liegende Fehlerursache und beheben Sie sie. Wenn der Fehler weiterhin besteht, erfassen Sie die Job-Protokolle zusammen mit den Operator-Protokollen für Ihr ABBYY Account Team.

​
Service Mesh und Ingress

​
503 vom Ingress, Anwendungsdatenverkehr blockiert

Symptom. https://$your_vantage_hostname gibt 503 zurück, obwohl die Pods Ready melden. Diagnose. Unter AKS mit dem integrierten Istio-Ingress ist das externe Gateway möglicherweise nicht fehlerfrei, oder das TLS-Secret stimmt nicht mit ingress.tls.secretName überein. Bei kundenseitig verwaltetem Ingress hat der Controller möglicherweise keine passende Route, der Service-Name oder Port des Backends ist möglicherweise falsch, oder das TLS-Zertifikat ist möglicherweise noch nicht verfügbar. Behebung. Prüfen Sie bei Istio das Gateway und das TLS-Secret:
Bestätigen Sie, dass im Namespace des externen Gateways ein Secret vom Typ kubernetes.io/tls mit dem im Chart angegebenen Namen vorhanden ist und dass sein Zertifikat für dnsRecord gültig ist. Prüfen Sie bei kundenseitig verwaltetem Ingress die Controller-Protokolle und den Status der Route. Bestätigen Sie, dass der Hostname der Route vantage.dnsRecord entspricht, TLS bereit ist und jeder Backend-Service in $install_namespace vorhanden ist. Siehe Ingress und TLS konfigurieren.

​
Anmeldeweiterleitungen oder OIDC-Metadaten verwenden http://

Symptom. Vantage wird über HTTPS bereitgestellt, aber die Anmeldung als Plattformadministrator schlägt fehl oder /auth2/.well-known/openid-configuration weist einen http://-Issuer und http://-Endpunkte aus. Diagnose. TLS wird am Ingress-Controller beendet, aber die Authentifizierungs-Workloads berücksichtigen das weitergeleitete HTTPS-Schema nicht. Lösung. Vergewissern Sie sich, dass der Ingress X-Forwarded-Proto: https sendet und dass die Anwendungs-Container für auth-identity, auth-adminapi2, api-gateway und api-registry Folgendes aufweisen:
Wenn Ihr Workload-Chart diese Umgebungseinstellung nicht bereitstellt, wenden Sie Ihre genehmigte Admission-Mutation an, bevor Sie die betroffenen Pods neu starten. Siehe Forwarded HTTPS scheme.

​
Prometheus-Scrape-Targets werden für /metrics-text als DOWN angezeigt

Symptom. Im In-mesh Prometheus werden die Targets der Vantage-Anwendung als DOWN angezeigt. Diagnose. Unter Istio fehlt dem Prometheus-Pod möglicherweise sein Sidecar, oder die von Istio ausgegebenen Zertifikate werden nicht nach /etc/prom-certs/ geschrieben. Unter Linkerd kann eine strikte Autorisierungsrichtlinie Plaintext-Scrapes von einem nicht im Mesh befindlichen Prometheus blockieren.
Lösung. Vergewissern Sie sich bei Istio, dass der Prometheus-Pod drei Container (prometheus, config-reloader, istio-proxy) enthält und dass die annotation proxy.istio.io/config mit OUTPUT_CERTS: /etc/istio-output-certs vorhanden ist. Injizieren Sie bei Linkerd den namespace observability, oder konfigurieren Sie ServiceMonitor und Prometheus mit den gemäß Ihrer Richtlinie erforderlichen Clientzertifikaten. Weitere Informationen finden Sie unter Überwachung mit Prometheus.

​
Betrieb ab Tag 2

​
Nach dem Upgrade meldet der Operator die neue Version, aber Vantage läuft noch mit der alten

Symptom. status.installedVantageVersion ist nach dem Upgrade der Helm-Releases unverändert. Diagnose. Die Releases vantage-operator und vantage-selfhosted haben möglicherweise nicht dieselbe neue Version, oder ArgoCD wendet die Änderungen pro Komponente noch an. Prüfen Sie beide Helm-Releases und den Synchronisierungsstatus der ArgoCD-Anwendung. Lösung. Führen Sie für beide Charts ein Upgrade auf dieselbe Version durch und warten Sie dann, bis die ArgoCD-Anwendungen die Synchronisierung abgeschlossen haben. Wenn der Operator die Bedingung Degraded anzeigt, ermitteln Sie anhand des Degradierungsgrunds die fehlerhafte Komponente, beheben Sie das Problem und annotieren Sie dann die Ressource Vantage mit vantage.abbyy.com/reprocess, um einen erneuten Versuch auszulösen (Erneuten Versuch erzwingen). Siehe Upgrade.

​
Wie geht es weiter?

Architektur

Was der Operator bei jedem Reconcile tut – hilfreicher Kontext bei der Fehlerdiagnose.

Bekannte Einschränkungen

Aktuelle Einschränkungen, die bestimmen, was tatsächlich als Fehler gilt – und was nicht.