Prihlásiť saRezervovať brífing

Kapitola 2.17

Riešenie problémov

Problémy, s ktorými sa operátori stretávajú najčastejšie, zoradené podľa toho, čo vidíte. Pri každom je uvedená príčina, príkaz na jej potvrdenie a oprava; kapitola sa končí odoslaním balíka pre podporu.

Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

22 min čítania

Väčšina zlyhaní pri inštalácii systému Nexus prebieha tuctom rovnakých spôsobov a takmer všetky sa ohlásia kódom. Táto kapitola je usporiadaná podľa toho, čo vidíte, približne v poradí, v akom sa s jednotlivými problémami stretnete: inštalácia, priradenie vlastníctva, licencovanie a potom prevádzka. Pri každom probléme nájdete príčinu, príkaz na jej potvrdenie a riešenie.

Príklady používajú inštaláciu organizácie Harrow Port Authority: menný priestor nexus, vydanie nexus, hostitelia console.harrow.example, api.harrow.example a auth.harrow.example. Nahraďte ich svojimi vlastnými hodnotami. Pri každom z týchto problémov ušetria čas tri návyky:

  1. Prečítajte si kód skôr než samotnú správu. Každé zamietnutie v systéme Nexus sa končí strojovým kódom a práve podľa tohto kódu je táto kapitola zoradená.
  2. Po každej zmene v klastri alebo v súbore hodnôt znova spustite nexusctl preflight. Prečíta stav klastra bez toho, aby ho menil, a nahlási väčšinu zamietnutí chartu podľa názvu skôr, ako to urobí Helm.
  3. Pri akomkoľvek príkaze nástroja nexusctl, ktorým si nie ste istí, použite --explain. Vypíše operácie kubectl a helm bez toho, aby ich spustil.

Inštalácia zamrzne

Spustili ste inštaláciu a ešte sa nedokončila. Príkaz helm sa nevrátil ani po pätnástich minútach, alebo sa vrátil a pody sú stále v stave Init či Pending, prípadne adresa konzoly neodpovedá.

Najčastejšou príčinou je helm install --wait. Nexus vytvára svoju databázu, svoje roly a schému každej služby v post-inštalačných hookoch a práve zavádzací (bootstrap) hook odovzdáva každej službe jej databázové heslo. S parametrom --wait Helm čaká, kým budú objekty Deployment pripravené, pred tým, než tieto hooky spustí, zatiaľ čo objekty Deployment čakajú na hooky. Ani jedno sa nepohne. Nikdy neinštalujte s parametrom --wait; inštalujte bez neho a počkajte až potom.

Zvislý sled rámčekov spojených šípkami smerujúcimi nadol: „Vytvorené prostriedky vydania (spúšťajú sa objekty Deployment, každý držaný svojím inicializačným kontajnerom wait-for-schema)“, potom „Zavádzací hook databázy: databáza, roly, účtovná kniha vydaní“, potom „Migračné hooky, jeden pre každú službu, v pevnom poradí“, potom „Každý hook zapíše svoj riadok do účtovnej knihy vydaní“. Z posledného rámčeka sa šípky rozbiehajú do strán k trom malým rámčekom „spúšťa sa nexus-auth“, „spúšťa sa nexus-gateway“, „spúšťajú sa ostatné služby“. Bočná poznámka vedľa horného rámčeka s prečiarknutou šípkou smerujúcou nadol: „helm install --wait tu čaká na objekty Deployment, ktoré čakajú na hooky“.
Čo sa postupne spúšťa pri inštalácii alebo aktualizácii chartu.

Ostatné príčiny sú bežné záležitosti systému Kubernetes. Obrazy nie je možné stiahnuť, pretože global.imageRegistry uvádza nesprávny register, alebo v inštalácii edície Enterprise chýba sťahovací token (pull token). Zväzok zostáva v stave Pending, pretože trieda úložiska (storage class) neexistuje. Chýba cert-manager, pričom v takom prípade inštalácia vôbec nezamrzne: zlyhá v priebehu niekoľkých sekúnd, pretože vydavatelia certifikátov v charte potrebujú prostriedky nástroja cert-manager.

