Verzia 1.0.0-alpha.1najnovšia
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

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ý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.keyRiadok # 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.keyTento 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.
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.
