ΣύνδεσηΚλείστε μια ενημέρωση

Κεφάλαιο 2.17

Αντιμετώπιση προβλημάτων

Τα προβλήματα που συναντούν συχνότερα οι χειριστές, οργανωμένα με βάση αυτό που βλέπετε. Κάθε περίπτωση παρουσιάζει την αιτία, την εντολή που την επιβεβαιώνει και τη λύση, ενώ το κεφάλαιο κλείνει με την αποστολή ενός πακέτου υποστήριξης.

Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

22 λεπτά ανάγνωσης

Τα περισσότερα από όσα πηγαίνουν στραβά σε μια εγκατάσταση του Nexus συμβαίνουν με τους ίδιους δώδεκα περίπου τρόπους, και σχεδόν όλα δηλώνουν την παρουσία τους με έναν κωδικό. Αυτό το κεφάλαιο είναι οργανωμένο ανάλογα με το τι βλέπετε, περίπου με τη σειρά που θα συναντούσατε κάθε πρόβλημα: εγκατάσταση, διεκδίκηση, αδειοδότηση και, τέλος, λειτουργία. Για το καθένα σας δίνεται η αιτία, μια εντολή που την επιβεβαιώνει και η λύση.

Τα παραδείγματα χρησιμοποιούν την εγκατάσταση της Harrow Port Authority: namespace nexus, release nexus, hosts console.harrow.example, api.harrow.example και auth.harrow.example. Αντικαταστήστε τα με τα δικά σας. Τρεις συνήθειες εξοικονομούν χρόνο σε κάθε πρόβλημα που αναφέρεται εδώ:

  1. Διαβάστε τον κωδικό πριν από το μήνυμα. Κάθε άρνηση στο Nexus καταλήγει σε έναν κωδικό μηχανής, και αυτό το κεφάλαιο είναι ταξινομημένο με βάση αυτόν τον κωδικό.
  2. Εκτελέστε ξανά το nexusctl preflight μετά από κάθε αλλαγή στο cluster ή στο αρχείο values. Διαβάζει το cluster χωρίς να το αλλάζει και αναφέρει ονομαστικά τις περισσότερες αρνήσεις του chart πριν το κάνει το Helm.
  3. Χρησιμοποιήστε το --explain σε οποιοδήποτε ρήμα του nexusctl για το οποίο δεν είστε βέβαιοι. Εμφανίζει τις ενέργειες kubectl και helm χωρίς να τις εκτελέσει.

Η εγκατάσταση κολλάει

Εκτελέσατε την εγκατάσταση και δεν έχει ολοκληρωθεί. Το helm δεν έχει επιστρέψει μετά από δεκαπέντε λεπτά, ή επέστρεψε και τα pods βρίσκονται ακόμα σε κατάσταση Init ή Pending, ή η διεύθυνση της κονσόλας δεν αποκρίνεται.

Η πιο συχνή αιτία είναι το helm install --wait. Το Nexus δημιουργεί τη βάση δεδομένων του, τους ρόλους του και το schema κάθε υπηρεσίας σε post-install hooks, ενώ το bootstrap hook είναι αυτό που δίνει σε κάθε υπηρεσία τον κωδικό πρόσβασης της βάσης δεδομένων της. Με το --wait, το Helm περιμένει να ετοιμαστούν τα Deployments πριν εκτελέσει αυτά τα hooks, ενώ τα Deployments περιμένουν τα hooks. Κανένα από τα δύο δεν προχωρά. Μην κάνετε ποτέ εγκατάσταση με το --wait· κάντε εγκατάσταση χωρίς αυτό και περιμένετε στη συνέχεια.

Μια κάθετη ακολουθία πλαισίων που ενώνονται με βέλη προς τα κάτω: "Δημιουργία πόρων έκδοσης (τα Deployments ξεκινούν, το καθένα σε αναμονή από το wait-for-schema init container του)", μετά "Database bootstrap hook: βάση δεδομένων, ρόλοι, καθολικό εκδόσεων (release ledger)", μετά "Migration hooks, ένα ανά υπηρεσία, με καθορισμένη σειρά", μετά "Κάθε hook εγγράφει τη γραμμή του στο καθολικό εκδόσεων". Από το τελευταίο πλαίσιο, βέλη ανοίγουν προς τα πλάγια σε τρία μικρά πλαίσια: "Το nexus-auth ξεκινά", "Το nexus-gateway ξεκινά", "Άλλες υπηρεσίες ξεκινούν". Μια πλαϊνή σημείωση δίπλα στο επάνω πλαίσιο, με ένα διαγραμμένο βέλος προς το κάτω μέρος: "Το helm install --wait περιμένει εδώ για Deployments που περιμένουν τα hooks".
Τι εκτελείται, με τη σειρά, κατά την εγκατάσταση ή την αναβάθμιση του chart.

Οι άλλες αιτίες είναι συνηθισμένες αιτίες του Kubernetes. Δεν είναι δυνατή η λήψη (pull) των images επειδή το global.imageRegistry υποδεικνύει λάθος registry, ή επειδή μια εγκατάσταση Enterprise δεν έχει pull token. Ένα volume παραμένει σε κατάσταση Pending επειδή δεν υπάρχει το storage class. Λείπει το cert-manager, οπότε η εγκατάσταση δεν κολλάει καθόλου: αποτυγχάνει μέσα σε δευτερόλεπτα, επειδή οι εκδότες πιστοποιητικών του chart χρειάζονται τους πόρους του cert-manager.