Začnite podmi a úlohami (Job) hookov:

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

Príkaz describe zobrazuje vo svojich udalostiach chyby pri sťahovaní obrazov a nepripojené zväzky. Úloha (Job) hooku, ktorá ukazuje 0/1 dokončení so zlyhaným podom, zastavila inštaláciu, pretože úlohy hookov majú limit opakovaní (backoff limit) nastavený na 0 a nikdy sa potichu neopakujú. Príčinu nájdete v jej zázname (logu).

Tu je postup, ako vyriešiť jednotlivé príčiny:

  • Ak Helm čaká s parametrom --wait, zastavte ho, odinštalujte vydanie a nainštalujte ho znova bez tohto príznaku. Potom počkajte na služby:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
  • Pri chybách sťahovania skontrolujte global.imageRegistry a v prípade edície Enterprise aj sťahovací token zo stránky Sťahovacie tokeny a inštalačné príkazy (Pull tokens and install commands) vo vašom účte.
  • Pri zväzkoch v stave Pending nastavte storage.className na triedu úložiska, ktorú klaster má, alebo nastavte jednu z nich ako predvolenú.
  • V prípade chýbajúceho nástroja cert-manager nainštalujte cert-manager v1.21.3 a spustite inštaláciu znova.
  • V prípade zlyhaného hooku opravte to, čo sa uvádza v jeho zázname (logu), a spustite inštaláciu znova.

Pod čaká na svoju schému

Pod služby zotrváva celé minúty v stave Init:0/1. Každá služba, ktorá používa databázu, má inicializačný kontajner wait-for-schema, ktorý drží pod, kým účtovná kniha vydaní (release ledger) neukáže, že jej migrácie pre obraz tohto vydania boli použité. Počas prvých minút inštalácie alebo aktualizácie, kým bežia migračné hooky, je to normálne. Problém nastáva, keď sa tento stav nekončí.

Prečítajte si záznam (log) inicializačného kontajnera:

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

Záznam uvádza názov komponentu, migračné reťazce, na ktoré čaká, a jeho časový limit, a potom vypíše riadok pri každej zmene svojho stavu:

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
Riadok priebehu uvádza Čo to znamená
Ktoré reťazce sa ešte majú použiť pre toto vydanie Uvedené migračné hooky sa ešte nedokončili. Pozrite sa na príslušné úlohy (Jobs).
Že účtovnú knihu vydaní nie je možné prečítať, spolu s chybou databázy Postgres neodpovedá alebo účtovná kniha neexistuje, pretože neprebehlo zavedenie (bootstrap) databázy.
FAILED (<component>): after <n>s, … Vzdal to po uplynutí schemaWait.timeoutSeconds (predvolene 1 800). Inicializačný kontajner sa reštartuje; samotná služba sa vôbec nespustila.

Reťazec, ktorý sa nikdy nepoužije, takmer vždy znamená, že zlyhala jeho migračná úloha (Job). Nájdite ju pomocou kubectl -n nexus get jobs a prečítajte si jej záznam. Opravte to, čo uvádza (plný disk, externá databáza, s ktorou sa migrátor nedokáže spojiť, konflikt rolí), a spustite helm upgrade s rovnakými hodnotami: hooky sa spustia znova a každý z nich je bezpečné spustiť opakovane.

Hodnotu schemaWait.timeoutSeconds zvýšte iba vtedy, keď je migrácia pomalá, ale prebieha v poriadku, čo môže byť prípad veľkej prvej migrácie na pomalom úložisku. Jej zvýšenie s cieľom zakryť zlyhanú úlohu len spôsobí, že pod bude dlhšie čakať na niečo, čo nikdy nepríde.

Úložisko kľúčov je zapečatené

Po výpadku napájania, reštarte uzla alebo reštarte prostredia behu kontajnerov (container runtime) sa pody obnovia a konzola sa načíta, ale všetko, čo potrebuje kľúč, zlyhá alebo čaká. Odomykač (unsealer) sa po každom reštarte svojho uzla spúšťa uzamknutý (sealed) a úložisko kľúčov sa nedokáže samo odomknúť, kým nie je otvorený odomykač.

