AnmeldenBriefing buchen

Kapitel 2.17

Fehlerbehebung

Die Probleme, denen Betreiber am häufigsten begegnen, geordnet nach dem jeweiligen Symptom. Zu jedem Problem werden die Ursache, der Befehl zur Bestätigung und die Lösung genannt; das Kapitel endet mit dem Einsenden eines Support-Bundles.

Diese Seite wurde mithilfe von KI aus dem englischen Original übersetzt. Bei Unklarheiten gilt die englische Seite als Referenz. Diese Seite auf Englisch lesen

22 Minuten Lesezeit

Das meiste, was bei einer Nexus-Installation schiefgeht, verläuft nach demselben Dutzend Muster, und fast alle kündigen sich mit einem Code an. Dieses Kapitel ist nach dem geordnet, was Sie sehen, etwa in der Reihenfolge, in der Sie auf die jeweiligen Probleme stoßen würden: Installieren, Beanspruchen, Lizenzieren und anschließend der Betrieb. Für jedes Problem erhalten Sie die Ursache, einen Befehl zur Bestätigung und die Lösung.

Die Beispiele verwenden die Installation der Harrow Port Authority: Namespace nexus, Release nexus, Hosts console.harrow.example, api.harrow.example und auth.harrow.example. Ersetzen Sie diese durch Ihre eigenen. Drei Gewohnheiten sparen bei jedem hier beschriebenen Problem Zeit:

  1. Lesen Sie den Code vor der Meldung. Jede Ablehnung in Nexus endet mit einem Maschinencode, und nach diesem Code ist dieses Kapitel indiziert.
  2. Führen Sie nexusctl preflight nach jeder Änderung am Cluster oder an der Values-Datei erneut aus. Es liest den Cluster, ohne ihn zu verändern, und meldet die meisten Chart-Ablehnungen namentlich, noch bevor Helm dies tut.
  3. Verwenden Sie --explain bei jedem nexusctl-Verb, bei dem Sie sich unsicher sind. Es gibt die kubectl- und helm-Operationen aus, ohne sie auszuführen.

Die Installation hängt

Sie haben die Installation gestartet und sie wird nicht abgeschlossen. helm ist nach fünfzehn Minuten noch nicht zurückgekehrt, oder es ist zurückgekehrt und Pods befinden sich weiterhin im Status Init oder Pending, oder die Konsolenadresse antwortet nicht.

Die häufigste Ursache ist helm install --wait. Nexus erstellt seine Datenbank, seine Rollen und das Schema jedes Dienstes in Post-Install-Hooks, und der Bootstrap-Hook übergibt jedem Dienst sein Datenbankpasswort. Mit --wait wartet Helm darauf, dass die Deployments bereit sind, bevor es diese Hooks ausführt, während die Deployments auf die Hooks warten. Keines von beiden bewegt sich. Installieren Sie niemals mit --wait; installieren Sie ohne diese Option und warten Sie anschließend.

Eine vertikale Abfolge von Kästchen, die durch nach unten weisende Pfeile verbunden sind: „Release-Ressourcen erstellt (Deployments starten, jedes gehalten von seinem wait-for-schema-Init-Container)“, dann „Datenbank-Bootstrap-Hook: Datenbank, Rollen, Release-Verzeichnis“, dann „Migrations-Hooks, einer pro Dienst, in fester Reihenfolge“, dann „Jeder Hook schreibt seine Zeile in das Release-Verzeichnis“. Vom letzten Kästchen fächern sich Pfeile seitlich zu drei kleinen Kästchen auf: „nexus-auth startet“, „nexus-gateway startet“, „andere Dienste starten“. Eine Randnotiz neben dem obersten Kästchen mit einem durchgestrichenen Pfeil nach ganz unten: „helm install --wait wartet hier auf Deployments, die auf die Hooks warten“.
Was der Reihe nach abläuft, wenn das Chart installiert oder aktualisiert wird.

Die anderen Ursachen sind gewöhnliche Kubernetes-Ursachen. Images können nicht abgerufen werden, weil global.imageRegistry die falsche Registry benennt oder einer Enterprise-Installation das Pull-Token fehlt. Ein Volume bleibt im Status Pending, weil die Speicherklasse nicht existiert. cert-manager fehlt, wobei die Installation in diesem Fall überhaupt nicht hängt: Sie schlägt innerhalb von Sekunden fehl, da die Zertifikatsaussteller des Charts die Ressourcen von cert-manager benötigen.

Beginnen Sie mit den Pods und den Hook-Jobs:

kubectl -n nexus get pods,jobs
kubectl -n nexus describe pod <pod-name>
kubectl -n nexus logs job/<job-name>
kubectl get crd certificates.cert-manager.io

describe zeigt Fehler beim Abrufen von Images und ungebundene Volumes in seinen Ereignissen an. Ein Hook-Job, der 0/1 Abschlüsse mit einem fehlgeschlagenen Pod anzeigt, hat die Installation gestoppt, da Hook-Jobs ein Backoff-Limit von 0 haben und niemals stillschweigend wiederholt werden. Sein Protokoll gibt Aufschluss über den Grund.

So beheben Sie die jeweiligen Ursachen:

  • Wenn Helm mit --wait wartet, brechen Sie den Vorgang ab, deinstallieren Sie und installieren Sie erneut ohne das Flag. Warten Sie dann auf die Dienste:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
  • Überprüfen Sie bei Pull-Fehlern global.imageRegistry und bei Enterprise das Pull-Token auf der Seite „Pull tokens and install commands“ Ihres Kontos.
  • Setzen Sie bei Pending-Volumes storage.className auf eine Speicherklasse, über die der Cluster verfügt, oder legen Sie eine als Standard fest.
  • Installieren Sie bei einem fehlenden cert-manager die Version cert-manager v1.21.3 und führen Sie die Installation erneut aus.
  • Beheben Sie bei einem fehlgeschlagenen Hook das, was in seinem Protokoll genannt wird, und führen Sie die Installation erneut aus.

Ein Pod wartet auf sein Schema

Der Pod eines Dienstes verharrt minutenlang im Status Init:0/1. Jeder Dienst, der die Datenbank nutzt, verfügt über einen Init-Container, wait-for-schema, der den Pod anhält, bis das Release-Verzeichnis anzeigt, dass seine Migrationen für das Image dieses Releases angewendet wurden. Das ist in den ersten Minuten einer Installation oder eines Upgrades normal, während die Migrations-Hooks laufen. Zum Problem wird es, wenn dieser Zustand nicht endet.

Lesen Sie das Protokoll des Init-Containers:

kubectl -n nexus logs <pod-name> -c wait-for-schema

Das Protokoll nennt die Komponente, die Migrationsketten, auf die sie wartet, sowie ihr Zeitlimit und gibt dann jedes Mal eine Zeile aus, wenn sich ihr Status ändert:

wait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations=sha256:…; gives up after 1800s
Aussage der Fortschrittszeile Bedeutung
Welche Ketten für dieses Release noch angewendet werden müssen Die genannten Migrations-Hooks sind noch nicht abgeschlossen. Sehen Sie sich diese Jobs an.
Dass das Release-Verzeichnis nicht gelesen werden kann, zusammen mit dem Fehler der Datenbank Postgres antwortet nicht, oder das Verzeichnis existiert nicht, weil der Datenbank-Bootstrap nicht ausgeführt wurde.
FAILED (<component>): after <n>s, … Es hat nach schemaWait.timeoutSeconds (standardmäßig 1.800) aufgegeben. Der Init-Container startet neu; der Dienst selbst wurde nie gestartet.

Eine Kette, die niemals angewendet wird, bedeutet fast immer, dass ihr Migrations-Job fehlgeschlagen ist. Suchen Sie ihn mit kubectl -n nexus get jobs und lesen Sie sein Protokoll. Beheben Sie das dort genannte Problem (eine volle Festplatte, eine externe Datenbank, die der Migrator nicht erreichen kann, ein Rollenkonflikt) und führen Sie helm upgrade mit denselben Werten aus: Die Hooks laufen erneut, und jeder einzelne kann bedenkenlos erneut ausgeführt werden.

Erhöhen Sie schemaWait.timeoutSeconds nur dann, wenn eine Migration langsam, aber fehlerfrei verläuft, wie es bei einer großen Erstmigration auf langsamem Speicher der Fall sein kann. Den Wert zu erhöhen, um einen fehlgeschlagenen Job zu kaschieren, führt nur dazu, dass der Pod länger auf etwas wartet, das nie eintreten wird.

Der Schlüsselspeicher ist versiegelt

Nach einem Stromausfall, einem Knoten-Neustart oder einem Neustart der Container-Laufzeitumgebung kehren die Pods zurück und die Konsole lädt, aber alles, was einen Schlüssel benötigt, schlägt fehl oder wartet. Der Unsealer startet nach jedem Neustart seines Knotens im versiegelten Zustand, und der Schlüsselspeicher kann sich erst dann selbst entsiegeln, wenn der Unsealer geöffnet ist.