Ξεκινήστε με τα pods και τα 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 εμφανίζει σφάλματα λήψης image και μη συνδεδεμένα (unbound) volumes στα συμβάντα (events) του. Ένα hook Job που εμφανίζει 0/1 ολοκληρώσεις με ένα αποτυχημένο pod έχει σταματήσει την εγκατάσταση, επειδή τα hook Jobs έχουν όριο επανάληψης (backoff limit) 0 και δεν επαναλαμβάνονται ποτέ σιωπηλά. Το αρχείο καταγραφής (log) του εξηγεί τον λόγο.

Δείτε πώς μπορείτε να διορθώσετε κάθε αιτία:

  • Αν το Helm περιμένει με το --wait, σταματήστε το, απεγκαταστήστε το και εγκαταστήστε το ξανά χωρίς την παράμετρο (flag). Στη συνέχεια, περιμένετε τις υπηρεσίες:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
  • Για σφάλματα λήψης (pull errors), ελέγξτε το global.imageRegistry και, για την έκδοση Enterprise, το pull token από τη σελίδα Pull tokens and install commands του λογαριασμού σας.
  • Για volumes σε κατάσταση Pending, ορίστε το storage.className σε ένα storage class που διαθέτει το cluster, ή ορίστε ένα ως προεπιλογή.
  • Αν λείπει το cert-manager, εγκαταστήστε το cert-manager v1.21.3 και εκτελέστε ξανά την εγκατάσταση.
  • Για ένα αποτυχημένο hook, διορθώστε αυτό που αναφέρει το αρχείο καταγραφής (log) του και εκτελέστε ξανά την εγκατάσταση.

Ένα pod αναμένει το σχήμα του (schema)

Το pod μιας υπηρεσίας παραμένει σε κατάσταση Init:0/1 για λεπτά. Κάθε υπηρεσία που χρησιμοποιεί τη βάση δεδομένων έχει ένα init container, το wait-for-schema, το οποίο συγκρατεί το pod μέχρι το καθολικό εκδόσεων (release ledger) να δείξει ότι οι μεταφορές (migrations) της έχουν εφαρμοστεί για το image αυτής της έκδοσης. Αυτό είναι φυσιολογικό για τα πρώτα λεπτά μιας εγκατάστασης ή αναβάθμισης, ενώ εκτελούνται τα migration hooks. Είναι πρόβλημα όταν δεν ολοκληρώνεται.

Διαβάστε το αρχείο καταγραφής (log) του init container:

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

Το αρχείο καταγραφής αναφέρει το στοιχείο (component), τις αλυσίδες μεταφοράς (migration chains) που περιμένει και το χρονικό του όριο, και στη συνέχεια εκτυπώνει μια γραμμή κάθε φορά που αλλάζει η κατάστασή του:

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
Η γραμμή προόδου λέει Τι σημαίνει
Ποιες αλυσίδες απομένουν να εφαρμοστούν για αυτήν την έκδοση Τα αναφερόμενα migration hooks δεν έχουν ολοκληρωθεί. Ελέγξτε αυτά τα Jobs.
Ότι δεν είναι δυνατή η ανάγνωση του καθολικού εκδόσεων (release ledger), μαζί με το σφάλμα της βάσης δεδομένων Το Postgres δεν αποκρίνεται, ή το καθολικό δεν υπάρχει επειδή δεν έχει εκτελεστεί το bootstrap της βάσης δεδομένων.
FAILED (<component>): after <n>s, … Εγκατέλειψε την προσπάθεια μετά από schemaWait.timeoutSeconds (1.800 από προεπιλογή). Το init container επανεκκινείται· η ίδια η υπηρεσία δεν ξεκίνησε ποτέ.

Μια αλυσίδα που δεν εφαρμόζεται ποτέ σημαίνει σχεδόν πάντα ότι το migration Job της απέτυχε. Βρείτε το με το kubectl -n nexus get jobs και διαβάστε το αρχείο καταγραφής του. Διορθώστε αυτό που αναφέρει (έναν γεμάτο δίσκο, μια εξωτερική βάση δεδομένων στην οποία δεν έχει πρόσβαση το εργαλείο μεταφοράς, μια σύγκρουση ρόλων) και εκτελέστε το helm upgrade με τις ίδιες τιμές: τα hooks εκτελούνται ξανά, και η εκ νέου εκτέλεση του καθενός είναι ασφαλής.

Αυξήστε το schemaWait.timeoutSeconds μόνο όταν μια μεταφορά (migration) είναι αργή αλλά υγιής, όπως μπορεί να συμβεί με μια μεγάλη πρώτη μεταφορά σε αργό αποθηκευτικό χώρο. Η αύξησή του για να κρύψετε ένα αποτυχημένο Job απλώς κάνει το pod να περιμένει περισσότερο για κάτι που δεν θα έρθει ποτέ.

Ο χώρος αποθήκευσης κλειδιών είναι σφραγισμένος

Μετά από διακοπή ρεύματος, επανεκκίνηση κόμβου (node) ή επανεκκίνηση του container runtime, τα pods επανέρχονται και η κονσόλα φορτώνει, αλλά οτιδήποτε χρειάζεται κλειδί αποτυγχάνει ή περιμένει. Ο μηχανισμός αποσφράγισης (unsealer) ξεκινά σφραγισμένος μετά από κάθε επανεκκίνηση του κόμβου του, και ο χώρος αποθήκευσης κλειδιών (key store) δεν μπορεί να αποσφραγιστεί μόνος του μέχρι να ανοίξει ο μηχανισμός αποσφράγισης.