Opýtajte sa služby OpenBao v každom pode:

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

Návratový kód 0 znamená odomknuté (unsealed), 2 znamená uzamknuté (sealed) a 1 znamená, že služba nedokázala odpovedať (opýtajte sa znova o minútu). Spustite to isté voči openbao-0 s -tls-server-name=openbao pre úložisko kľúčov. Ak je odomykač odomknutý a úložisko kľúčov nie je, úložisko kľúčov sa práve samo odomyká; doprajte mu minútu.

Na vyriešenie uzamknutého odomykača jeden zo správcov kľúčov (custodian) spustí skript chartu unseal.sh so svojou vlastnou identitou age. Úplný príkaz nájdete v kapitole 2.15, Druhý deň: prevádzka systému Nexus. Návratový kód skriptu vám povie, čo sa stalo:

Návratový kód Význam Čo robiť
0 Odomknuté Do minúty skontrolujte kubectl -n nexus get deploy,statefulset.
1 Stále zamknuté alebo volanie na odomknutie zlyhalo Prečítajte si riadky podielov (shares), ktoré vypísal; spustite ho znova.
2 Chýba prerekvizita Správa ju pomenuje: AGE_IDENTITY, binárny súbor ako age alebo jq, prípadne nastavenie priameho režimu (direct-mode).
3 Táto identita nedokáže dešifrovať podiely Nie ste správcom kľúčov tejto inštalácie. Nič nebolo odoslané. Nájdite správcu kľúčov, ktorý ním je.

Nemožno sa prihlásiť cez protokol HTTP

Konzola sa načíta na adrese http:// alebo cez kubectl port-forward na 127.0.0.1 a prihlásenie zlyhá. Výzva na zadanie prístupového kľúča (passkey) sa vôbec nezobrazí alebo sa prihlasovanie v slučke vracia na začiatok.

Prihlásenie vyžaduje vlastný pôvod (origin) HTTPS konzoly. Konzola prijíma prihlásenie iba z https://<hosts.console>, udržiava reláciu v súbore cookie __Host- označenom ako Secure (ktorý prehliadač ukladá iba cez HTTPS) a prístupový kľúč (passkey) prvého administrátora vyžaduje stránku s platným certifikátom. Prehliadače pri chybe certifikátu prístupové kľúče odmietajú. Presmerovanie portov (port-forward) na http://127.0.0.1 sa nikdy nedokáže prihlásiť.

Skontrolujte, kam sa prehliadač v skutočnosti pripojil:

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

Prvý príkaz by mal odpovedať cez HTTPS s certifikátom, ktorému váš počítač dôveruje. Druhý by mal zobraziť troch hostiteľov s názvami, ktoré ste nastavili v hosts.*.

Na vyriešenie problému otvorte konzolu na adrese https://console.harrow.example, čo je presný názov v hosts.console, s certifikátom, ktorému prehliadač dôveruje. Pri tls.mode: existing skontrolujte, či tls.existingSecret obsahuje certifikát pre všetkých troch hostiteľov. Pri tls.mode: cert-manager skontrolujte, či ho vydal ClusterIssuer. Pri tls.mode: none sa protokol Transport Layer Security (TLS) ukončuje na vašom vlastnom vyvažovači záťaže (load balancer) a práve tam musí byť certifikát v poriadku. V prípade súkromnej certifikačnej autority nainštalujte jej certifikát na počítače, z ktorých sa hlásia vaši administrátori.

Platnosť kódu na prevzatie vypršala

Na stránke Priradiť túto inštaláciu (Claim this installation) stránka odmietne kód s chybou CLAIM_CODE_EXPIRED (410). Kód priradenia pozostáva z troch skupín po štyroch znakoch. Funguje raz, po dobu 30 minút, s 5 pokusmi. Po uplynutí tejto doby alebo po piatom nesprávnom pokuse je neplatný a nič sa nepriradilo ani nezmenilo.

Vytvorte nový kód z terminálu, ktorý má prístup ku klastru:

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

Vypíše nový kód a odtlačok (fingerprint) inštalácie. Zadajte kód na stránke priradenia do 30 minút a znova porovnajte odtlačok.

