Přihlásit seDomluvit prezentaci

Kapitola 2.15

Druhý den: provoz systému Nexus

Běžná práce spojená s provozem instalace po prvním týdnu. Začíná odpečetěním úložiště klíčů po restartu a končí odinstalací.

Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

18 min čtení

Když v serverovně Harrow Port Authority poprvé vypadl proud, naběhlo zpět vše kromě částí, které potřebovaly klíče. Pody měly stav Running a konzole se načetla. Nikdo ale nemohl otevřít žádný soubor. Tomás Reilly o tom četl, a přesto mu trvalo dvacet minut, než si vzpomněl proč. Služba pro odpečetění úložiště klíčů (unsealer) se po každém restartu svého uzlu spustí zapečetěná a otevřít ji může pouze správce klíčů (custodian).

Tato kapitola sleduje běžný provoz administrátora po prvním týdnu – od úložiště klíčů a jeho správců až po odinstalaci. Každý příkaz nexusctl zde přijímá parametr --explain, který vypíše operace kubectl a helm, jež by provedl, aniž by je skutečně spustil. Použijte jej vždy, když na produkčním clusteru spouštíte cokoli poprvé.

Správa úložiště klíčů

Instalace má ve svém jmenném prostoru dva servery OpenBao. Úložiště klíčů, openbao, uchovává všechny klíče, které Nexus používá. Unsealer, openbao-unsealer, je druhý, malý server OpenBao, jehož jediným úkolem je odpečetit úložiště klíčů. Úložiště klíčů se odpečeťuje samo pomocí tranzitního klíče unsealeru; samotný unsealer je zapečetěn Šamirovým schématem jako 5 podílů, z nichž libovolné 3 jej odpečetí.

Při první instalaci inicializuje oba servery uvnitř clusteru úloha (Job) pro správu klíčů. Ve své vlastní paměti zašifruje podíly unsealeru a obnovovací klíče úložiště klíčů pro každého správce klíčů uvedeného v keys.custody.recipients a uloží pouze šifrový text (objekty Secret openbao-unseal-shares-encrypted a openbao-recovery-keys-encrypted). Ve stejné úloze zneplatní oba kořenové tokeny (root tokens). Balíček každého správce klíčů obsahuje dostatek podílů k samostatnému odpečetění, takže po restartu stačí jediný správce klíčů.

Po restartu uzlu

Po jakémkoli restartu uzlu, na kterém běží unsealer (výpadek proudu, restart stroje, restart běhového prostředí kontejnerů), se unsealer spustí zapečetěný. Dokud jej správce klíčů neodpečetí, zůstává zapečetěné i úložiště klíčů a nefunguje nic, co vyžaduje klíč. Konzole sice dál odpovídá a lidé se mohou přihlásit, ale jakýkoli úkon vyžadující klíč z úložiště klíčů čeká: otevírání šifrovaného obsahu, nárokování instalace, kontrola zkompilované části.

Zeptejte se přímo serveru OpenBao uvnitř každého podu. Toto je unsealer:

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

Spusťte stejný příkaz proti openbao-0 s -tls-server-name=openbao pro úložiště klíčů. bao status skončí s kódem 0, když je server odpečetěný, 2, když je zapečetěný, a 1, když nedokázal odpovědět. Návratový kód 1 nic neznamená, protože pod ještě nemusí běžet. Počkejte minutu a zeptejte se znovu. Pokud je unsealer odpečetěný a úložiště klíčů je stále zapečetěné, úložiště klíčů se právě odpečeťuje samo a vy nemusíte dělat nic.

Vlevo: ikona osoby označená „Správce klíčů se svou vlastní age identitou“. Šipka vede doprava do pole „unseal.sh na stroji správce klíčů (jedno dešifrování)“. Odtud vede šipka označená „kubectl port-forward, Transport Layer Security (TLS) ověřené vůči certifikační autoritě (CA) unsealeru“ do pole „openbao-unsealer (Šamir, 5 podílů, libovolné 3)“. Z unsealeru vede druhá šipka označená „tranzitní klíč, automaticky“ do pole „openbao, úložiště klíčů“. Z úložiště klíčů vede vějíř šipek do malých polí „nexus-keys“, „nexus-auth“, „ostatní služby“. Poznámka pod správcem klíčů: „identita nikdy neopouští tento stroj“.
Co dělá správce klíčů po restartu uzlu.

Odpečetění