Ρωτήστε το OpenBao σε κάθε pod:

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 $?"

Ο κωδικός εξόδου 0 σημαίνει αποσφραγισμένο, το 2 σημαίνει σφραγισμένο και το 1 σημαίνει ότι δεν μπόρεσε να απαντήσει (ρωτήστε ξανά σε ένα λεπτό). Εκτελέστε το ίδιο στο openbao-0 με -tls-server-name=openbao για τον χώρο αποθήκευσης κλειδιών. Αν ο μηχανισμός αποσφράγισης είναι αποσφραγισμένος και ο χώρος αποθήκευσης κλειδιών δεν είναι, ο χώρος αποθήκευσης κλειδιών αποσφραγίζεται μόνος του· δώστε του ένα λεπτό.

Για να διορθωθεί ένας σφραγισμένος μηχανισμός αποσφράγισης, ένας θεματοφύλακας (custodian) εκτελεί το unseal.sh του chart με τη δική του ταυτότητα age. Το Κεφάλαιο 2.15, Δεύτερη μέρα: λειτουργία του Nexus, περιέχει την πλήρη εντολή. Η έξοδος του script σάς λέει τι συνέβη:

Έξοδος Σημασία Τι πρέπει να κάνετε
0 Αποσφραγίστηκε Ελέγξτε το kubectl -n nexus get deploy,statefulset μέσα σε ένα λεπτό.
1 Ακόμα σφραγισμένο, ή απέτυχε μια κλήση αποσφράγισης Διαβάστε τις γραμμές μεριδίων (shares) που εμφάνισε· εκτελέστε το ξανά.
2 Λείπει ένα προαπαιτούμενο Το μήνυμα το κατονομάζει: AGE_IDENTITY, ένα εκτελέσιμο αρχείο (binary) όπως το age ή το jq, ή μια ρύθμιση άμεσης λειτουργίας (direct-mode).
3 Αυτή η ταυτότητα δεν μπορεί να αποκρυπτογραφήσει τα μερίδια (shares) Δεν είστε θεματοφύλακας (custodian) αυτής της εγκατάστασης. Δεν υποβλήθηκε τίποτα. Βρείτε έναν θεματοφύλακα της εγκατάστασης.

Δεν μπορείτε να συνδεθείτε μέσω HTTP

Η κονσόλα φορτώνει σε μια διεύθυνση http://, ή μέσω ενός kubectl port-forward στο 127.0.0.1, και η σύνδεση αποτυγχάνει. Η προτροπή για passkey δεν εμφανίζεται ποτέ, ή η σύνδεση επιστρέφει ξανά στην αρχή.

Η σύνδεση απαιτεί το ίδιο το HTTPS origin της κονσόλας. Η κονσόλα δέχεται σύνδεση μόνο από το https://<hosts.console>, διατηρεί τη συνεδρία σε ένα cookie __Host- με την ένδειξη Secure (το οποίο το πρόγραμμα περιήγησης αποθηκεύει μόνο μέσω HTTPS), και το passkey του πρώτου διαχειριστή χρειάζεται μια σελίδα με έγκυρο πιστοποιητικό. Τα προγράμματα περιήγησης απορρίπτουν τα passkeys όταν υπάρχει σφάλμα πιστοποιητικού. Ένα port-forward στο http://127.0.0.1 δεν μπορεί ποτέ να πραγματοποιήσει σύνδεση.

Ελέγξτε πού συνδέθηκε πραγματικά το πρόγραμμα περιήγησης:

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

Το πρώτο θα πρέπει να απαντήσει μέσω HTTPS με ένα πιστοποιητικό που εμπιστεύεται το μηχάνημά σας. Το δεύτερο θα πρέπει να εμφανίσει τα τρία hosts με τα ονόματα που ορίσατε στο hosts.*.

Για να το διορθώσετε, συνδεθείτε στην κονσόλα στη διεύθυνση https://console.harrow.example, το ακριβές όνομα στο hosts.console, με ένα πιστοποιητικό που εμπιστεύεται το πρόγραμμα περιήγησης. Με το tls.mode: existing, ελέγξτε ότι το tls.existingSecret περιέχει πιστοποιητικό και για τα τρία hosts. Με το tls.mode: cert-manager, ελέγξτε ότι το εξέδωσε ο ClusterIssuer. Με το tls.mode: none, το Transport Layer Security (TLS) τερματίζει στον δικό σας load balancer, και εκεί είναι που πρέπει να είναι σωστό το πιστοποιητικό. Για μια ιδιωτική αρχή έκδοσης πιστοποιητικών (CA), εγκαταστήστε το πιστοποιητικό της στα μηχανήματα από τα οποία συνδέονται οι διαχειριστές σας.

Ο κωδικός διεκδίκησης έληξε

Στη σελίδα Claim this installation, η σελίδα απορρίπτει τον κωδικό με CLAIM_CODE_EXPIRED (410). Ένας κωδικός διεκδίκησης αποτελείται από τρεις ομάδες των τεσσάρων χαρακτήρων. Λειτουργεί μία φορά, για 30 λεπτά, με 5 προσπάθειες. Μετά από αυτό, ή μετά την πέμπτη λανθασμένη προσπάθεια, ακυρώνεται, και τίποτα δεν διεκδικήθηκε ούτε άλλαξε.