Prevziať túto inštaláciu
Prevziať túto inštaláciu
Priradiť túto inštaláciu. Kód z terminálu sa zadáva v troch skupinách a stránka zobrazuje úplný odtlačok v skupinách po štyroch na porovnanie; kód s uplynutou platnosťou je odmietnutý s chybou CLAIM_CODE_EXPIRED a nič sa nepriradí.

Dve súvisiace odpovede:

  • Chyba RATE_LIMITED (429) na stránke priradenia znamená, že stránka zaznamenala za poslednú minútu viacero pokusov. Počkajte počet sekúnd, ktorý uvádza. Ak ste tieto pokusy neurobili vy, stránku skúša niekto iný vo vašej sieti; pred priradením zistite, kto to je.
  • Chyba TRANSITION_NOT_PERMITTED (409) znamená, že inštalácia už je priradená a jej stránka priradenia je natrvalo vypnutá. Namiesto toho sa prihláste. Ak ste ju nepriradili vy, považujte to za bezpečnostný incident.

Odtlačok (fingerprint) sa nezhoduje

Stránka priradenia zobrazí chybu CLAIM_FINGERPRINT_MISMATCH (403) alebo sami vidíte, že osem skupín po štyroch znakoch na stránke sa líši od tých, ktoré vypísal váš terminál. Aj jedna odlišná skupina znamená, že prehliadač komunikuje s inou inštaláciou.

Zastavte. Nezadávajte kód do tejto stránky. Na tejto adrese môže odpovedať niečo iné než vaša inštalácia, možno stroj nastražený na zachytenie prvého administrátora. Ak by ste vykonali priradenie, tento stroj by získal kontrolu nad vašou organizáciou. Vaša vlastná inštalácia je nezmenená a stále nepriradená.

Skontrolujte, kam smeruje názov a ktorý certifikát odpovedal:

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

Adresa by mala patriť vášmu radiču prichádzajúcej prevádzky (ingress controller) a certifikát by mal byť ten, ktorý ste nainštalovali pre hosts.console.

Odtlačok sa nezhoduje
Odtlačok sa nezhoduje
Odtlačky sa líšia v troch z ôsmich skupín. Stránka vyzýva, aby ste zastavili, vysvetľuje, kto by mohol odpovedať, a uvádza zoznam toho, čo treba pred ďalším pokusom skontrolovať.

Na vyriešenie problému odovzdajte svojmu bezpečnostnému tímu adresu, ktorá odpovedala, a uchovajte záznam (log) inštalácie, v ktorom je zaznamenaný odtlačok vypísaný inštaláciou. Opravte záznam v systéme doménových mien – Domain Name System (DNS) – alebo server proxy, ktorý vás presmeroval inam. Potom vytvorte nový kód priradenia pomocou nexusctl claim-code --administrator <email> a vykonajte priradenie z prehliadača v sieti, ktorej dôverujete, pričom znova porovnajte všetkých osem skupín.

Licencia je odmietnutá

Import na stránke Importovať licenciu (Import the licence), Importovať novú licenciu (Import a new licence) alebo príkazom nexusctl licence import odpovie zamietnutím. Zamietnutý import nič nemení: platná licencia zostáva v platnosti a spodná hranica hodín (clock floor) sa neposunie.

Prečítajte si kód a krok:

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

Telo zamietnutia obsahuje code, message, refused_at (krok, ktorý zlyhal) a troubleshooting. Ak chcete zobraziť stav platnej licencie, prečítajte GET https://auth.harrow.example/api/v1/installation/licence/state s rovnakým tokenom.

