Prihlásiť saRezervovať brífing

Kapitola 2.3

Plánovanie inštalácie

Čo potrebuje inštalácia systému Nexus na Kubernetes predtým, než napíšete príkaz, aká je veľká a dve rozhodnutia, ktoré nemôžete vziať späť – názov inštalácie a správcovia kľúčov. Končí vyplneným plánovacím hárkom pre Harrow Port Authority.

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

16 min čítania

Keď sme inštalovali Nexus v Harrow Port Authority, samotné príkazy nám zabrali jedno popoludnie. Plánovanie trvalo týždeň a väčšina z tohto týždňa padla na dve otázky, ktoré nemajú nič spoločné s Kubernetes: ako inštaláciu nazveme a ktorí ľudia budú držať jej kľúče na obnovu. Obe rozhodnutia sú trvalé. Všetko ostatné v tejto kapitole možno neskôr zmeniť pomocou súboru hodnôt a príkazu helm upgrade.

Volám sa Tomás Reilly a som platformový inžinier v Harrow. Harrow prevádzkuje dve inštalácie. Táto kapitola plánuje tú pripojenú v našej firemnej sieti, kde sme najprv pilotne nasadili edíciu Community. Prevádzková sieť prístavu, ktorá nemá žiadne prepojenie s internetom, dostala vlastnú inštaláciu neskôr; venuje sa jej kapitola 2.10, Inštalácia v izolovanej sieti (air-gapped). Táto kapitola obsahuje presne to, čo by som si prial mať v rukách v prvé ráno: aký klaster Nexus očakáva, na aké názvy odpovedá, aké má nároky na vaše uzly a aké rozhodnutia musíte pred inštaláciou uzavrieť s vedúcim IT. Na záver nájdete pracovný hárok, ktorý pred začiatkom schválila Aoife Brennan, naša vedúca IT. Kapitola 2.4, Získanie a overenie vydania, sa venuje stiahnutiu a kontrole vydania a kapitola 2.5, Predinštalačná kontrola pomocou nexusctl, skontroluje váš klaster voči všetkému, čo je tu uvedené.

Čo musí mať klaster

Nexus sa inštaluje ako jeden Helm chart, nexus, verzia 1.0.0-alpha.1. Tento chart obsahuje platformové služby a ich dátovú vrstvu a odmietne sa nainštalovať na klaster, ktorému chýbajú nižšie uvedené súčasti.

Požiadavka Čo Nexus očakáva Prečo
Kubernetes 1.33 alebo novší. Testované na k3s v1.33.6+k3s1 Hodnota kubeVersion v charte je >=1.33.0-0 a helm install ju vynucuje
cert-manager v1.21.3, nainštalovaný pred systémom Nexus Chart si vytvára vlastnú lokálnu certifikačnú autoritu (CA) a certifikáty, ktoré jeho služby používajú na vzájomnú komunikáciu
Helm v4 (my sme použili v4.3.1) Helm 4 predvolene čaká na dokončenie úloh (hook Jobs) chartu, od čoho závisí inštalácia
Trieda úložiska (StorageClass) Jedna označená ako predvolená (default), alebo tá, ktorú uvediete v storage.className Každé dátové úložisko si nárokuje trvalý zväzok (Persistent Volume)
Trieda ingressu (IngressClass) Jedna označená ako predvolená (default), alebo tá, ktorú uvediete v ingress.className Tri verejné adresy sú štandardné networking.k8s.io/v1 objekty Ingress
Porty 80 a 443 Otvorené na ingress kontroléri, ako služba typu LoadBalancer alebo NodePort Používatelia pristupujú k systému Nexus cez ingress kontrolér
Architektúra Uzly linux/amd64 alebo linux/arm64 Každý obraz je zostavený pre obe architektúry

Dve veci v tejto tabuľke chýbajú zámerne. Nexus nepotrebuje žiadny service mesh: vzájomné TLS (mTLS, Transport Layer Security v oboch smeroch) medzi službami zabezpečuje lokálna CA chartu prostredníctvom nástroja cert-manager. Chart obsahuje kľúč istio.enabled, ktorý je predvolene nastavený na false, a tak by ste ho mali aj ponechať. Nexus taktiež nepotrebuje žiadny vlastný nástroj na riadenie politík prijímania (admission policy engine).