Δημιουργήστε έναν νέο κωδικό από το τερματικό που έχει πρόσβαση στο cluster:

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

Εκτυπώνει έναν νέο κωδικό και το αποτύπωμα (fingerprint) της εγκατάστασης. Εισαγάγετε τον κωδικό στη σελίδα διεκδίκησης εντός 30 λεπτών και συγκρίνετε ξανά το αποτύπωμα.

Διεκδίκηση αυτής της εγκατάστασης
Διεκδίκηση αυτής της εγκατάστασης
Διεκδίκηση αυτής της εγκατάστασης. Ο κωδικός από το τερματικό εισάγεται σε τρεις ομάδες, και η σελίδα εμφανίζει το πλήρες αποτύπωμα σε ομάδες των τεσσάρων για σύγκριση· ένας ληγμένος κωδικός απορρίπτεται με CLAIM_CODE_EXPIRED και δεν διεκδικείται τίποτα.

Δύο σχετικές απαντήσεις:

  • Το RATE_LIMITED (429) στη σελίδα διεκδίκησης σημαίνει ότι η σελίδα έχει δεχτεί αρκετές προσπάθειες το τελευταίο λεπτό. Περιμένετε τον αριθμό δευτερολέπτων που υποδεικνύει. Αν δεν κάνατε εσείς αυτές τις προσπάθειες, κάποιος άλλος στο δίκτυό σας δοκιμάζει τη σελίδα· μάθετε ποιος είναι πριν προχωρήσετε στη διεκδίκηση.
  • Το TRANSITION_NOT_PERMITTED (409) σημαίνει ότι η εγκατάσταση έχει ήδη διεκδικηθεί και η σελίδα διεκδίκησής της έχει απενεργοποιηθεί οριστικά. Αντ' αυτού, συνδεθείτε. Αν δεν τη διεκδικήσατε εσείς, αντιμετωπίστε το ως περιστατικό ασφαλείας.

Το αποτύπωμα (fingerprint) δεν ταιριάζει

Η σελίδα διεκδίκησης εμφανίζει CLAIM_FINGERPRINT_MISMATCH (403), ή μπορείτε να δείτε και μόνοι σας ότι οι οκτώ ομάδες των τεσσάρων στη σελίδα διαφέρουν από αυτές που εκτύπωσε το τερματικό σας. Ακόμα και μία ομάδα να διαφέρει, σημαίνει ότι το πρόγραμμα περιήγησης επικοινωνεί με διαφορετική εγκατάσταση.

Σταματήστε. Μην πληκτρολογήσετε τον κωδικό σε αυτήν τη σελίδα. Κάτι άλλο πέρα από την εγκατάστασή σας ενδέχεται να απαντά σε αυτήν τη διεύθυνση, πιθανώς ένα μηχάνημα που έχει στηθεί για να παγιδεύσει τον πρώτο διαχειριστή. Αν την είχατε διεκδικήσει, εκείνο το μηχάνημα θα είχε στην κατοχή του τον οργανισμό σας. Η δική σας εγκατάσταση παραμένει αμετάβλητη και ακόμη αδιεκδίκητη.

Ελέγξτε πού οδηγεί το όνομα και ποιο πιστοποιητικό απάντησε:

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

Η διεύθυνση θα πρέπει να είναι αυτή του ingress controller σας, και το πιστοποιητικό θα πρέπει να είναι αυτό που εγκαταστήσατε για το hosts.console.

Το αποτύπωμα δεν ταιριάζει
Το αποτύπωμα δεν ταιριάζει
Τα αποτυπώματα διαφέρουν σε τρεις από τις οκτώ ομάδες. Η σελίδα σάς προτρέπει να σταματήσετε, εξηγεί ποιος μπορεί να απαντά και παραθέτει τι πρέπει να ελέγξετε πριν προσπαθήσετε ξανά.

Για να το διορθώσετε, δώστε στην ομάδα ασφαλείας σας τη διεύθυνση που απάντησε και κρατήστε το αρχείο καταγραφής της εγκατάστασης, το οποίο καταγράφει το αποτύπωμα που εκτύπωσε η εγκατάσταση. Διορθώστε την εγγραφή Domain Name System (DNS) ή τον proxy που σας έστειλε αλλού. Στη συνέχεια, δημιουργήστε έναν νέο κωδικό διεκδίκησης με το nexusctl claim-code --administrator <email> και κάντε τη διεκδίκηση από ένα πρόγραμμα περιήγησης σε ένα δίκτυο που εμπιστεύεστε, συγκρίνοντας ξανά όλες τις οκτώ ομάδες.

Η άδεια χρήσης απορρίπτεται

Η εισαγωγή στη σελίδα Import the licence, Import a new licence ή στο nexusctl licence import απαντά με άρνηση. Μια απορριφθείσα εισαγωγή δεν αλλάζει τίποτα: η ισχύουσα άδεια παραμένει σε ισχύ και το κατώτατο όριο του ρολογιού (clock floor) δεν μετακινείται.

Διαβάστε τον κωδικό και το βήμα:

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

Το σώμα της άρνησης περιέχει τα code, message, refused_at (το βήμα που απέτυχε) και troubleshooting. Για να δείτε την κατάσταση της ισχύουσας άδειας, διαβάστε το GET https://auth.harrow.example/api/v1/installation/licence/state με το ίδιο token.