Chart obsahuje skript unseal.sh ve složce files/custody/, který je v každém vydání bajt po bajtu stejný. Správce klíčů jej spouští na svém vlastním stroji. Skript načte zašifrovaný Secret, jednou jej dešifruje pomocí identity správce klíčů (identita v Secure Enclave si jednou vyžádá Touch ID), odešle podíly unsealeru a potvrdí, že je odpečetěn. Žádný podíl se nikdy nezapisuje do souboru ani nepředává na příkazovém řádku.

Harrow jej spouští v přímém režimu přes přesměrování portů (port-forward):

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity> je soubor s age identitou správce klíčů, tedy soukromá polovina jednoho z příjemců v keys.custody.recipients. UNSEAL_RESOLVE je název, který nese certifikát unsealeru (<namespace> je jmenný prostor, ve kterém je Nexus nainstalován, ve výchozím nastavení nexus), takže TLS se kontroluje vůči vlastní certifikační autoritě (CA) unsealeru, i když připojení směřuje na 127.0.0.1. Skript nikdy nevypíná kontrolu certifikátu.

Návratový kód Poslední řádek Význam
0 UNSEALED nexus/openbao-unsealer-0 Odpečetěno. Pokud již odpečetěno bylo, nic se neodeslalo
1 STILL-SEALED … Stále zapečetěno, nebo volání pro odpečetění selhalo
2 UNSEAL-REFUSED … Chybí prerekvizita uvedená ve zprávě
3 UNSEAL-REFUSED … Tato identita nedokáže dešifrovat podíly, takže není správcem klíčů této instalace. Nic se neodeslalo

Během minuty jej úložiště klíčů samo následuje. Pomocí kubectl -n nexus get deploy,statefulset zkontrolujte, že je vše opět připraveno.

Správci klíčů se vybírají před instalací a každý si vytvoří svůj vlastní klíč na svém vlastním stroji. Chart vždy vidí pouze veřejnou polovinu:

age-keygen -o custodian.key
age-plugin-se keygen --access-control=any-biometry -o custodian.key

První příkaz vytvoří běžnou age identitu; jejím příjemcem je řádek # public key: age1... v souboru. Druhý vytvoří identitu uloženou v Secure Enclave na Macu s příjemcem začínajícím na age1se1. Kterýkoli z těchto příjemců se vloží do keys.custody.recipients. Soubor s identitou zůstává u svého správce klíčů, offline.

Zálohování a obnova

Stránka Zálohování a obnova zobrazuje každé úložiště s jeho poslední zálohou a časem, kdy byla naposledy skutečně otestována jeho obnova. Záloha je prověřená teprve tehdy, když byla obnovena, proto stránka sleduje obojí. Zálohuje se šest úložišť. Hlavní databáze uchovává osoby a nastavení, úlohy a auditní protokol. Vedle ní je znalostní graf a vyhledávací index, dále úložiště souborů a úložiště paměti. Šestým jsou klíče, zapečetěné a uchovávané odděleně od dat. Zálohy směřují do vašeho vlastního úložiště, jsou šifrovány vašimi vlastními klíči a Adverant je nemůže číst. Když úložiště nebylo cvičně obnoveno ve stanovené lhůtě, zobrazí se na stránce štítek RESTORE_TEST_OVERDUE s tlačítkem Otestovat nyní. Testovací obnova probíhá v odděleném prostoru a nikdo ji nepocítí.

Stejné dva úkony jsou dostupné z příkazového řádku:

nexusctl backup now
nexusctl backup verify

backup now pořídí zálohu všech úložišť najednou. backup verify zkontroluje nejnovější zálohu. Spusťte obojí před jakoukoli změnou, ze které máte obavy.

Zálohování a obnova
Zálohování a obnova
Každé úložiště se svou poslední zálohou a poslední otestovanou obnovou. Vyhledávací index má zpoždění s testem a štítek nabízí jeho okamžité spuštění.

Při obnově uvedete název zálohy:

nexusctl restore --from <backup-id>

<backup-id> pochází ze seznamu na stránce Zálohování a obnova. Obnova vyžaduje schválení druhou osobou a během jejího běhu ji ukazuje proužek průběhu s časem spuštění a jménem schvalovatele. Během obnovy mají všichni přístup jen pro čtení, což se liší od uzamčení: lidé se mohou přihlásit a číst. Úlohy se nespouštějí (plány čekají a doběhnou později) a vyhledávání se vrátí, jakmile je zpět vyhledávací index. Vše, co bylo zapsáno po pořízení zálohy, je ztraceno, a proto to zpráva o obnově vypíše podle vlastníků, aby to mohli provést znovu.