Na svojej pracovnej stanici budete potrebovať kubectl, Helm v4, cosign v3 na kontrolu podpisov, age na vytváranie kľúčov opatrovníkov a nexusctl, čo je rozhranie príkazového riadka (CLI) pre operátora systému Nexus. Kapitola 2.4, Získanie a overenie vydania, uvádza, kde sa nachádzajú jednotlivé súbory systému Nexus na stiahnutie.

Tri adresy

Každá inštalácia odpovedá na troch názvoch hostiteľov. Chart ich nazýva identitou inštalácie a bez nich sa odmietne spustiť akákoľvek služba.

Kľúč v súbore hodnôt Názov v Harrow Čo na ňom odpovedá
hosts.console console.harrow.example Konzola, webová aplikácia, do ktorej sa ľudia prihlasujú
hosts.api api.harrow.example Brána (gateway), ktorá poskytuje aplikačné programovacie rozhranie (API) a smeruje každú požiadavku umelej inteligencie (AI)
hosts.auth auth.harrow.example Prihlasovacia služba, nexus-auth

global.domain uchováva doménu, pod ktorou sa tieto tri názvy nachádzajú – v našom prípade harrow.example. Každý hostiteľ je samostatným plným názvom a môže sa nachádzať pod akoukoľvek doménou, ktorú máte pod kontrolou. My sme ponechali všetky tri pod jednou doménou, pretože ich tak mohol pokryť jeden certifikát.

Vytvorte záznam v systéme doménových mien (DNS) pre každý z týchto troch názvov tak, aby smeroval na adresu vášho ingress kontroléra. Urobte to pred predinštalačnou kontrolou (preflight). Príkaz nexusctl preflight vyhľadá každý názov z vašej pracovnej stanice a zruší inštaláciu, ak pre niektorý z nich záznam neexistuje, pretože používateľ sa nedokáže pripojiť k názvu, ktorý sa nedá preložiť na adresu.

Vľavo sú tri názvy DNS: console.harrow.example, api.harrow.example a auth.harrow.example, pričom z každého vedie šípka do jedného poľa s označením „ingress controller, ports 80 and 443“. Z tohto poľa vedú tri šípky do väčšieho poľa s označením „namespace nexus“: šípka pre console do „nexus-alpha :3000“, šípka pre api do „nexus-gateway :9092“ a šípka pre auth do „nexus-auth :9101“. Prerušovaný okraj okolo menného priestoru má označenie „default deny; only the ingress namespace may reach these three“.
Ako sa tri verejné názvy dostanú k službám za nimi.

Výber spôsobu ukončenia TLS

Hodnota tls.mode v charte rozhoduje o tom, kto spravuje certifikáty pre tri verejné adresy. Existujú tri možnosti a neskôr medzi nimi môžete prepínať pomocou aktualizácie (upgrade).

tls.mode Vy poskytnete Čo urobí chart
existing (predvolené) Kubernetes TLS Secret v mennom priestore nexus, pomenovaný v tls.existingSecret Všetky tri objekty Ingress používajú tento jeden Secret
cert-manager ClusterIssuer, ktorý prevádzkujete, pomenovaný v tls.clusterIssuer Pridá anotácie ku každému objektu Ingress, aby cert-manager vydal nexus-console-tls, nexus-api-tls a nexus-auth-tls
none Prvok pred klastrom, ktorý ukončuje TLS, napríklad váš vlastný load balancer Vygeneruje objekty Ingress bez sekcie TLS

Pri možnosti existing jeden certifikát obsluhuje všetkých troch hostiteľov, takže musí obsahovať všetky tri názvy – buď ako tri alternatívne názvy subjektu (SAN), alebo ako hviezdičkový (wildcard) certifikát pre vašu doménu. My sme použili certifikát z internej CA organizácie Harrow. Predinštalačná kontrola prečíta tento Secret pred inštaláciou a upozorní vás, ak platnosť certifikátu vyprší do 30 dní.