Κωδικός HTTP Συνήθης αιτία Λύση
LICENCE_SIGNATURE_INVALID 422 Το αρχείο υπέστη επεξεργασία, επαναμορφοποίηση ή εκ νέου αποθήκευση, ή λείπει μία υπογραφή Κατεβάστε το ξανά από τον λογαριασμό σας και εισαγάγετέ το ανέπαφο
LICENCE_FORMAT_INVALID 422 Δεν είναι άδεια: λάθος αρχείο, περικομμένο ή ενσωματωμένο μέσα σε άλλο αντικείμενο Στείλτε το αρχείο ακριβώς όπως το έδωσε η Adverant
LICENCE_ROOT_UNKNOWN 422 Υπογεγραμμένη με κλειδί που δεν περιλαμβάνεται σε αυτήν την έκδοση Αναβαθμίστε, ή ζητήστε μια άδεια υπογεγραμμένη για την έκδοσή σας
LICENCE_MATRIX_MISMATCH 422 Συνταγμένη για νεότερο πίνακα εκδόσεων (edition matrix), ή εκχωρεί μια ομάδα που δεν γνωρίζει αυτό το build Αναβαθμίστε, ή ζητήστε μια άδεια συνταγμένη για την έκδοσή σας
LICENCE_OTHER_INSTALLATION 409 Εκδόθηκε για άλλη εγκατάσταση, συχνά η άδεια του δοκιμαστικού cluster στο περιβάλλον παραγωγής Ζητήστε μια άδεια για την ταυτότητα αυτής της εγκατάστασης
LICENCE_REVOKED 403 Η Adverant την απέσυρε Ζητήστε από την Adverant νέα άδεια
LICENCE_LOCKED 403 Το starts_on της είναι μεταγενέστερο της τρέχουσας ημερομηνίας Εισαγάγετέ την κατά την πρώτη ημέρα ισχύος της ή μετά από αυτήν
TRANSITION_NOT_PERMITTED 409 Αυτό το αναγνωριστικό άδειας έχει ήδη εισαχθεί Δεν απαιτείται ενέργεια αν είναι σε ισχύ· απευθυνθείτε στην Adverant αν πρέπει να αλλάξουν οι όροι
RECORD_NOT_FOUND 404 Η εγκατάσταση δεν έχει δηλωθεί, επομένως δεν έχει ακόμη ταυτότητα Ολοκληρώστε το βήμα του πρώτου διαχειριστή και, στη συνέχεια, κάντε εισαγωγή
TENANT_NOT_A_PARAMETER 403 Το σώμα ορίζει έναν οργανισμό στο ανώτατο επίπεδό του Στείλτε μόνο το αρχείο της άδειας ως σώμα

Δύο πράγματα μοιάζουν με προβλήματα άδειας αλλά δεν είναι. Μια ανάγνωση κατάστασης που φέρει το LICENCE_CLOCK_BEHIND_FLOOR σημαίνει ότι το ρολόι του κόμβου δείχνει ώρα προγενέστερη από την πιο πρόσφατη ώρα που έχει καταγράψει η εγκατάσταση· διορθώστε την ώρα του κόμβου και, αν το ρολόι είχε τρέξει μπροστά παρασύροντας μαζί του το κατώτατο όριο (floor), ζητήστε από την Adverant ένα token επαναφοράς ώρας (time-reset token). Επίσης, μια άδεια που εισάγεται αλλά εξακολουθεί να εμφανίζει μια ομάδα ως προεπισκόπηση (teaser) συνήθως δεν εκχωρεί αυτήν την ομάδα: διαβάστε πρώτα απ' όλα τις εκχωρήσεις (grants) στη σελίδα της άδειας.

Καμία απάντηση από το AI

Ο βοηθός τεχνητής νοημοσύνης (AI) εμφανίζει MODEL_NOT_CONNECTED (503), ένα βήμα ροής εργασίας αποτυγχάνει με NO_PROVIDER_FOR_ROLE (422), ή οι απαντήσεις απλώς σταματούν.

Η δεξαμενή (pool) του οργανισμού δεν διαθέτει κλειδί που να μπορεί να απαντήσει, ή ο δρομολογητής (router) δεν μπορεί να επικοινωνήσει με τον πάροχο. Κάθε οργανισμός φέρνει το δικό του κλειδί μοντέλου. Χωρίς ενεργό κλειδί δεν υπάρχει AI, εκ σχεδιασμού, και κανένα κοινόχρηστο κλειδί δεν καλύπτει το κενό.

Ελέγξτε τη δεξαμενή (pool) και την επιλογή του δρομολογητή, χρησιμοποιώντας και στις δύο περιπτώσεις το προσωπικό access token του χρήστη:

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

Το πρώτο παραθέτει κάθε πάροχο, το αν μπορεί να απαντήσει και γιατί όχι ("No key in use: 1 withdrawn, 1 lapsed"), καθώς και την κατάσταση κάθε κλειδιού. Το δεύτερο απαντά με το μοντέλο που θα χρησιμοποιούσε ο δρομολογητής για τον οργανισμό, ή την άρνησή του ολογράφως. Στη συνέχεια, ελέγξτε τη διαδρομή εξόδου από το cluster με αυτές τις δύο εντολές:

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

Τι σημαίνει κάθε εύρημα:

Εύρημα Λύση
Κανένα κλειδί στη δεξαμενή (pool) Ένας ιδιοκτήτης ή διαχειριστής προσθέτει ένα κλειδί οργανισμού στον πίνακα ελέγχου AI (AI switchboard) ή στις Ρυθμίσεις, Μοντέλα AI (Settings, AI models)
Κλειδιά invalid, expired ή exhausted Προσθέστε ένα νέο κλειδί· το παλιό παραμένει στη λίστα ως ιστορικό
Κλειδιά resting Περιμένετε: ένα κλειδί που αποτυγχάνει παραμένει ανενεργό για 60 δευτερόλεπτα, και μετά από 5 συνεχόμενες αποτυχίες απενεργοποιείται (PROVIDER_KEY_SWITCHED_OFF)
NO_PROVIDER_FOR_ROLE με κλειδιά σε χρήση Ο ρόλος δεν έχει ανάθεση και τίποτα δεν ταιριάζει· ορίστε τον ρόλο στην πολιτική δρομολόγησης
MODEL_CAPABILITY_UNAVAILABLE (422) Το αίτημα απαιτεί μια δυνατότητα, ή μια έδρα δεδομένων (residency), που δεν προσφέρει κανένας πάροχος στη δεξαμενή· ενεργοποιήστε έναν που την προσφέρει
Δεν υπάρχει πολιτική nexus-operator-egress, ή λείπουν από αυτήν τα εύρη (ranges) του παρόχου Προσθέστε τα εύρη, γραμμένα σε σημειογραφία Classless Inter-Domain Routing (CIDR), στο networkPolicy.externalEgressCIDRs και κάντε αναβάθμιση
Ένας τοπικός διακομιστής μοντέλου που δεν αποκρίνεται Ελέγξτε το ai.localProvider.baseUrl, καταχωρίστε τον διακομιστή στο ai.installationHosts και επιτρέψτε το εύρος του στο networkPolicy.externalEgressCIDRs

Ένα κλειδί φιλοξενούμενου παρόχου που λειτουργεί από φορητό υπολογιστή και αποτυγχάνει στην εγκατάσταση οφείλεται σχεδόν πάντα στην πολιτική δικτύου. Το namespace απαγορεύει την εξερχόμενη κίνηση (egress) από προεπιλογή.

Απαντήσεις 429

Ένας client λαμβάνει την απάντηση 429 Too Many Requests. Το Nexus έχει τέσσερα σημεία που μπορούν να το επιστρέψουν αυτό, και το σώμα της απάντησης σας λέει ποιο είναι.

Πού Κωδικός και λεπτομέρειες Τι να αλλάξετε
nexus-auth, ανά συνδεδεμένο άτομο RATE_LIMITED με limit, windowSeconds και retryAfterSeconds auth.rateLimitPerMinute (προεπιλογή 5000), για εκτεταμένη αυτοματοποίηση
Όριο κλειδιού script, εφαρμογής ή μονάδας (Enterprise) RATE_LIMITED που αναφέρει το κλειδί και το όριό του Το όριο στις Ρυθμίσεις, Όρια ρυθμού (Settings, Rate limits), με αιτιολογία
Η σελίδα διεκδίκησης πρώτης εκτέλεσης RATE_LIMITED με retry_after_seconds Τίποτα: περιμένετε και μάθετε ποιος άλλος δοκιμάζει τη σελίδα
Ένας πάροχος μοντέλου Ο δρομολογητής το αντιμετωπίζει ως παροδική αποτυχία και προχωρά στον επόμενο πάροχο Προσθέστε άλλο κλειδί ή πάροχο αν συμβαίνει συχνά

Κάθε μία φέρει μια κεφαλίδα Retry-After. Ένας σωστά ρυθμισμένος client περιμένει για αυτό το διάστημα και δεν προσπαθεί ξανά νωρίτερα.

Αν φαίνεται ότι όλοι οι χρήστες ταυτόχρονα μοιράζονται ένα όριο, ελέγξτε το proxy.trustedCIDRs. Όταν δεν καλύπτει το δίκτυο των pods του ingress controller σας, το nexus-auth δεν μπορεί να εμπιστευτεί την κεφαλίδα X-Forwarded-For και βλέπει κάθε αίτημα σαν να προέρχεται από τον controller. Η προεπιλογή, 10.42.0.0/16, ταιριάζει μόνο στο k3s.

kubectl get pods -A -o wide

Βρείτε τη διεύθυνση του pod του ingress controller στην έξοδο και βεβαιωθείτε ότι το proxy.trustedCIDRs την καλύπτει.

Σφάλματα αναβάθμισης

Η αναβάθμιση αναιρέθηκε (rolled back). Η σελίδα Upgrade εμφανίζει UPGRADE_ROLLED_BACK: ένα βήμα απέτυχε, κάθε μηχανή (engine) επέστρεψε στην προηγούμενη έκδοση και τα δεδομένα δεν άλλαξαν. Η σελίδα κατονομάζει το βήμα. Ένα συνηθισμένο πρόβλημα είναι ένα volume που είναι πολύ μικρό για τη νέα διάταξη ενός χώρου αποθήκευσης. Διορθώστε αυτό που αναφέρει, εκτελέστε ξανά το nexusctl upgrade plan --bundle <file> και, στη συνέχεια, εφαρμόστε την. Το αντίγραφο ασφαλείας λαμβάνεται ξανά πρώτο.