Fragen Sie OpenBao in jedem Pod ab:

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

Exit-Code 0 bedeutet entsiegelt, 2 bedeutet versiegelt und 1 bedeutet, dass er nicht antworten konnte (fragen Sie in einer Minute erneut nach). Führen Sie dasselbe gegen openbao-0 mit -tls-server-name=openbao für den Schlüsselspeicher aus. Wenn der Unsealer entsiegelt ist und der Schlüsselspeicher nicht, entsiegelt sich der Schlüsselspeicher gerade selbst; geben Sie ihm eine Minute Zeit.

Um einen versiegelten Unsealer zu reparieren, führt ein Treuhänder (Custodian) das unseal.sh des Charts mit seiner eigenen age-Identität aus. Kapitel 2.15, Tag zwei: Betrieb von Nexus, enthält den vollständigen Befehl. Der Exit-Code des Skripts verrät Ihnen, was passiert ist:

Beenden Bedeutung Vorgehensweise
0 Entsiegelt Überprüfen Sie kubectl -n nexus get deploy,statefulset innerhalb einer Minute.
1 Noch versiegelt, oder ein Aufruf zum Entsiegeln ist fehlgeschlagen Lesen Sie die ausgegebenen Share-Zeilen; führen Sie es erneut aus.
2 Eine Voraussetzung fehlt Die Meldung nennt sie beim Namen: AGE_IDENTITY, eine Binärdatei wie age oder jq oder eine Einstellung für den Direktmodus.
3 Diese Identität kann die Shares nicht entschlüsseln Sie sind kein Treuhänder dieser Installation. Es wurde nichts übermittelt. Suchen Sie einen Treuhänder, der berechtigt ist.

Anmeldung über HTTP nicht möglich

Die Konsole lädt unter einer http://-Adresse oder über ein kubectl port-forward zu 127.0.0.1, und die Anmeldung schlägt fehl. Die Passkey-Aufforderung erscheint nie, oder die Anmeldung springt in einer Schleife immer wieder an den Anfang zurück.

Die Anmeldung erfordert den eigenen HTTPS-Ursprung der Konsole. Die Konsole akzeptiert eine Anmeldung nur von https://<hosts.console>, speichert die Sitzung in einem als Secure markierten __Host--Cookie (das ein Browser nur über HTTPS speichert), und der Passkey des ersten Administrators benötigt eine Seite mit einem gültigen Zertifikat. Browser verweigern Passkeys hinter einem Zertifikatsfehler. Eine Port-Weiterleitung zu http://127.0.0.1 kann sich niemals anmelden.

Überprüfen Sie, was der Browser tatsächlich erreicht hat:

curl -sI https://console.harrow.example
kubectl -n nexus get ingress

Der erste Befehl sollte über HTTPS mit einem Zertifikat antworten, dem Ihr Rechner vertraut. Der zweite sollte die drei Hosts mit den Namen anzeigen, die Sie in hosts.* festgelegt haben.

Um das Problem zu beheben, rufen Sie die Konsole unter https://console.harrow.example auf, dem exakten Namen in hosts.console, und zwar mit einem Zertifikat, dem der Browser vertraut. Überprüfen Sie bei tls.mode: existing, ob tls.existingSecret ein Zertifikat für alle drei Hosts enthält. Überprüfen Sie bei tls.mode: cert-manager, ob der ClusterIssuer es ausgestellt hat. Bei tls.mode: none endet Transport Layer Security (TLS) auf Ihrem eigenen Load Balancer, und genau dort muss das Zertifikat korrekt sein. Bei einer privaten Zertifizierungsstelle installieren Sie deren Zertifikat auf den Rechnern, von denen aus sich Ihre Administratoren anmelden.

Der Übernahmecode ist abgelaufen

Auf der Seite „Claim this installation“ lehnt die Seite den Code mit CLAIM_CODE_EXPIRED (410) ab. Ein Beanspruchungscode besteht aus drei Gruppen zu je vier Zeichen. Er funktioniert einmalig, für 30 Minuten und mit 5 Versuchen. Danach oder nach dem fünften Fehlversuch ist er ungültig, und es wurde nichts beansprucht oder geändert.

Erzeugen Sie über das Terminal mit Cluster-Zugriff einen neuen Code:

nexusctl claim-code --administrator aoife.brennan@harrow.example

Dies gibt einen neuen Code und den Fingerabdruck der Installation aus. Geben Sie den Code innerhalb von 30 Minuten auf der Beanspruchungsseite ein und vergleichen Sie den Fingerabdruck erneut.