Obnovování
Obnovování
Probíhající obnova. Úložiště se vracejí v daném pořadí, uživatelé mají režim jen pro čtení, dokud není nahráno poslední z nich, a oznámení na každé stránce uvádí, kdy lze očekávat dokončení.

Spolu se zálohami uchovávejte ještě jednu věc: Secret nexus-generated ve jmenném prostoru nexus. Chart při první instalaci vytvoří vygenerovaná hesla a šifrovací klíče instalace a při každém upgradu je z tohoto objektu Secret znovu načítá. Data zapečetěná pod EXTERNAL_KEY_ENCRYPTION_KEY lze otevřít pouze tímto klíčem. Uložte si kopii tohoto objektu Secret tam, kde uchováváte ty nejcitlivější materiály, protože kdokoli jej drží, drží i tyto klíče.

Upgrady

Tomás provádí upgrade ve dvou krocích. Nejprve se zeptá, co se změní:

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Plán vypíše, co se ve vydání mění, jakékoli změny ve struktuře databáze a zda je lze vrátit zpět. Poté jej aplikuje:

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Aplikování nejprve pořídí zálohu a spustí předběžnou kontrolu (preflight). Poté přesouvá enginy ve vlnách, přičemž každá vlna čeká, dokud ta předchozí neběží v pořádku po dobu 10 minut. Stránka Upgrade zobrazuje každou probíhající vlnu a průběžný stav instalace. Uvádí také, dokdy zůstává otevřená cesta zpět; po tomto datu vyžaduje návrat obnovu ze zálohy. Pokud některý krok selže, Nexus vrátí všechny enginy zpět na předchozí vydání a zkontroluje je. Oznámení UPGRADE_ROLLED_BACK pak uvede krok, který selhal, a potvrdí, že data nebyla změněna. Před tlačítkem Zkusit znovu je uveden postup opravy a balíček pro podporu je dostupný jedním tlačítkem.

Pro instalaci bez vnějšího připojení přichází balíček na médiu. Import z média zkontroluje podpis vydání vůči klíči vydání společnosti Adverant nainstalovanému v instalaci a ověří, že verze postupují pouze vpřed. Soubory podepsané kýmkoli jiným jsou odmítnuty s chybou MEDIA_SIGNATURE_INVALID: nic se nenačte a běžící vydání běží dál.

Upgrade
Upgrade
Probíhající upgrade. Nejprve byla pořízena záloha, právě probíhá druhá ze tří vln a cesta zpět zůstává otevřená do uvedeného data.
Upgrade selhal a byl vrácen zpět
Upgrade selhal a byl vrácen zpět
Vlna selhala, protože na svazku došlo místo. Všechny enginy jsou zpět na předchozím vydání s nedotčenými daty a před tlačítkem Zkusit znovu je uveden postup opravy.

Co se děje na pozadí

nexusctl upgrade apply spustí helm upgrade nad chartem. Pokud provádíte upgrade pomocí nástroje Helm sami, platí stejná pravidla:

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

Schéma se přesune před spuštěním nových podů. Migrace chartu jsou hooky typu pre-upgrade, které běží v tomto pořadí: nejprve bootstrap databáze, poté migrace jednotlivých služeb a nakonec migrace backendu pro frontend (BFF) konzole. Běží také úloha pro správu klíčů (custody Job), která na již inicializované instalaci tento stav potvrdí a nic nemění. Každá úloha hooku má limit opakování (backoff limit) nastavený na 0, takže migrace, která selže, zastaví upgrade a nikdy se tiše neopakuje: před dalším pokusem si přečtěte její protokol pomocí kubectl -n nexus logs job/<hook-job>.

Pod každé služby čeká v init kontejneru wait-for-schema, dokud kniha vydání (release ledger) neukáže, že její migrace pro obraz nového vydání byly aplikovány. Po vrácení zpět (rollback) nebo po upgradu, který změnil pouze hodnoty, najde restartovaný pod svůj záznam a okamžitě se spustí.

Před upgradem