Kód HTTP Zvyčajná príčina Riešenie
LICENCE_SIGNATURE_INVALID 422 Súbor bol upravený, preformátovaný alebo znova uložený, prípadne chýba jeden podpis Stiahnite ho znova zo svojho účtu a importujte ho bez úprav
LICENCE_FORMAT_INVALID 422 Nejdeo licenciu: nesprávny súbor, skrátený súbor alebo súbor zabalený v inom objekte Odošlite súbor presne tak, ako ho spoločnosť Adverant poskytla
LICENCE_ROOT_UNKNOWN 422 Podpísané kľúčom, ktorý toto vydanie neobsahuje Aktualizujte systém alebo požiadajte o licenciu podpísanú pre vaše vydanie
LICENCE_MATRIX_MISMATCH 422 Napísané pre novšiu maticu edícií alebo udeľuje skupinu, ktorú táto zostava nepozná Aktualizujte systém alebo požiadajte o licenciu napísanú pre vaše vydanie
LICENCE_OTHER_INSTALLATION 409 Vydané pre inú inštaláciu, často ide o licenciu testovacieho klastra použitú v produkcii Požiadajte o licenciu pre identitu tejto inštalácie
LICENCE_REVOKED 403 Spoločnosť Adverant ju stiahla Požiadajte spoločnosť Adverant o novú licenciu
LICENCE_LOCKED 403 Jej dátum starts_on je neskorší ako aktuálny dátum Importujte ju v jej prvý deň platnosti alebo neskôr
TRANSITION_NOT_PERMITTED 409 Toto ID licencie už bolo importované Nie je potrebné robiť nič, ak je v platnosti; ak sa musia zmeniť podmienky, kontaktujte spoločnosť Adverant
RECORD_NOT_FOUND 404 Inštalácia ešte nebola deklarovaná, takže zatiaľ nemá identitu Dokončite krok prvého administrátora a potom vykonajte import
TENANT_NOT_A_PARAMETER 403 Telo požiadavky uvádza organizáciu na svojej najvyššej úrovni Odošlite ako telo požiadavky iba samotný súbor licencie

Dve veci vyzerajú ako problémy s licenciou, ale nie sú nimi. Čítanie stavu, ktoré obsahuje LICENCE_CLOCK_BEHIND_FLOOR, znamená, že hodiny uzla ukazujú skorší čas ako posledný čas, ktorý inštalácia zaznamenala; opravte čas uzla, a ak hodiny prebehli dopredu a posunuli so sebou aj spodnú hranicu (floor), požiadajte spoločnosť Adverant o token na resetovanie času. A licencia, ktorá sa naimportuje, no stále zobrazuje skupinu len ako ukážku (teaser), túto skupinu zvyčajne neudeľuje: pred čímkoľvek iným si prečítajte udelené oprávnenia na stránke licencie.

Žiadne odpovede od AI

Asistent umelej inteligencie (AI) zobrazí chybu MODEL_NOT_CONNECTED (503), krok pracovného postupu (workflow) zlyhá s chybou NO_PROVIDER_FOR_ROLE (422) alebo odpovede jednoducho prestanú prichádzať.

V zásobníku (pool) organizácie nie je žiadny kľúč, ktorý by dokázal odpovedať, alebo sa smerovač (router) nedokáže spojiť s poskytovateľom. Každá organizácia si prináša svoj vlastný kľúč k modelom. Bez používaného kľúča nie je k dispozícii žiadna AI – je to tak navrhnuté zámerne a žiadny zdieľaný kľúč ju nezastúpi.

Skontrolujte zásobník a voľbu smerovača, oboje pomocou vlastného prístupového tokenu danej osoby:

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

Prvý príkaz vypíše každého poskytovateľa, či dokáže odpovedať a prečo nie ("No key in use: 1 withdrawn, 1 lapsed"), a stav každého kľúča. Druhý vráti model, ktorý by smerovač použil pre organizáciu, alebo slovné odôvodnenie jeho zamietnutia. Potom skontrolujte cestu von z klastra pomocou týchto dvoch príkazov:

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

Čo jednotlivé zistenia znamenajú:

Zistenie Riešenie
V zásobníku nie je žiadny kľúč Vlastník alebo administrátor pridá kľúč organizácie na prepájacej doske AI (AI switchboard) alebo v časti Nastavenia, Modely AI (Settings, AI models)
Kľúče v stave invalid, expired alebo exhausted Pridajte nový kľúč; starý zostane uvedený ako história
Kľúče v stave resting Počkajte: zlyhávajúci kľúč odpočíva 60 sekúnd a po 5 zlyhaniach za sebou sa vypne (PROVIDER_KEY_SWITCHED_OFF)
NO_PROVIDER_FOR_ROLE s používanými kľúčmi Rola nemá priradenie a nič jej nezodpovedá; nastavte rolu v politike smerovania
MODEL_CAPABILITY_UNAVAILABLE (422) Požiadavka vyžaduje schopnosť alebo umiestnenie dát (residency), ktoré neponúka žiadny poskytovateľ v zásobníku; povoľte takého, ktorý ich ponúka
Žiadna politika nexus-operator-egress alebo v nej chýbajú rozsahy poskytovateľa Pridajte rozsahy zapísané v notácii Classless Inter-Domain Routing (CIDR) do networkPolicy.externalEgressCIDRs a vykonajte aktualizáciu
Lokálny server modelov, ktorý neodpovedá Skontrolujte ai.localProvider.baseUrl, uveďte server v ai.installationHosts a povoľte jeho rozsah v networkPolicy.externalEgressCIDRs

Kľúč hostovaného poskytovateľa, ktorý funguje z prenosného počítača a zlyháva v inštalácii, je takmer vždy spôsobený sieťovou politikou. Menný priestor predvolene zakazuje odchádzajúcu prevádzku (egress).

Odpovede 429

Klient dostane odpoveď 429 Too Many Requests. Nexus má štyri miesta, ktoré ju môžu vrátiť, a telo odpovede vám povie, ktoré z nich to bolo.

Kde Kód a podrobnosti Čo zmeniť
nexus-auth, na prihlásenú osobu RATE_LIMITED s limit, windowSeconds a retryAfterSeconds auth.rateLimitPerMinute (predvolene 5000), pre intenzívnu automatizáciu
Limit kľúča skriptu, aplikácie alebo jednotky (Enterprise) RATE_LIMITED s uvedením kľúča a jeho limitu Limit v časti Nastavenia, Limity frekvencie požiadaviek (Settings, Rate limits), s uvedením dôvodu
Stránka priradenia pri prvom spustení RATE_LIMITED s retry_after_seconds Nič: počkajte a zistite, kto ďalší stránku skúša
Poskytovateľ modelu Smerovač to považuje za prechodné zlyhanie a prejde na ďalšieho poskytovateľa Ak sa to stáva často, pridajte ďalší kľúč alebo poskytovateľa

Každá z týchto odpovedí obsahuje hlavičku Retry-After. Správne navrhnutý klient počká uvedenú dobu a neskúša to skôr.

Ak sa zdá, že všetci používatelia naraz zdieľajú jeden limit, skontrolujte proxy.trustedCIDRs. Keď nepokrýva sieť podov vášho radiča prichádzajúcej prevádzky (ingress controller), služba nexus-auth nemôže dôverovať hlavičke X-Forwarded-For a vníma každú požiadavku, akoby prichádzala priamo z radiča. Predvolená hodnota 10.42.0.0/16 vyhovuje iba prostrediu k3s.

kubectl get pods -A -o wide

Vo výstupe nájdite adresu podu radiča prichádzajúcej prevádzky a uistite sa, že ju proxy.trustedCIDRs pokrýva.

Chyby pri aktualizácii na vyššiu verziu

Aktualizácia sa vrátila späť (rolled back). Stránka Aktualizácia (Upgrade) zobrazuje UPGRADE_ROLLED_BACK: niektorý krok zlyhal, každý engine je späť na predchádzajúcom vydaní a dáta sa nezmenili. Stránka uvádza názov daného kroku. Častou príčinou je príliš malý zväzok pre nové rozloženie úložiska. Opravte to, čo sa uvádza, spustite znova nexusctl upgrade plan --bundle <file> a potom zmeny použite. Najprv sa znova vytvorí záloha.

Chart odmieta vykreslenie s chybou EXTERNAL_KEY_ENCRYPTION_KEY_INVALID. Objekt Secret nexus-generated uchováva EXTERNAL_KEY_ENCRYPTION_KEY v tvare, ktorý chart nedokáže použiť. Musí ísť o base64 zápis 32 bajtov alebo o nespracovaný (raw) 32-bajtový kľúč zo staršej inštalácie. Niekto upravil alebo nahradil objekt Secret. Vráťte späť kľúč, pod ktorým sú uzamknuté dáta tejto inštalácie, ako base64 zápis jeho 32 bajtov (printf %s "$OLD" | base64), a znova spustite aktualizáciu. Nenechajte chart vytvoriť nový kľúč: dáta uzamknuté pod starým kľúčom by zostali nečitateľné.