Diese Installation übernehmen
Diese Installation übernehmen
Beanspruchen Sie diese Installation. Der Code aus dem Terminal wird in drei Gruppen eingegeben, und die Seite zeigt zum Vergleich den vollständigen Fingerabdruck in Vierergruppen an; ein abgelaufener Code wird mit CLAIM_CODE_EXPIRED abgelehnt und es wird nichts beansprucht.

Zwei verwandte Antworten:

  • RATE_LIMITED (429) auf der Beanspruchungsseite bedeutet, dass es auf der Seite in der letzten Minute mehrere Versuche gab. Warten Sie die angegebene Anzahl von Sekunden ab. Wenn diese Versuche nicht von Ihnen stammen, versucht jemand anderes in Ihrem Netzwerk, auf die Seite zuzugreifen; finden Sie heraus, wer das ist, bevor Sie die Installation beanspruchen.
  • TRANSITION_NOT_PERMITTED (409) bedeutet, dass die Installation bereits beansprucht wurde und ihre Beanspruchungsseite dauerhaft abgeschaltet ist. Melden Sie sich stattdessen an. Wenn nicht Sie die Installation beansprucht haben, behandeln Sie dies als Sicherheitsvorfall.

Der Fingerabdruck stimmt nicht überein

Die Beanspruchungsseite zeigt CLAIM_FINGERPRINT_MISMATCH (403) an, oder Sie sehen selbst, dass die acht Vierergruppen auf der Seite von denen abweichen, die Ihr Terminal ausgegeben hat. Schon eine einzige abweichende Gruppe bedeutet, dass der Browser mit einer anderen Installation kommuniziert.

Stopp. Geben Sie den Code nicht auf dieser Seite ein. Möglicherweise antwortet unter dieser Adresse etwas anderes als Ihre Installation, eventuell ein Rechner, der eingerichtet wurde, um den ersten Administrator abzufangen. Würden Sie sie beanspruchen, hätte dieser Rechner die Kontrolle über Ihre Organisation. Ihre eigene Installation ist unverändert und weiterhin unbeansprucht.

Überprüfen Sie, wohin der Name verweist und welches Zertifikat geantwortet hat:

nslookup console.harrow.example
kubectl -n nexus get ingress
curl -svI https://console.harrow.example

Die Adresse sollte die Ihres Ingress-Controllers sein, und das Zertifikat sollte dasjenige sein, das Sie für hosts.console installiert haben.

Fingerabdruck stimmt nicht überein
Fingerabdruck stimmt nicht überein
Die Fingerabdrücke unterscheiden sich in drei von acht Gruppen. Die Seite fordert zum Innehalten auf, erklärt, wer möglicherweise antwortet, und listet auf, was vor einem erneuten Versuch zu prüfen ist.

Um das Problem zu beheben, übergeben Sie Ihrem Sicherheitsteam die Adresse, die geantwortet hat, und bewahren Sie das Installationsprotokoll auf, in dem der von der Installation ausgegebene Fingerabdruck festgehalten ist. Korrigieren Sie den Eintrag im Domain Name System (DNS) oder den Proxy, der Sie fehlgeleitet hat. Erzeugen Sie dann mit nexusctl claim-code --administrator <email> einen neuen Beanspruchungscode und führen Sie die Beanspruchung über einen Browser in einem vertrauenswürdigen Netzwerk durch, wobei Sie erneut alle acht Gruppen vergleichen.

Die Lizenz wird abgelehnt

Der Import unter „Import the licence“, „Import a new licence“ oder nexusctl licence import antwortet mit einer Ablehnung. Ein abgelehnter Import ändert nichts: Die geltende Lizenz bleibt in Kraft, und die Zeituntergrenze (Clock Floor) verschiebt sich nicht.

Lesen Sie den Code und den Schritt:

curl --fail-with-body -X POST https://auth.harrow.example/api/v1/installation/licence \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  --data-binary @harrow-2027.licence.json

Der Rumpf der Ablehnung enthält code, message, refused_at (den fehlgeschlagenen Schritt) und troubleshooting. Um den Status der geltenden Lizenz einzusehen, lesen Sie GET https://auth.harrow.example/api/v1/installation/licence/state mit demselben Token aus.