Při plánování stojí za to zohlednit tři body z poznámek k vydání:

  1. Provádějte upgrade v klidovém období. Při prvním upgradu instalace vytvořené ze staršího chartu odebere úloha bootstrapu stará výchozí práva k tabulkám a každá služba získá svá vlastní zpět ze své vlastní migrace. Dokud tato migrace neproběhne, služba nemůže své tabulky používat. Výpadek trvá několik sekund. Pokud na sekundách záleží, nejprve služby škálujte na nulu a po dokončení migračních úloh je znovu vraťte na původní počet.
  2. Přiřaďte každému klíči rozhraní pro programování aplikací (API) organizaci. Klíč bez organizace je odmítnut s chybou 403 TOKEN_ORG_MISSING každou službou, která kontroluje klíče přes nexus-auth, včetně nexus-graphrag. Před upgradem přiřaďte každému takovému klíči organizaci nebo vydejte klíč nový. Staré klíče bcrypt fungují dál až do data jejich pevného zneplatnění.
  3. Poté vyprázdněte mezipaměť klíčů API. Záznamy klíčů uložené v mezipaměti po dobu až jedné hodiny nesou nesprávný název aplikace, dokud to neuděláte. Spusťte tento příkaz proti mezipaměti služby nexus-auth, tedy úložišti Valkey dané instalace (nexus-valkey, heslo v objektu Secret nexus-generated pod VALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

To platí pro výchozí úložiště uvnitř clusteru. Při použití dataTier.valkey.mode: external žádný takový pod neexistuje: spusťte stejné prohledání a smazání proti svému vlastnímu hostiteli Valkey s heslem z objektu Secret uvedeného v dataTier.valkey.external.existingSecret.

Návrat k předchozí verzi (rollback)

V časovém okně, které zobrazuje stránka Upgrade, vrátí tlačítko Vrátit zpět každý engine na předchozí vydání. Po uplynutí tohoto okna znamená návrat zpět obnovení zálohy, kterou upgrade na začátku pořídil.

Dvě hodnoty se při upgradu ani při vrácení zpět nesmí nikdy změnit.

Hodnota keys.installationName je trvalá. První bootstrap úložiště klíčů pod ní vytvoří identitu instalace a právě tuto identitu uvádí vaše licence. Používejte přesně stejnou hodnotu v každém souboru hodnot (values), který kdy na tuto instalaci aplikujete.

Secret nexus-generated musí zůstat tak, jak je. Při každém upgradu z něj chart načte EXTERNAL_KEY_ENCRYPTION_KEY a zkontroluje jeho tvar. Hodnota, která není ani base64 z 32 bajtů, ani surový 32bajtový klíč ze starší instalace, zastaví vykreslení šablony s chybou EXTERNAL_KEY_ENCRYPTION_KEY_INVALID a chart hodnotu nikdy nevypíše. Znamená to, že někdo tento Secret upravil nebo nahradil. Vraťte zpět klíč, pod kterým jsou zapečetěna data této instalace, jako base64 jeho 32 bajtů (printf %s "$OLD" | base64), a spusťte upgrade znovu. Nový náhodný klíč by způsobil, že vše zapečetěné pod starým klíčem by zůstalo nečitelné.

Škálování

Každá komponenta má v souboru hodnot přepínač a velikost. Povinné komponenty nelze vypnout: chart je spustí bez ohledu na to, co říká jejich přepínač. Ostatním lze přidělit více replik a více prostředků.

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

Aplikujte změny pomocí helm upgrade jako výše. Velikost svazků se nastavuje pod dataTier.<store>.size; než některý zvětšíte, zkontrolujte, zda vaše třída úložiště (storage class) dokáže svazek rozšířit. Stránka Jak si instalace vede zobrazuje v grafech vytížení procesorů a paměti clusteru spolu se zbývající kapacitou v každém z nich. Navýšte to, co dochází jako první.

Balíčky pro podporu

Když Harrow potřebuje pomoc od společnosti Adverant, Tomás vytvoří balíček pro podporu:

nexusctl support-bundle --out harrow-support-4471.tar.gz

Stránka Balíček pro podporu v konzoli vytvoří tentýž soubor. Shromáždí protokoly enginů za posledních 24 hodin spolu s podrobnostmi o stavu a verzích. Nastavení se vloží bez tajných údajů (secrets) spolu se zprávami z předběžné kontroly a instalace. Než se cokoli zapíše, redigování nahradí jména a tajné údaje zástupnými symboly a vy si přečtete náhled toho, co přesně odejde. Vlastní obsah uživatelů se nikdy neshromažďuje. Balíček putuje do společnosti Adverant buď nahráním na stránku Podpora a balíčky pro podporu pod vaším účtem, nebo jako soubor přenesený na médiu. Otevřít jej mohou pouze inženýři podpory uvedení v požadavku a po 30 dnech je smazán.

Balíček pro podporu
Balíček pro podporu
Vytváření balíčku pro podporu. Náhled redigování ukazuje, co je skryto, ještě než cokoli odejde, a otevřít jej mohou pouze jmenovaní inženýři.

Export důkazních záznamů

Auditoři a váš vlastní tým pro soulad s předpisy (compliance) často vyžadují důkaz, že se platforma chová tak, jak je popsáno. Příkaz nexusctl evidence export jej vypíše:

nexusctl evidence export --out harrow-evidence-2027-01

Vedle záznamů, které exportuje, spustí příkaz akceptační sondy platformy: směrovač umělé inteligence (AI) je dosažitelný a odpovídá, úloha UNO je odeslána a dokončena a čtení napříč organizacemi je odmítnuto. Jejich výsledky jsou v souboru probes.json ve výstupní složce.

Přehled stavu

nexusctl status --json odpovídá na to, zda je instalace v pořádku a v jakém stavu je každá komponenta. Hlásí také stav licence s datem vypršení platnosti, edici a běžící vydání. Každá zkompilovaná část je vypsána se svým otiskem (digest) a podpisem. Je to příkaz, který můžete napojit na svůj vlastní monitorovací systém.

Odinstalace

nexusctl uninstall --profile <profile-file>

<profile-file> je profil nasazení pro cluster, tedy tentýž soubor, který jste předali příkazu nexusctl handoff --profile <profile-file> --out <dir>, pokud cluster provozuje váš platformní tým. Příkaz handoff pro tento tým vypíše srozumitelný seznam toho, co Nexus od clusteru potřebuje, a manifesty, které to zajistí. Odinstalace odstraní jmenné prostory systému Nexus a nic jiného, přičemž vaše zálohy ponechá. Identita instalace zaniká spolu s ní. Pozdější instalace na stejném clusteru je novou instalací s novou identitou, takže její nárokování je novým nárokováním a její licence je novou licencí.

Stránky Tato instalace

Operátoři instalace mají v nabídce svou vlastní skupinu Tato instalace a na jejích stránkách se v konzoli odehrává většina této kapitoly. Člen, který některou z nich otevře, uvidí stránku Nejste administrátor, která uvádí, kdo může jednat.

Stránka K čemu slouží
Licence a co odemyká Licence a její skupiny funkcí (kapitola 2.13, Licence)
Pokud licence vyprší Stupnice vypršení platnosti vyjádřená slovy, s daty této licence
Zkompilované části Každý licencovaný modul se svou noční kontrolou podpisu
Výkaz využití pro Adverant Roční počítadla, čitelná před odesláním
Verze a upgrady Každá nainstalovaná verze s informací, kdo a kdy ji nainstaloval
Upgrade Fázovaný upgrade a cesta zpět
Zálohování a obnova Každé úložiště, jeho poslední záloha a jeho poslední otestovaná obnova
Jak si instalace vede Uzly, kapacita a provozní náklady, včetně varování
Klíče a výmaz Klíč každé organizace a funkce Vymazat s uvedením důvodu a druhou osobou
Incidenty Otevřené a uzavřené problémy s popisem toho, co bylo provedeno
Brzy končící Funkce, které se vypínají, s daty, exportem a náhradou
Stav Každá část systému Nexus nyní a za posledních 30 dní, napsaná srozumitelně pro každého
Balíček pro podporu Co odchází do společnosti Adverant a jak

Dvě z těchto stránek si zaslouží komentář. Stránka Zkompilované části každou noc kontroluje každý licencovaný modul vůči podpisu společnosti Adverant. Změněná kopie modulu je odmítnuta a nikdy se nenačte, zatímco podepsaná kopie běží dál, a stránka počítá odmítnutí po měsících, takže upravená kopie nemůže projít bez povšimnutí. Stránka Stav je napsána tak, aby jí rozuměl kdokoli v organizaci. Zobrazuje každou část systému Nexus nyní a za posledních 30 dní jako proužek dnů s plánovanou údržbou a nedávnými incidenty a operátor ze stejné stránky přidává incident nebo okno údržby.

Instalace edice Community má jednu stránku, Tato instalace (Community), se svou verzí, stavem a aktualizacemi. Stránky edice Enterprise se na ní zobrazují jako ukázky, které uvádějí, kdo je může zapnout.