Pri možnosti cert-manager a vydavateľovi využívajúcom protokol ACME (Automatic Certificate Management Environment) chart nepridáva žiadne vlastné presmerovanie, takže požiadavka /.well-known/acme-challenge/ na porte 80 dorazí k riešiteľu (solver) nezmenená. Nepridávajte na svojom ingress kontroléri presmerovanie z HTTP na HTTPS, ktoré by sa vykonalo pred cestou pre overovaciu výzvu (challenge path); certifikát, ktorý sa nedokáže obnoviť, o niekoľko týždňov neskôr potichu zlyhá.

Nech už si pre verejný okraj siete zvolíte čokoľvek, služby vnútri menného priestoru vždy komunikujú cez TLS z lokálnej CA chartu. Táto časť nie je voliteľná, a práve preto je cert-manager nevyhnutnou požiadavkou aj vtedy, keď je tls.mode nastavené na existing alebo none.

Čo opúšťa klaster a čo nie

Chart vygeneruje pre menný priestor nexus sieťovú politiku predvoleného zamietnutia (default-deny). Následne sú povolené iba tieto dátové toky:

  • prevádzka medzi podmi systému Nexus vnútri menného priestoru;
  • dotazy DNS na službu DNS klastra;
  • API server Kubernetes pre niekoľko služieb, ktoré overujú tokeny pracovných záťaží (workload tokens);
  • menný priestor ingress kontroléra smerom k trom verejným službám (Services);
  • akékoľvek rozsahy CIDR (Classless Inter-Domain Routing), ktoré uvediete v networkPolicy.externalEgressCIDRs.

Posledný menovaný zoznam je predvolene prázdny. Ak budete používať poštový relé server (mail relay) alebo server modelov mimo klastra, jeho rozsah patrí práve sem. Telemetria je vypnutá a aj zostane vypnutá: schéma akceptuje iba hodnotu telemetry.enabled: false a vlastné hlásenie o používaní dátových úložísk je taktiež vypnuté.

Chart si pri inštalácii prečíta adresy API servera priamo z klastra. Ak váš účet nemá oprávnenie čítať objekt Endpoints kubernetes v mennom priestore default, zadajte ich sami v networkPolicy.apiServerCIDRs ako rozsahy /32. Premenná proxy.trustedCIDRs určuje sieť podov, v ktorej sa nachádza váš ingress kontrolér, aby služba nexus-auth vedela, koho hlavičke X-Forwarded-For má dôverovať. Predvolená hodnota 10.42.0.0/16 je sieť podov systému k3s.

Dimenzovanie

Predvolené požiadavky (requests) chartu predstavujú spolu približne 2,05 jadra centrálnej procesorovej jednotky (CPU) a 6,7 GiB pamäte. To je objem, ktorý rezervuje plánovač (scheduler); limity sú vyššie a dátové úložiská do nich postupne dorastajú, ako pridávate používateľov a súbory.