Code HTTP Übliche Ursache Lösung
LICENCE_SIGNATURE_INVALID 422 Die Datei wurde bearbeitet, neu formatiert oder neu gespeichert, oder eine Signatur fehlt Laden Sie sie erneut aus Ihrem Konto herunter und importieren Sie sie unverändert
LICENCE_FORMAT_INVALID 422 Keine Lizenz: falsche Datei, abgeschnitten oder in ein anderes Objekt eingebettet Senden Sie die Datei genau so, wie Adverant sie bereitgestellt hat
LICENCE_ROOT_UNKNOWN 422 Mit einem Schlüssel signiert, den dieses Release nicht enthält Führen Sie ein Upgrade durch oder fordern Sie eine für Ihr Release signierte Lizenz an
LICENCE_MATRIX_MISMATCH 422 Für eine neuere Editionsmatrix geschrieben, oder gewährt eine Gruppe, die dieser Build nicht kennt Führen Sie ein Upgrade durch oder fordern Sie eine auf Ihr Release zugeschnittene Lizenz an
LICENCE_OTHER_INSTALLATION 409 Für eine andere Installation ausgestellt, häufig die Lizenz des Test-Clusters auf dem Produktivsystem Fordern Sie eine Lizenz für die Identität dieser Installation an
LICENCE_REVOKED 403 Adverant hat sie zurückgezogen Fordern Sie bei Adverant eine neue Lizenz an
LICENCE_LOCKED 403 Ihr starts_on liegt nach dem aktuellen Datum Importieren Sie sie an oder nach ihrem ersten Gültigkeitstag
TRANSITION_NOT_PERMITTED 409 Diese Lizenz-ID wurde bereits importiert Kein Handlungsbedarf, wenn sie in Kraft ist; wenden Sie sich an Adverant, falls sich die Bedingungen ändern müssen
RECORD_NOT_FOUND 404 Die Installation wurde noch nicht deklariert und hat daher noch keine Identität Schließen Sie den Schritt für den ersten Administrator ab und importieren Sie dann
TENANT_NOT_A_PARAMETER 403 Der Rumpf benennt auf seiner obersten Ebene eine Organisation Senden Sie ausschließlich die Lizenzdatei als Rumpf

Zwei Dinge sehen aus wie Lizenzprobleme, sind es aber nicht. Eine Statusabfrage, die LICENCE_CLOCK_BEHIND_FLOOR enthält, bedeutet, dass die Uhr des Knotens eine frühere Zeit anzeigt als den letzten Zeitpunkt, den die Installation gesehen hat; korrigieren Sie die Zeit des Knotens, und falls die Uhr vorgegangen war und die Zeituntergrenze mitgezogen hat, fordern Sie bei Adverant ein Token zum Zurücksetzen der Zeit an. Und eine Lizenz, die sich importieren lässt, eine Gruppe aber weiterhin nur als Vorschau (Teaser) anzeigt, gewährt diese Gruppe in der Regel nicht: Prüfen Sie vor allem anderen die Berechtigungen (Grants) auf der Lizenzseite.

Keine KI-Antworten

Der Assistent für künstliche Intelligenz (KI) zeigt MODEL_NOT_CONNECTED (503) an, ein Workflow-Schritt schlägt mit NO_PROVIDER_FOR_ROLE (422) fehl oder die Antworten bleiben einfach aus.

Der Pool der Organisation verfügt über keinen Schlüssel, der antworten kann, oder der Router kann den Anbieter nicht erreichen. Jede Organisation bringt ihren eigenen Modellschlüssel mit. Ohne aktiven Schlüssel gibt es konzeptionsgemäß keine KI, und es springt auch kein gemeinsam genutzter Schlüssel ein.

Überprüfen Sie den Pool und die Auswahl des Routers, jeweils mit dem persönlichen Zugriffstoken des Nutzers:

GET https://console.harrow.example/api/v1/ai-providers
GET https://api.harrow.example/api/ai/routing-policy/effective

Der erste Befehl listet jeden Anbieter auf, ob er antworten kann und warum nicht ("No key in use: 1 withdrawn, 1 lapsed"), sowie den Status jedes Schlüssels. Der zweite gibt das Modell zurück, das der Router für die Organisation verwenden würde, oder seine ausformulierte Ablehnung. Überprüfen Sie anschließend mit diesen beiden Befehlen den Pfad aus dem Cluster heraus:

kubectl -n nexus get networkpolicy nexus-operator-egress -o yaml
kubectl -n nexus logs deploy/nexus-gateway

Was die einzelnen Ergebnisse bedeuten:

Befund Lösung
Kein Schlüssel im Pool Ein Eigentümer oder Administrator fügt auf der KI-Schaltzentrale (AI switchboard) oder unter „Settings, AI models“ einen Organisationsschlüssel hinzu
Schlüssel invalid, expired oder exhausted Fügen Sie einen neuen Schlüssel hinzu; der alte bleibt als Verlauf aufgelistet
Schlüssel resting Warten Sie: Ein fehlschlagender Schlüssel pausiert für 60 Sekunden, und nach 5 Fehlversuchen in Folge wird er abgeschaltet (PROVIDER_KEY_SWITCHED_OFF)
NO_PROVIDER_FOR_ROLE bei aktiven Schlüsseln Die Rolle hat keine Zuweisung und nichts passt; legen Sie die Rolle in der Routing-Richtlinie fest
MODEL_CAPABILITY_UNAVAILABLE (422) Die Anfrage erfordert eine Fähigkeit oder einen Datenstandort (Residency), den kein Anbieter im Pool bietet; aktivieren Sie einen Anbieter, der dies unterstützt
Keine nexus-operator-egress-Richtlinie, oder die Bereiche des Anbieters fehlen darin Fügen Sie die Bereiche in Classless Inter-Domain Routing (CIDR)-Notation zu networkPolicy.externalEgressCIDRs hinzu und führen Sie ein Upgrade durch
Ein lokaler Modellserver, der nicht antwortet Überprüfen Sie ai.localProvider.baseUrl, tragen Sie den Server in ai.installationHosts ein und geben Sie seinen Bereich in networkPolicy.externalEgressCIDRs frei

Ein Schlüssel eines gehosteten Anbieters, der von einem Laptop aus funktioniert und in der Installation fehlschlägt, liegt fast immer an der Netzwerkrichtlinie. Der Namespace verweigert standardmäßig ausgehenden Datenverkehr (Egress).

429-Antworten

Ein Client erhält die Antwort 429 Too Many Requests. In Nexus gibt es vier Stellen, von denen diese Meldung stammen kann, und der Rumpf verrät Ihnen, welche es ist.

Wo Code und Details Was zu ändern ist
nexus-auth, pro angemeldeter Person RATE_LIMITED mit limit, windowSeconds und retryAfterSeconds auth.rateLimitPerMinute (Standardwert 5000), für intensive Automatisierung
Ein Limit für Skriptschlüssel, Apps oder Einheiten (Enterprise) RATE_LIMITED unter Nennung des Schlüssels und seines Limits Das Limit unter „Settings, Rate limits“, mit einer Begründung
Die Beanspruchungsseite beim ersten Start RATE_LIMITED mit retry_after_seconds Nichts: Warten Sie ab und finden Sie heraus, wer sonst noch versucht, auf die Seite zuzugreifen
Ein Modellanbieter Der Router behandelt dies als vorübergehenden Fehler und wechselt zum nächsten Anbieter Fügen Sie einen weiteren Schlüssel oder Anbieter hinzu, wenn dies häufig vorkommt

Jede dieser Antworten enthält einen Retry-After-Header. Ein sich korrekt verhaltender Client wartet so lange und versucht es nicht früher erneut.

Wenn es so aussieht, als würden sich alle Benutzer gleichzeitig ein einziges Limit teilen, überprüfen Sie proxy.trustedCIDRs. Wenn dieser Wert das Pod-Netzwerk Ihres Ingress-Controllers nicht abdeckt, kann nexus-auth dem X-Forwarded-For-Header nicht vertrauen und betrachtet jede Anfrage so, als käme sie vom Controller. Der Standardwert, 10.42.0.0/16, passt nur für k3s.

kubectl get pods -A -o wide

Suchen Sie in der Ausgabe nach der Pod-Adresse des Ingress-Controllers und stellen Sie sicher, dass proxy.trustedCIDRs diese abdeckt.

Upgrade-Fehler

Das Upgrade wurde zurückgerollt. Die Upgrade-Seite zeigt UPGRADE_ROLLED_BACK an: Ein Schritt ist fehlgeschlagen, jede Engine befindet sich wieder auf dem vorherigen Release und es wurden keine Daten verändert. Die Seite benennt den Schritt. Ein häufiger Grund ist ein Volume, das für das neue Layout eines Speichers zu klein ist. Beheben Sie das genannte Problem, führen Sie nexusctl upgrade plan --bundle <file> erneut aus und wenden Sie das Upgrade dann an. Zuvor wird erneut ein Backup erstellt.