Το chart αρνείται να κάνει render με EXTERNAL_KEY_ENCRYPTION_KEY_INVALID. Το Secret nexus-generated διατηρεί το EXTERNAL_KEY_ENCRYPTION_KEY σε μορφή που δεν μπορεί να χρησιμοποιήσει το chart. Πρέπει να είναι σε base64 των 32 bytes, ή το ακατέργαστο κλειδί 32-byte μιας παλαιότερης εγκατάστασης. Κάποιος επεξεργάστηκε ή αντικατέστησε το Secret. Επαναφέρετε το κλειδί με το οποίο έχουν σφραγιστεί τα δεδομένα αυτής της εγκατάστασης, ως base64 των 32 bytes του (printf %s "$OLD" | base64), και αναβαθμίστε ξανά. Μην αφήσετε το chart να δημιουργήσει νέο: τα δεδομένα που σφραγίστηκαν με το παλιό κλειδί θα παρέμεναν μη αναγνώσιμα.

Τα scripts απορρίπτονται με TOKEN_ORG_MISSING μετά την αναβάθμιση. Κάθε υπηρεσία που ελέγχει κλειδιά application programming interface (API) μέσω του nexus-auth απορρίπτει πλέον ένα κλειδί χωρίς οργανισμό, με 403 TOKEN_ORG_MISSING. Αναθέστε σε κάθε τέτοιο κλειδί έναν οργανισμό, ή εκδώστε ένα νέο κλειδί.

Τα κλειδιά αναφέρουν λάθος εφαρμογή για μία ώρα. Εκκαθαρίστε τις προσωρινά αποθηκευμένες καταχωρίσεις κλειδιών στην cache του nexus-auth, τον χώρο αποθήκευσης Valkey της εγκατάστασης. Το Κεφάλαιο 2.15, Δεύτερη μέρα: λειτουργία του Nexus, περιέχει την εντολή, τόσο για τον χώρο αποθήκευσης εντός του cluster όσο και για έναν εξωτερικό.

Ένα migration hook απέτυχε. Το helm upgrade αναφέρει ένα αποτυχημένο pre-upgrade hook. Το schema μεταφέρεται πριν ξεκινήσουν τα νέα pods, επομένως η τρέχουσα έκδοση εξακολουθεί να εξυπηρετεί. Διαβάστε το αρχείο καταγραφής του Job με το kubectl -n nexus logs job/<job-name>, διορθώστε αυτό που αναφέρει και εκτελέστε ξανά την αναβάθμιση.

Οι υπηρεσίες δεν μπορούσαν να χρησιμοποιήσουν τους πίνακές τους για λίγα δευτερόλεπτα. Κατά την πρώτη αναβάθμιση μιας εγκατάστασης που έγινε από παλαιότερο chart, κάθε υπηρεσία χάνει τα παλιά προεπιλεγμένα δικαιώματα πινάκων της και ανακτά τα δικά της από το δικό της migration. Το κενό διαρκεί δευτερόλεπτα. Κάντε την αναβάθμιση σε περίοδο χαμηλής κίνησης, ή μειώστε πρώτα την κλίμακα (scale) των υπηρεσιών στο μηδέν.

Η έκδοση στον δίσκο απορρίφθηκε. Η εισαγωγή από μέσο αποθήκευσης εμφανίζει MEDIA_SIGNATURE_INVALID (422): τα αρχεία δεν είναι υπογεγραμμένα από το κλειδί έκδοσης που είναι εγκατεστημένο σε αυτήν την εγκατάσταση. Δεν φορτώθηκε τίποτα και η τρέχουσα έκδοση συνεχίζει να εκτελείται. Κρατήστε το μέσο αποθήκευσης για την ομάδα ασφαλείας σας και ζητήστε από την Adverant νέο μέσο μέσω της ανταλλαγής εκτός σύνδεσης (offline exchange).

Άρνηση απόδοσης του chart

Το helm install, το helm upgrade ή το helm template σταματά πριν εφαρμοστεί οτιδήποτε, με ένα μήνυμα που ξεκινά με έναν κωδικό ή κατονομάζει μια τιμή. Το chart απορρίπτει τιμές που δεν μπορεί να εκτελέσει με ασφάλεια. Δεν άλλαξε τίποτα στο cluster.

Κάντε render το chart μόνο του για να δείτε κάθε άρνηση χωρίς να πειράξετε το cluster. Χρησιμοποιήστε το Enterprise chart που κατεβάσατε αντί για τη διεύθυνση oci:// στην έκδοση Enterprise, και ορίστε το networkPolicy.apiServerCIDRs στα values, επειδή ένα offline render δεν μπορεί να το διαβάσει από το cluster:

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) ελέγχει τις ίδιες τιμές ταυτότητας στην ενότητα "time and keys" και αναφέρει τους ίδιους κωδικούς. Η έξοδός του είναι 0 όταν η εγκατάσταση μπορεί να προχωρήσει (οι προειδοποιήσεις δεν την εμποδίζουν), 1 όταν απέτυχε τουλάχιστον ένας έλεγχος και 2 όταν δεν μπόρεσε να εκτελεστεί.