Časť Požadované CPU Požadovaná pamäť
Deväť platformových služieb (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1,1 jadra 2,6 GiB
Služba kľúčov, nexus-keys 0,05 jadra 64 MiB
PostgreSQL 0,25 jadra 1 GiB
Neo4j 0,25 jadra 2 GiB
Valkey, Qdrant a objektové úložisko spolu 0,25 jadra 640 MiB
Dva servery OpenBao úložiska kľúčov 0,15 jadra 384 MiB

Predvolené zväzky predstavujú spolu 142 GiB:

Úložisko Kľúč v súbore hodnôt Predvolená veľkosť
PostgreSQL 16 s PostGIS 3 a pgvector 0.8 dataTier.postgres.size 50Gi
Objektové úložisko (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Úložisko kľúčov a jeho odomykač (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi a 1Gi
Potvrdenia služby kľúčov keys.receiptsStorage 1Gi

Pre jeden uzol počítajte s 8 vCPU, 32 GiB operačnej pamäte (RAM) a 250 GB jednotkou SSD (solid-state drive). Na testovacie účely postačia 4 vCPU, 16 GiB a 200 GB. Obraz inštalačného disku odmietne stroj s menej ako 16 GiB pamäte (pozri kapitolu 2.9, Obraz inštalačného disku) a túto hodnotu by som považoval za absolútne minimum všade.

Grafické uzly sú voliteľné. Bez uzla, ktorý ponúka grafickú procesorovú jednotku (GPU), asistent odpovedá prostredníctvom hostovaného modelu s použitím vlastného kľúča organizácie. Predinštalačná kontrola to hlási ako varovanie, nikdy nie ako chybu. Kapitola 2.14, Poskytovatelia a modely AI, sa venuje obom možnostiam.

Každé úložisko môže bežať aj mimo klastra: nastavte dataTier.<store>.mode na external a uveďte jeho hostiteľa a Secret. Externý PostgreSQL potrebuje účet superpoužívateľa pre úvodnú inicializáciu (bootstrap) pri inštalácii a certifikát, ktorý dokáže Nexus overiť. Tejto téme sa venuje kapitola 2.11, Variácie: externé úložiská, TLS a ingress. Ak ich ponecháte v klastri, umiestnite ich na triedu úložiska, za ktorou sú skutočné disky. Databáza je presne tá časť, ktorá vám bude chýbať najviac, ak zlyhá lokálny disk uzla.

Názov inštalácie je trvalý

keys.installationName je názov, ktorým operátori označujú túto inštaláciu. Musí zodpovedať výrazu ^[a-z][a-z0-9-]{0,62}$: malé písmeno, za ktorým nasleduje až 62 malých písmen, číslic alebo spojovníkov.

Keď sa úložisko kľúčov spustí prvýkrát, vytvorí identitu inštalácie pod týmto názvom a táto identita je už natrvalo nemenná. Licencia od spoločnosti Adverant sa vydáva pre túto identitu, takže licencia vytvorená pre jednu inštaláciu bude na inej odmietnutá s chybou LICENCE_OTHER_INSTALLATION. Premenovanie by znamenalo novú inštaláciu, novú identitu a nové licencie.

Chart nemá pre tento názov žiadnu predvolenú hodnotu. Odmietne inštaláciu bez názvu (INSTALLATION_NAME_MISSING) a odmietne aj vzorový názov zo svojich vlastných príkladov súborov hodnôt (INSTALLATION_NAME_EXAMPLE). Predinštalačná kontrola nahlási oba prípady skôr, než sa k samotnej inštalácii vôbec dostanete.

V Harrow sme nad tým strávili viac času, než by som si chcel priznať. Nakoniec sme sa zhodli na harrow-port-authority: pomenúva organizáciu, nehovorí nič o tom, na ktorom klastri beží, a bude platiť aj po výmene hardvéru. Vyhnite sa názvom ako prod-k3s-2, ktoré opisujú dnešné stroje.

Úschova kľúčov

Nexus uchováva kľúče každej organizácie vo svojom vlastnom úložisku kľúčov vnútri klastra. Nemusíte ho každodenne obsluhovať, ale pred inštaláciou musíte rozhodnúť, kto ho dokáže opäť spojazdniť po reštarte. Toto je rozhodnutie, ktoré vás bude stáť najviac, ak ho urobíte nesprávne.

Úložisko kľúčov tvoria dva servery OpenBao. Hlavný server, openbao, uchováva kľúče a sám sa odomyká prostredníctvom druhého, menšieho servera, openbao-unsealer. Tento odomykač (unsealer) je uzamknutý pomocou Shamirovej schémy: päť častí (shares), z ktorých ľubovoľné tri ho otvoria. Pri inštalácii úloha správy kľúčov (custody Job) inicializuje oba servery vnútri klastra. V pamäti tejto úlohy zašifruje časti odomykača a kľúče na obnovu úložiska kľúčov pre každého opatrovníka (custodian), ktorého uvediete, uloží iba šifrovaný text (v objektoch Secret openbao-unseal-shares-encrypted a openbao-recovery-keys-encrypted) a pred svojím ukončením zneplatní oba koreňové (root) tokeny. Žiadna nezašifrovaná časť sa nikdy nedostane na disk ani do záznamov (logov).

Po akomkoľvek reštarte uzla odomykača sa odomykač spustí v uzamknutom stave. Úložisko kľúčov naň čaká a nič, čo vyžaduje kľúč, nefunguje, kým ho opatrovník neodomkne. To si vyžaduje jedno dešifrovanie pomocou vlastného súkromného kľúča opatrovníka. Postup je opísaný v kapitole 2.15, Druhý deň: prevádzka systému Nexus.

Vytvorenie kľúča opatrovníka

Opatrovník je definovaný verejnou polovicou kľúča age, ktorá sa nazýva príjemca (recipient). Každý opatrovník si vytvorí svoj vlastný kľúč na svojom vlastnom zariadení a vám odovzdá iba príjemcu:

age-keygen -o custodian.key

Riadok # public key: v súbore predstavuje príjemcu a začína sa reťazcom age1. Opatrovník s počítačom Mac môže namiesto toho uchovávať kľúč v čipe Secure Enclave počítača Mac, takže súkromná polovica nikdy neopustí čip a každé použitie si vyžiada odtlačok prsta:

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

Tento príjemca sa začína reťazcom age1se1. Úloha správy kľúčov šifruje pre päť foriem príjemcov: age1 (X25519), age1tag1 a age1tagpq1 (tag), age1pq1 (hybridný post-kvantový) a age1se1 (Secure Enclave). Odmietne akúkoľvek inú formu zásuvného modulu, ako je napríklad age1yubikey1; takýto kľúč namiesto toho uveďte v jednej z akceptovaných foriem.

Chart pri generovaní skontroluje každého príjemcu. Príjemca s preklepom neprejde kontrolným súčtom bech32 a je odmietnutý, takže sa nikdy nič neuzamkne kľúčom, ktorý nikto nevlastní. Ak niekto do zoznamu omylom vloží súkromný kľúč, chart ho odmietne bez toho, aby ho vypísal späť na výstup. Vzorový príjemca vo vlastných súboroch hodnôt chartu je taktiež odmietnutý (KEYS_CUSTODIAN_EXAMPLE); jeho súkromnú polovicu totiž nikto nevlastní.

Koľko opatrovníkov zvoliť

Každá časť je zašifrovaná pre každého opatrovníka, takže odomknutie dokáže vykonať ktorýkoľvek opatrovník samostatne. Viac opatrovníkov znamená viac spôsobov obnovy a viac ľudí, z ktorých každý môže konať samostatne. V Harrow sme zvolili troch: Aoife, mňa a kľúč Secure Enclave na záložnom notebooku, ktorý je uložený v trezore prístavu. Dvaja sú absolútne minimum, ktoré by som akceptoval. Jeden predstavuje jediný bod zlyhania (single point of failure), ktorý bude skôr či neskôr práve na dovolenke, keď sa uzol reštartuje.

Výber edície

Hodnota edition je buď community, alebo enterprise a enterprise.enabled sa s ňou musí zhodovať. Chart odmietne nezhodu a odmietne akúkoľvek edíciu, ktorá nie je jednou z týchto dvoch.

Edícia tiež rozhoduje o tom, ktoré obrazy nainštalujete. Každý balík chartu obsahuje zámok obrazov (images lock) – zoznam všetkých obrazov podľa ich kontrolného súčtu (digest) pre jednu edíciu. Inštalácia Community využíva iba obrazy Community. Inštalácia Enterprise využíva zámok Enterprise, čo sú obrazy Community plus zostavy Enterprise, a sťahuje ich pomocou sťahovacieho tokenu (pull token) z vášho účtu Adverant. Kapitola 2.4, Získanie a overenie vydania, vysvetľuje fungovanie zámku a kapitola 2.2, Edície pod kapotou, vysvetľuje, čo jednotlivé edície obsahujú.

Nemusíte sa rozhodnúť natrvalo. Inštalácia Community sa dá na mieste previesť na Enterprise, pričom si zachová používateľov, súbory aj históriu; kapitola 2.7, Inštalácia edície Enterprise a použitie licencie, ukazuje, ako na to. V Harrow sme počas pilotnej fázy prevádzkovali edíciu Community a o šesť týždňov neskôr sme prešli na Enterprise.

Licencia nikdy nie je súčasťou tohto plánu. Nie je to hodnota v charte ani pripojený súbor: importujete ju až po inštalácii prostredníctvom konzoly, nástroja nexusctl alebo cez API.

Výber formy dodania

Forma Kedy je vhodná Kapitola
Helm chart z registry.adverant.ai Váš vlastný klaster Kubernetes so spojením do registra 2.6 a 2.7
nexusctl install Ten istý klaster, pričom predinštalačná kontrola a kontrola podpisu sa vykonajú za vás 2.6
nexusctl install --single-node Jeden stroj, kde nexusctl nastaví aj samotný klaster 2.8
Obraz inštalačného disku Čistý (bare-metal) server alebo virtuálny stroj (VM), ktorý radšej nechcete pripravovať ručne 2.9
Offline balík Žiadne spojenie s vonkajšou sieťou; obrazy a chart sa dodávajú na disku 2.10

Chart je v každej forme rovnaký. Mení sa len to, kto vytvára klaster a odkiaľ pochádzajú obrazy.

Získať vydanie
Získať vydanie
Toto je stránka vydania v účte Adverant. Všimnite si jasné vyhlásenie o tom, čo alfa vydanie sľubuje, veľkosť a podpis vedľa každého súboru a offline príkazy na kontrolu stiahnutých súborov.

Plánovací hárok

Toto je hárok z Harrow, ako ho schválila Aoife. Skopírujte ľavé dva stĺpce a pravý vyplňte pre svoju vlastnú inštaláciu.

Rozhodnutie Kľúč hodnôt alebo príkaz Harrow Port Authority
Kubernetes a verzia (načíta predinštalačná kontrola) k3s v1.33.6+k3s1, tri uzly
Kube kontext pre inštaláciu --context harrow-prod
Menný priestor (Namespace) --namespace nexus
Edícia edition, enterprise.enabled community pre pilotnú fázu, potom enterprise
Register obrazov global.imageRegistry registry.adverant.ai
Doména global.domain harrow.example
Adresa konzoly hosts.console console.harrow.example
Adresa API hosts.api api.harrow.example
Adresa na prihlásenie hosts.auth auth.harrow.example
TLS na okraji siete tls.mode, tls.existingSecret existing, Secret harrow-public-tls z internej CA organizácie Harrow
Trieda ingressu (IngressClass) ingress.className traefik
Menný priestor ingressu networkPolicy.ingressNamespace kube-system
Trieda úložiska (StorageClass) storage.className local-path
Dátové úložiská dataTier.<store>.mode Všetky in-cluster, predvolené veľkosti
Odchádzajúce rozsahy networkPolicy.externalEgressCIDRs Iba rozsah poštového relé servera
Názov inštalácie (trvalý) keys.installationName harrow-port-authority
Opatrovníci (v praxi trvalí) keys.custody.recipients Traja: Aoife Brennan, Tomás Reilly, notebook v trezore (age1se1)
Grafické uzly (načíta predinštalačná kontrola) Žiadne pre pripojenú pilotnú fázu; hostovaný model s vlastným kľúčom organizácie Harrow
Prvý správca (administrátor) nexusctl claim-code --administrator aoife.brennan@harrow.example

Dva riadky v tomto hárku sa nedajú vrátiť späť: názov inštalácie a opatrovníci v tom zmysle, že strata všetkých opatrovníkov znamená stratu úložiska kľúčov. Nechajte si tieto dve položky písomne schváliť niekým, kto má právomoc povedať áno. Všetko ostatné je len zmena v súbore hodnôt.

Keď máte pracovný hárok hotový, prejdite na kapitolu 2.4, Získanie a overenie vydania, a stiahnite si vydanie.