Das Chart verweigert das Rendern mit EXTERNAL_KEY_ENCRYPTION_KEY_INVALID. Das Secret nexus-generated enthält EXTERNAL_KEY_ENCRYPTION_KEY in einer Form, die das Chart nicht verwenden kann. Es muss ein Base64-Wert von 32 Byte oder der unkodierte 32-Byte-Schlüssel einer älteren Installation sein. Jemand hat das Secret bearbeitet oder ersetzt. Stellen Sie den Schlüssel wieder her, mit dem die Daten dieser Installation versiegelt sind, und zwar als Base64-Wert seiner 32 Byte (printf %s "$OLD" | base64), und führen Sie das Upgrade erneut durch. Lassen Sie das Chart keinen neuen Schlüssel erzeugen: Daten, die mit dem alten Schlüssel versiegelt wurden, blieben sonst unlesbar.

Skripte werden nach dem Upgrade mit TOKEN_ORG_MISSING abgelehnt. Jeder Dienst, der Application Programming Interface (API)-Schlüssel über nexus-auth prüft, lehnt nun Schlüssel ohne Organisation mit 403 TOKEN_ORG_MISSING ab. Weisen Sie jedem dieser Schlüssel eine Organisation zu oder stellen Sie einen neuen Schlüssel aus.

Schlüssel melden eine Stunde lang die falsche Anwendung. Leeren Sie die zwischengespeicherten Schlüsseleinträge im Cache von nexus-auth, dem Valkey-Speicher der Installation. Kapitel 2.15, Tag zwei: Betrieb von Nexus, enthält den Befehl sowohl für den Cluster-internen als auch für einen externen Speicher.

Ein Migrations-Hook ist fehlgeschlagen. helm upgrade meldet einen fehlgeschlagenen Pre-Upgrade-Hook. Das Schema wird aktualisiert, bevor die neuen Pods ausgerollt werden, sodass das laufende Release weiterhin den Betrieb übernimmt. Lesen Sie das Protokoll des Jobs mit kubectl -n nexus logs job/<job-name>, beheben Sie das dort genannte Problem und führen Sie das Upgrade erneut aus.

Dienste konnten einige Sekunden lang nicht auf ihre Tabellen zugreifen. Beim ersten Upgrade einer Installation, die mit einem älteren Chart erstellt wurde, verliert jeder Dienst seine alten Standard-Tabellenrechte und erhält seine eigenen Rechte durch seine eigene Migration zurück. Diese Lücke dauert nur Sekunden. Führen Sie das Upgrade in einer ruhigen Phase durch oder skalieren Sie die Dienste zuvor auf null.

Das Release auf dem Datenträger wurde abgelehnt. Der Import vom Datenträger zeigt MEDIA_SIGNATURE_INVALID (422) an: Die Dateien sind nicht mit dem auf dieser Installation installierten Release-Schlüssel signiert. Es wurde nichts geladen und das laufende Release läuft weiter. Bewahren Sie den Datenträger für Ihr Sicherheitsteam auf und fordern Sie bei Adverant über den Offline-Austausch einen neuen Datenträger an.

Ablehnung beim Rendern des Charts

helm install, helm upgrade oder helm template bricht ab, bevor irgendetwas angewendet wird, und gibt eine Meldung aus, die mit einem Code beginnt oder einen Wert benennt. Das Chart lehnt Werte ab, die es nicht sicher ausführen kann. Am Cluster wurde nichts verändert.

Rendern Sie das Chart separat, um jede Ablehnung zu sehen, ohne den Cluster anzufassen. Verwenden Sie bei Enterprise das heruntergeladene Enterprise-Chart anstelle der oci://-Adresse und setzen Sie networkPolicy.apiServerCIDRs in den Werten, da ein Offline-Rendering diesen Wert nicht aus dem Cluster auslesen kann:

helm template nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> \
  -n nexus -f harrow-values.yaml > /dev/null
nexusctl preflight --context harrow-prod --values harrow-values.yaml

Preflight prüft dieselben Identitätswerte in seinem Abschnitt „time and keys“ und meldet dieselben Codes. Sein Exit-Code ist 0, wenn die Installation fortgesetzt werden kann (Warnungen blockieren nicht), 1, wenn mindestens eine Prüfung fehlgeschlagen ist, und 2, wenn es nicht ausgeführt werden konnte.