Το preflight δεν μπορεί να συνεχίσει
Το preflight δεν μπορεί να συνεχίσει
Ο προέλεγχος δεν μπορεί να συνεχίσει. Οι έλεγχοι που απέτυχαν εμφανίζονται πρώτοι, ο καθένας με τη λύση του, και η εγκατάσταση παραμένει αποκλεισμένη με PREFLIGHT_FAILED μέχρι να περάσουν επιτυχώς.
Απόρριψη Αιτία Λύση
INSTALLATION_NAME_MISSING Το keys.installationName είναι κενό Ορίστε το στο όνομα αυτής της εγκατάστασης, ώστε να ταιριάζει με το ^[a-z][a-z0-9-]{0,62}$. Γίνεται μόνιμο μόλις ξεκινήσει για πρώτη φορά ο χώρος αποθήκευσης κλειδιών
INSTALLATION_NAME_EXAMPLE Το όνομα είναι αυτό που υπάρχει στα ενδεικτικά αρχεία values του chart Ορίστε το δικό σας όνομα
keys.installationName "…" does not match … Κεφαλαία, κάτω παύλες ή ψηφίο στην αρχή Χρησιμοποιήστε πεζά γράμματα, ψηφία και παύλες, ξεκινώντας με γράμμα
KEYS_CUSTODIAN_MISSING Το keys.custody.recipients είναι κενό Καταχωρίστε τους παραλήπτες age των θεματοφυλάκων σας, δηλαδή τα δημόσια μέρη των κλειδιών
KEYS_CUSTODIAN_EXAMPLE Ένας παραλήπτης είναι ο ενδεικτικός θεματοφύλακας από τα αρχεία values του chart, του οποίου την ταυτότητα δεν κατέχει κανείς Αντικαταστήστε τον με τους παραλήπτες των δικών σας θεματοφυλάκων
keys.custody.recipients: … Ένας παραλήπτης σε μορφή για την οποία το custody Job δεν μπορεί να κάνει κρυπτογράφηση Χρησιμοποιήστε age1…, age1tag1…, age1tagpq1…, age1pq1… ή age1se1…, με πεζούς χαρακτήρες
NEXUS_EDITION_INVALID Το edition δεν είναι ούτε community ούτε enterprise Ορίστε ένα από τα δύο
edition=… but enterprise.enabled=… Τα δύο διαφωνούν Ορίστε το enterprise.enabled: true ακριβώς όταν το edition είναι enterprise
global.imageRegistry is required Δεν έχει οριστεί registry Ορίστε το registry από το οποίο οι κόμβοι σας κάνουν pull τα images
hosts.<name> is required Λείπει ένα δημόσιο host Ορίστε τα hosts.console, hosts.api και hosts.auth
tls.existingSecret is required when tls.mode is existing Δεν έχει οριστεί Secret πιστοποιητικού Ονομάστε το Secret, ή επιλέξτε άλλο tls.mode
tls.clusterIssuer is required when tls.mode is cert-manager Δεν έχει οριστεί εκδότης (issuer) Ονομάστε τον ClusterIssuer σας
dataTier.<store>.external.host is required when mode is external Ένας εξωτερικός χώρος αποθήκευσης χωρίς διεύθυνση Δώστε το host του, καθώς και το Secret του στο existingSecret
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read Το helm template δεν έχει cluster για να τα αναζητήσει Δώστε τις διευθύνσεις του API server ως εύρη /32
EXTERNAL_KEY_ENCRYPTION_KEY_INVALID Το παραγόμενο κλειδί στο nexus-generated έχει λάθος μορφή Δείτε την ενότητα "Σφάλματα αναβάθμισης" παραπάνω

Ένα αρχείο values που χρησιμοποιεί ένα κλειδί το οποίο δεν διαθέτει το chart, ή μια τιμή λανθασμένου τύπου, απορρίπτεται από το schema του chart πριν από οποιοδήποτε από αυτά. Το telemetry.enabled: true είναι ένα παράδειγμα: το schema δέχεται μόνο το false.

Αποστολή πακέτου υποστήριξης

Όταν τίποτα από αυτά δεν επιλύει το πρόβλημα, στείλτε στην Adverant ένα πακέτο υποστήριξης (support bundle) μαζί με το αίτημα υποστήριξής σας.

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

Το <request-number> είναι ο αριθμός του αιτήματος που ανοίξατε στη σελίδα Support and support bundles του λογαριασμού σας. Μπορείτε να δημιουργήσετε το ίδιο πακέτο από τη σελίδα Support bundle της κονσόλας, στην ενότητα This installation.

Το πακέτο περιλαμβάνει αρχεία καταγραφής των μηχανών (engine logs) από τις τελευταίες 24 ώρες, λεπτομέρειες υγείας και έκδοσης, ρυθμίσεις χωρίς τα μυστικά τους, καθώς και τις αναφορές προελέγχου (preflight) και εγκατάστασης. Πριν εγγραφεί, η διαδικασία απόκρυψης (redaction) αντικαθιστά ονόματα, μυστικά και διευθύνσεις, και μπορείτε να διαβάσετε μια προεπισκόπηση με το τι ακριβώς αποστέλλεται. Τα μηνύματα, τα αρχεία και η μνήμη των χρηστών δεν συλλέγονται ποτέ.

Μεταφορτώστε το στο αίτημα στον λογαριασμό σας ή, εάν η εγκατάσταση δεν διαθέτει εξωτερική σύνδεση, αποθηκεύστε το σε μέσο αποθήκευσης και μεταφέρετέ το εκτός αυτής. Μόνο οι μηχανικοί υποστήριξης που αναφέρονται στο αίτημα μπορούν να το ανοίξουν, και διαγράφεται μετά από 30 ημέρες. Αναφέρετε στο αίτημα ποιο από τα παραπάνω προβλήματα εξετάζατε και τι έδειξαν οι έλεγχοι αυτού του κεφαλαίου: έτσι εξοικονομείται ένας κύκλος επικοινωνίας.