Skripty sú po aktualizácii odmietané s chybou TOKEN_ORG_MISSING. Každá služba, ktorá kontroluje kľúče aplikačného programovacieho rozhrania – application programming interface (API) – cez službu nexus-auth, teraz odmieta kľúč bez organizácie s chybou 403 TOKEN_ORG_MISSING. Priraďte každému takémuto kľúču organizáciu alebo vydajte nový kľúč.

Kľúče hlásia nesprávnu aplikáciu po dobu jednej hodiny. Vyprázdnite položky kľúčov uložené vo vyrovnávacej pamäti služby nexus-auth, ktorou je úložisko Valkey danej inštalácie. Príkaz pre úložisko v klastri aj pre externé úložisko nájdete v kapitole 2.15, Druhý deň: prevádzka systému Nexus.

Migračný hook zlyhal. Príkaz helm upgrade hlási zlyhaný hook pred aktualizáciou (pre-upgrade hook). Schéma sa presúva pred nasadením nových podov, takže bežiace vydanie naďalej poskytuje služby. Prečítajte si záznam (log) úlohy pomocou kubectl -n nexus logs job/<job-name>, opravte to, čo uvádza, a spustite aktualizáciu znova.

Služby nemohli niekoľko sekúnd používať svoje tabuľky. Pri prvej aktualizácii inštalácie vytvorenej zo staršieho chartu stratí každá služba svoje staré predvolené práva k tabuľkám a získa späť svoje vlastné práva zo svojej vlastnej migrácie. Výpadok trvá niekoľko sekúnd. Aktualizujte v období nízkej prevádzky alebo služby najprv naškálujte na nulu.

Vydanie na disku bolo odmietnuté. Import z média zobrazí chybu MEDIA_SIGNATURE_INVALID (422): súbory nie sú podpísané kľúčom vydania nainštalovaným v tejto inštalácii. Nič sa nenačítalo a bežiace vydanie beží ďalej. Médium uchovajte pre svoj bezpečnostný tím a požiadajte spoločnosť Adverant o nové médium prostredníctvom offline výmeny.

Odmietnutie vykreslenia chartu

Príkaz helm install, helm upgrade alebo helm template sa zastaví skôr, než sa čokoľvek použije, so správou, ktorá sa začína kódom alebo uvádza názov hodnoty. Chart odmieta hodnoty, s ktorými nemôže bezpečne bežať. V klastri sa nič nezmenilo.

Vykreslite chart samostatne, aby ste videli každé zamietnutie bez zásahu do klastra. V edícii Enterprise použite namiesto adresy oci:// stiahnutý chart Enterprise a v hodnotách nastavte networkPolicy.apiServerCIDRs, pretože offline vykreslenie ho nedokáže prečítať z klastra:

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

Predletová kontrola (Preflight) kontroluje rovnaké hodnoty identity vo svojej časti „čas a kľúče“ (time and keys) a hlási rovnaké kódy. Jej návratový kód je 0, keď inštalácia môže pokračovať (varovania ju neblokujú), 1, keď zlyhala aspoň jedna kontrola, a 2, keď sa nemohla spustiť.