Vorabprüfung kann nicht fortgesetzt werden
Vorabprüfung kann nicht fortgesetzt werden
Preflight kann nicht fortfahren. Die fehlgeschlagenen Prüfungen stehen an erster Stelle, jeweils mit der zugehörigen Lösung, und die Installation bleibt mit PREFLIGHT_FAILED blockiert, bis sie bestanden werden.
Ablehnung Ursache Lösung
INSTALLATION_NAME_MISSING keys.installationName ist leer Setzen Sie den Wert auf den eigenen Namen dieser Installation, passend zu ^[a-z][a-z0-9-]{0,62}$. Er ist dauerhaft, sobald der Schlüsselspeicher zum ersten Mal startet
INSTALLATION_NAME_EXAMPLE Der Name entspricht dem aus den Beispiel-Values-Dateien des Charts Legen Sie Ihren eigenen Namen fest
keys.installationName "…" does not match … Großbuchstaben, Unterstriche oder eine führende Ziffer Verwenden Sie Kleinbuchstaben, Ziffern und Bindestriche, beginnend mit einem Buchstaben
KEYS_CUSTODIAN_MISSING keys.custody.recipients ist leer Listen Sie die age-Empfänger Ihrer Treuhänder auf, also die öffentlichen Hälften
KEYS_CUSTODIAN_EXAMPLE Ein Empfänger ist der Beispiel-Treuhänder aus den Values-Dateien des Charts, dessen Identität niemand besitzt Ersetzen Sie ihn durch die Empfänger Ihrer eigenen Treuhänder
keys.custody.recipients: … Ein Empfänger in einer Form, für die der Custody-Job nicht verschlüsseln kann Verwenden Sie age1…, age1tag1…, age1tagpq1…, age1pq1… oder age1se1… in Kleinbuchstaben
NEXUS_EDITION_INVALID edition ist weder community noch enterprise Legen Sie einen der beiden Werte fest
edition=… but enterprise.enabled=… Die beiden Werte widersprechen sich Setzen Sie enterprise.enabled: true genau dann, wenn edition den Wert enterprise hat
global.imageRegistry is required Keine Registry angegeben Legen Sie die Registry fest, von der Ihre Knoten die Images abrufen
hosts.<name> is required Ein öffentlicher Host fehlt Setzen Sie hosts.console, hosts.api und hosts.auth
tls.existingSecret is required when tls.mode is existing Kein Zertifikats-Secret angegeben Geben Sie das Secret an oder wählen Sie einen anderen tls.mode
tls.clusterIssuer is required when tls.mode is cert-manager Kein Aussteller angegeben Geben Sie Ihren ClusterIssuer an
dataTier.<store>.external.host is required when mode is external Ein externer Speicher ohne Adresse Geben Sie seinen Host und sein Secret in existingSecret an
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read helm template hat keinen Cluster, in dem es sie nachschlagen kann Geben Sie die Adressen des API-Servers als /32-Bereiche an
EXTERNAL_KEY_ENCRYPTION_KEY_INVALID Der generierte Schlüssel in nexus-generated hat das falsche Format Siehe „Upgrade-Fehler“ oben

Eine Values-Datei, die einen Schlüssel verwendet, den das Chart nicht kennt, oder einen Wert des falschen Typs, wird vom Schema des Charts noch vor all diesen Prüfungen abgelehnt. telemetry.enabled: true ist ein Beispiel dafür: Das Schema akzeptiert nur false.

Einsenden eines Support-Bundles

Wenn nichts davon das Problem behebt, senden Sie Adverant zusammen mit Ihrer Supportanfrage ein Support-Bundle.

nexusctl support-bundle --out harrow-support-<request-number>.tar.gz

<request-number> ist die Nummer der Anfrage, die Sie auf der Seite „Support and support bundles“ Ihres Kontos eröffnet haben. Sie können dasselbe Bundle auch über die Seite „Support bundle“ der Konsole unter „This installation“ erstellen.

Das Bundle enthält Engine-Protokolle der letzten 24 Stunden, Status- und Versionsdetails, Einstellungen ohne deren Secrets sowie die Preflight- und Installationsberichte. Vor dem Schreiben ersetzt eine Schwärzungsfunktion (Redaction) Namen, Secrets und Adressen, und Sie erhalten eine Vorschau auf genau die Daten, die das System verlassen. Nachrichten, Dateien und Gedächtnisinhalte (Memory) von Personen werden niemals erfasst.

Laden Sie es direkt in der Anfrage in Ihrem Konto hoch oder speichern Sie es auf einem Datenträger und übertragen Sie es physisch, falls die Installation über keine Außenverbindung verfügt. Nur die in der Anfrage genannten Support-Ingenieure können es öffnen, und es wird nach 30 Tagen gelöscht. Geben Sie in der Anfrage an, welches der oben genannten Probleme Sie untersucht haben und was die Prüfungen in diesem Kapitel ergeben haben: Das erspart eine Rückfrage.