Predbežná kontrola nemôže pokračovať
Predbežná kontrola nemôže pokračovať
Predletová kontrola nemôže pokračovať. Zlyhávajúce kontroly sú uvedené ako prvé, každá so svojím riešením, a inštalácia zostáva zablokovaná s chybou PREFLIGHT_FAILED, kým neprejdú.
Odmietnutie Príčina Riešenie
INSTALLATION_NAME_MISSING Hodnota keys.installationName je prázdna Nastavte ju na vlastný názov tejto inštalácie, ktorý sa zhoduje s ^[a-z][a-z0-9-]{0,62}$. Po prvom spustení úložiska kľúčov je tento názov trvalý
INSTALLATION_NAME_EXAMPLE Názov je ten, ktorý sa nachádza vo vzorových súboroch hodnôt chartu Nastavte svoj vlastný názov
keys.installationName "…" does not match … Veľké písmená, podčiarkovníky alebo číslica na začiatku Použite malé písmená, číslice a spojovníky, pričom začnite písmenom
KEYS_CUSTODIAN_MISSING Hodnota keys.custody.recipients je prázdna Uveďte príjemcov age vašich správcov kľúčov, teda verejné polovice kľúčov
KEYS_CUSTODIAN_EXAMPLE Príjemcom je vzorový správca kľúčov zo súborov hodnôt chartu, ktorého identitu nikto nevlastní Nahraďte ho príjemcami vašich vlastných správcov kľúčov
keys.custody.recipients: … Príjemca je v tvare, pre ktorý úloha správy kľúčov (custody Job) nedokáže šifrovať Použite age1…, age1tag1…, age1tagpq1…, age1pq1… alebo age1se1…, malými písmenami
NEXUS_EDITION_INVALID Hodnota edition nie je community ani enterprise Nastavte jednu z týchto dvoch možností
edition=… but enterprise.enabled=… Tieto dve hodnoty sú v rozpore Nastavte enterprise.enabled: true presne vtedy, keď edition je enterprise
global.imageRegistry is required Nie je uvedený žiadny register Nastavte register, z ktorého vaše uzly sťahujú obrazy
hosts.<name> is required Chýba verejný hostiteľ Nastavte hosts.console, hosts.api a hosts.auth
tls.existingSecret is required when tls.mode is existing Nie je uvedený žiadny objekt Secret certifikátu Uveďte názov objektu Secret alebo zvoľte inú možnosť tls.mode
tls.clusterIssuer is required when tls.mode is cert-manager Nie je uvedený žiadny vydavateľ (issuer) Uveďte názov svojho objektu ClusterIssuer
dataTier.<store>.external.host is required when mode is external Externé úložisko bez adresy Uveďte jeho hostiteľa a jeho objekt Secret v existingSecret
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read Príkaz helm template nemá žiadny klaster, v ktorom by ich mohol vyhľadať Uveďte adresy servera API ako rozsahy /32
EXTERNAL_KEY_ENCRYPTION_KEY_INVALID Vygenerovaný kľúč v nexus-generated má nesprávny tvar Pozrite si časť „Chyby pri aktualizácii“ vyššie

Súbor hodnôt, ktorý používa kľúč, ktorý chart nemá, alebo hodnotu nesprávneho typu, schéma chartu zamietne ešte pred všetkými týmito kontrolami. Jedným z príkladov je telemetry.enabled: true: schéma prijíma iba false.

Odoslanie balíka pre podporu

Keď nič z uvedeného problém nevyrieši, pošlite spoločnosti Adverant diagnostický balík podpory (support bundle) spolu so svojou žiadosťou o podporu.

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

<request-number> je číslo žiadosti, ktorú ste otvorili na stránke Podpora a balíky podpory (Support and support bundles) vo svojom účte. Rovnaký balík môžete vytvoriť aj na stránke Balík podpory (Support bundle) v konzole v časti Táto inštalácia (This installation).

Balík obsahuje záznamy (logy) enginov za posledných 24 hodín, podrobnosti o stave a verziách, nastavenia bez ich tajomstiev a správy z predletovej kontroly a inštalácie. Pred jeho zapísaním redigovanie nahradí mená, tajomstvá a adresy a vy si môžete prečítať ukážku presne toho, čo odchádza. Správy, súbory a pamäť ľudí sa nikdy nezhromažďujú.

Nahrajte ho k žiadosti vo svojom účte, alebo ho uložte na médium a vyneste von, ak inštalácia nemá pripojenie do vonkajšej siete. Otvoriť ho môžu iba inžinieri podpory uvedení v žiadosti a po 30 dňoch sa vymaže. V žiadosti uveďte, ktorý z vyššie uvedených problémov ste riešili a čo ukázali kontroly v tejto kapitole: ušetrí to jedno kolo komunikácie.