Verze 1.0.0-alpha.1nejnovější
Kapitola 2.3
Plánování instalace
Co instalace systému Nexus v prostředí Kubernetes potřebuje, než zadáte příkaz, jak je velká, a dvě rozhodnutí, která nelze vzít zpět: název instalace a správci klíčů. Končí vyplněným plánovacím pracovním listem organizace Harrow Port Authority.
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ě

Když jsme instalovali Nexus v Harrow Port Authority, samotné příkazy zabraly jedno odpoledne. Plánování trvalo týden a většina toho týdne padla na dvě otázky, které nemají nic společného s Kubernetes: jak instalaci pojmenujeme a kteří lidé budou držet její klíče pro obnovu. Obě odpovědi jsou trvalé. Všechno ostatní v této kapitole lze změnit později pomocí souboru hodnot a helm upgrade.
Jsem Tomás Reilly, platformní inženýr v Harrow. Harrow provozuje dvě instalace. Tato kapitola plánuje tu připojenou v naší podnikové síti, kde jsme nejprve pilotně nasadili edici Community. Provozní síť přístavu, která nemá žádnou trasu do internetu, dostala vlastní instalaci později; věnuje se jí kapitola 2.10, Instalace v izolované síti (air-gapped). Tato kapitola je tím, co bych si přál mít k dispozici první ráno: jaký cluster Nexus očekává, na jaká jména slyší, kolik toho žádá od vašich uzlů a jaká rozhodnutí je třeba uzavřít s vaším ředitelem IT před instalací. Končí pracovním listem, který Aoife Brennan, naše ředitelka IT, schválila předtím, než jsme začali. Kapitola 2.4, Získání a ověření vydání, popisuje stažení a kontrolu vydání a kapitola 2.5, Předletová kontrola s nexusctl, zkontroluje váš cluster oproti všemu, co je uvedeno zde.
Co musí cluster mít
Nexus se instaluje jako jeden Helm chart, nexus, verze 1.0.0-alpha.1. Tento chart nese platformní služby i jejich datovou vrstvu a odmítne se nainstalovat na cluster, kterému chybí níže uvedené součásti.
| Požadavek | Co Nexus očekává | Proč |
|---|---|---|
| Kubernetes | 1.33 nebo novější. Testováno na k3s v1.33.6+k3s1 |
Hodnota kubeVersion v chartu je >=1.33.0-0 a helm install ji vynucuje |
| cert-manager | v1.21.3, nainstalovaný před Nexusem |
Chart vytváří vlastní lokální certifikační autoritu (CA) a certifikáty, které jeho služby používají ke vzájemné komunikaci |
| Helm | v4 (my jsme použili v4.3.1) | Helm 4 ve výchozím nastavení čeká na dokončení hook Jobů chartu, na čemž instalace závisí |
| Třída úložiště (StorageClass) | Jedna označená jako výchozí, nebo taková, kterou uvedete v storage.className |
Každé datové úložiště si nárokuje perzistentní svazek |
| Třída ingressu (IngressClass) | Jedna označená jako výchozí, nebo taková, kterou uvedete v ingress.className |
Tři veřejné adresy jsou běžné objekty Ingress networking.k8s.io/v1 |
| Porty 80 a 443 | Otevřené na ingress controlleru, jako služba typu LoadBalancer nebo NodePort | Lidé přistupují k Nexusu přes ingress controller |
| Architektura | Uzly linux/amd64 nebo linux/arm64 |
Každý obraz je sestaven pro obě architektury |
Dvě věci v této tabulce chybí záměrně. Nexus nepotřebuje žádnou service mesh: obousměrné TLS (mTLS, Transport Layer Security v obou směrech) mezi službami pochází z lokální CA chartu prostřednictvím nástroje cert-manager. Chart má klíč istio.enabled, který má výchozí hodnotu false, a na té byste jej měli ponechat. Nexus také nepotřebuje žádný vlastní systém pro vyhodnocování přístupových politik (admission policy engine).
Na své pracovní stanici budete potřebovat kubectl, Helm v4, cosign v3 pro kontrolu podpisů, age pro vytváření klíčů správců klíčů (custodians) a nexusctl, rozhraní příkazového řádku (CLI) operátora systému Nexus. Kapitola 2.4, Získání a ověření vydání, uvádí, kde se jednotlivé soubory ke stažení pro Nexus nacházejí.
Tři adresy
Každá instalace odpovídá na třech názvech hostitelů. Chart je nazývá identitou instalace a bez nich se každá služba odmítne spustit.
| Klíč v souboru hodnot | Název v Harrow | Co zde odpovídá |
|---|---|---|
hosts.console |
console.harrow.example |
Konzole, webová aplikace, do které se lidé přihlašují |
hosts.api |
api.harrow.example |
Brána (gateway), která obsluhuje aplikační programové rozhraní (API) a směruje každý požadavek na umělou inteligenci (AI) |
hosts.auth |
auth.harrow.example |
Přihlašovací služba, nexus-auth |
global.domain uchovává doménu, pod kterou tyto tři názvy spadají, v našem případě harrow.example. Každý hostitel je plnohodnotným názvem sám o sobě a může spadat pod jakoukoli doménu, kterou ovládáte. My jsme ponechali všechny tři pod jednou doménou, protože je pak mohl pokrýt jeden certifikát.
Vytvořte pro každý z těchto tří názvů záznam v systému doménových jmen (DNS), který bude směřovat na adresu vašeho ingress controlleru. Udělejte to před předletovou kontrolou (preflight). nexusctl preflight vyhledá každý název z vaší pracovní stanice a ukončí instalaci chybou, pokud některý z nich nemá záznam, protože uživatel se nedostane na název, který nelze přeložit.
Volba způsobu ukončení TLS
Hodnota tls.mode v chartu rozhoduje o tom, kdo drží certifikáty pro tři veřejné adresy. Existují tři možnosti a později mezi nimi můžete přepínat pomocí upgradu.
tls.mode |
Vy poskytnete | Co udělá chart |
|---|---|---|
existing (výchozí) |
Kubernetes TLS Secret ve jmenném prostoru nexus, pojmenovaný v tls.existingSecret |
Všechny tři objekty Ingress použijí tento jeden Secret |
cert-manager |
ClusterIssuer, který provozujete, pojmenovaný v tls.clusterIssuer |
Opatří každý Ingress anotací, aby cert-manager vydal nexus-console-tls, nexus-api-tls a nexus-auth-tls |
none |
Něco před clusterem, co ukončuje TLS, například váš vlastní load balancer | Vygeneruje objekty Ingress bez sekce TLS |
Při použití existing obsluhuje jeden certifikát všechny tři hostitele, takže musí obsahovat názvy všech tří – buď jako tři alternativní názvy subjektu (SAN), nebo jako hvězdičkový (wildcard) certifikát pro vaši doménu. My jsme použili certifikát z interní CA v Harrow. Předletová kontrola přečte Secret před instalací a upozorní vás, pokud platnost jeho certifikátu končí do 30 dnů.
Při použití cert-manager a vydavatele typu Automatic Certificate Management Environment (ACME) nepřidává chart žádné vlastní přesměrování, takže požadavek /.well-known/acme-challenge/ na portu 80 dorazí k řešiteli (solver) nedotčený. Nepřidávejte na svém ingress controlleru přesměrování z HTTP na HTTPS, které by se spustilo před cestou výzvy (challenge path); certifikát, který se nemůže obnovit, selže tiše o týdny později.
Ať už pro veřejný okraj sítě zvolíte cokoli, služby uvnitř jmenného prostoru vždy komunikují přes TLS z lokální CA chartu. Tato část není volitelná, a právě proto je cert-manager předpokladem i tehdy, když je tls.mode nastaveno na existing nebo none.
Co opouští cluster a co ne
Chart vygeneruje pro jmenný prostor nexus síťovou politiku výchozího zamítnutí (default-deny). Poté jsou povoleny pouze tyto toky:
- provoz mezi pody Nexusu uvnitř jmenného prostoru;
- dotazy DNS na službu DNS clusteru;
- API server Kubernetes, pro několik služeb, které ověřují tokeny úloh (workload tokens);
- jmenný prostor ingress controlleru směrem ke třem veřejným službám (Services);
- jakékoli rozsahy Classless Inter-Domain Routing (CIDR), které uvedete v
networkPolicy.externalEgressCIDRs.
Tento poslední seznam je ve výchozím nastavení prázdný. Pokud budete používat poštovní relé (mail relay) nebo modelový server mimo cluster, přijde sem jeho rozsah. Telemetrie je vypnutá a zůstává vypnutá: schéma přijímá pouze telemetry.enabled: false a vlastní hlášení o využití datových úložišť je rovněž vypnuto.
Chart při instalaci načte adresy API serveru z clusteru. Pokud váš účet nemůže číst objekty Endpoints kubernetes ve jmenném prostoru default, zadejte je sami v networkPolicy.apiServerCIDRs jako rozsahy /32. proxy.trustedCIDRs určuje síť podů, ve které se nachází váš ingress controller, aby nexus-auth věděl, čí hlavičce X-Forwarded-For má důvěřovat. Výchozí hodnota, 10.42.0.0/16, je síť podů v k3s.
Dimenzování
Výchozí požadavky (requests) chartu dávají v součtu přibližně 2.05 jádra centrální procesorové jednotky (CPU) a 6.7 GiB paměti. To je hodnota, kterou rezervuje plánovač (scheduler); limity jsou vyšší a datová úložiště do nich dorůstají, jak přidáváte lidi a soubory.
| Část | Požadované CPU | Požadovaná paměť |
|---|---|---|
| Devět platformních služeb (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) | 1.1 jádra | 2.6 GiB |
Služba pro správu klíčů, nexus-keys |
0.05 jádra | 64 MiB |
| PostgreSQL | 0.25 jádra | 1 GiB |
| Neo4j | 0.25 jádra | 2 GiB |
| Valkey, Qdrant a objektové úložiště dohromady | 0.25 jádra | 640 MiB |
| Dva servery OpenBao úložiště klíčů | 0.15 jádra | 384 MiB |
Výchozí svazky dávají v součtu 142 GiB:
| Úložiště | Klíč v souboru hodnot | Výchozí velikost |
|---|---|---|
| PostgreSQL 16 s PostGIS 3 a pgvector 0.8 | dataTier.postgres.size |
50Gi |
| Objektové úložiště (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žiště klíčů a jeho odemykací služba (unsealer) | keys.openbao.storage.keystore, keys.openbao.storage.unsealer |
5Gi a 1Gi |
| Potvrzení služby pro správu klíčů | keys.receiptsStorage |
1Gi |
Pro jeden uzel počítejte s 8 vCPU, 32 GiB paměti s přímým přístupem (RAM) a 250 GB jednotkou SSD (solid-state drive). Pro zkušební provoz postačí 4 vCPU, 16 GiB a 200 GB. Obraz instalačního disku odmítne stroj s méně než 16 GiB paměti (viz kapitola 2.9, Obraz instalačního disku) a já bych to bral jako spodní hranici všude.
Grafické uzly jsou volitelné. Bez uzlu, který nabízí grafický procesor (GPU), odpovídá asistent prostřednictvím hostovaného modelu s využitím vlastního klíče organizace. Předletová kontrola to hlásí jako varování, nikoli jako selhání. Kapitola 2.14, Poskytovatelé a modely AI, popisuje obě cesty.
Každé úložiště může běžet také mimo cluster: nastavte dataTier.<store>.mode na external a zadejte jeho hostitele a Secret. Externí PostgreSQL potřebuje účet superuživatele pro úvodní zavedení (bootstrap) instalace a certifikát, který může Nexus ověřit. Tomu se věnuje kapitola 2.11, Varianty: externí úložiště, TLS a ingress. Pokud je ponecháte v clusteru, umístěte je na třídu úložiště, za kterou stojí skutečné disky. Databáze je tou částí, kterou budete postrádat nejvíce, pokud odejde lokální disk uzlu.
Název instalace je trvalý
keys.installationName je název, kterým operátoři označují tuto instalaci. Musí odpovídat výrazu ^[a-z][a-z0-9-]{0,62}$: malé písmeno a poté až 62 malých písmen, číslic nebo spojovníků.
Při prvním spuštění úložiště klíčů vytvoří identitu instalace pod tímto názvem a tato identita je již natrvalo neměnná. Licence od společnosti Adverant se vydává pro tuto identitu, takže licence vytvořená pro jednu instalaci je na jiné odmítnuta s chybou LICENCE_OTHER_INSTALLATION. Přejmenování by znamenalo novou instalaci, novou identitu a nové licence.
Chart nemá pro název žádnou výchozí hodnotu. Odmítne instalaci bez názvu (INSTALLATION_NAME_MISSING) a odmítne také ukázkový název ze svých vlastních vzorových souborů hodnot (INSTALLATION_NAME_EXAMPLE). Předletová kontrola nahlásí obojí dříve, než se do této fáze dostanete.
V Harrow jsme nad tím strávili více času, než bych rád přiznal. Nakonec jsme se shodli na harrow-port-authority: pojmenovává organizaci, neříká nic o tom, na kterém clusteru běží, a bude platit i tehdy, až se vymění hardware. Vyhněte se názvům jako prod-k3s-2, které popisují dnešní stroje.
Správa klíčů
Nexus uchovává klíče každé organizace ve svém vlastním úložišti klíčů uvnitř clusteru. Běžně jej neobsluhujete, ale před instalací rozhodujete o tom, kdo jej dokáže po restartu znovu zprovoznit. Toto je rozhodnutí, které vás v případě chyby přijde nejdráže.
Úložiště klíčů tvoří dva servery OpenBao. Hlavní z nich, openbao, uchovává klíče a odemyká se (unseals) prostřednictvím druhého, menšího serveru, openbao-unsealer. Odemykací server (unsealer) je uzamčen (sealed) pomocí Šamirova schématu: pět podílů, přičemž libovolné tři z nich jej otevřou. Při instalaci inicializuje oba servery uvnitř clusteru úloha správy klíčů (custody Job). V paměti tohoto Jobu zašifruje podíly odemykacího serveru a klíče pro obnovu úložiště klíčů pro každého správce klíčů (custodian), kterého uvedete, uloží pouze šifrovaný text (v objektech Secret openbao-unseal-shares-encrypted a openbao-recovery-keys-encrypted) a před svým dokončením zneplatní oba kořenové (root) tokeny. Žádný nešifrovaný podíl se nikdy nedostane na disk ani do protokolu (logu).
Po jakémkoli restartu uzlu odemykacího serveru se tento server spustí uzamčený. Úložiště klíčů na něj čeká a nic, co potřebuje klíč, nefunguje, dokud jej některý ze správců klíčů neodemkne. To vyžaduje jedno dešifrování pomocí vlastního soukromého klíče správce. Postup je uveden v kapitole 2.15, Druhý den: provoz systému Nexus.
Vytvoření klíče správce
Správce klíčů je určen veřejnou polovinou klíče age, která se nazývá příjemce (recipient). Každý správce si vytvoří svůj vlastní klíč na svém vlastním stroji a vám předá pouze příjemce:
age-keygen -o custodian.keyŘádek # public key: v souboru představuje příjemce a začíná na age1. Správce s počítačem Mac může místo toho uchovávat klíč v čipu Secure Enclave počítače Mac, takže soukromá polovina nikdy neopustí čip a každé použití vyžaduje otisk prstu:
age-plugin-se keygen --access-control=any-biometry -o custodian.keyTento příjemce začíná na age1se1. Úloha správy klíčů (custody Job) šifruje pro pět forem příjemců: age1 (X25519), age1tag1 a age1tagpq1 (tag), age1pq1 (hybridní postkvantové) a age1se1 (Secure Enclave). Odmítá jakoukoli jinou formu zásuvného modulu, například age1yubikey1; takový klíč uveďte místo toho v jedné z přijímaných forem.
Chart při generování zkontroluje každého příjemce. Překlep v příjemci neprojde kontrolním součtem bech32 a je odmítnut, takže se nikdy nic neuzamkne klíčem, který nikdo nedrží. Pokud někdo do seznamu omylem vloží soukromý klíč, chart jej odmítne, aniž by jej vypsal zpět na výstup. Ukázkový příjemce z vlastních souborů hodnot chartu je rovněž odmítnut (KEYS_CUSTODIAN_EXAMPLE); jeho soukromou polovinu nikdo nedrží.
Kolik správců klíčů
Každý podíl je zašifrován pro každého správce klíčů, takže odemknutí může provést kterýkoli jednotlivý správce samostatně. Více správců znamená více způsobů obnovy a více lidí, z nichž každý může jednat samostatně. V Harrow jsme zvolili tři: Aoife, mě a klíč Secure Enclave na záložním notebooku, který je uložen v přístavním trezoru. Dva jsou minimum, které bych akceptoval. Jeden představuje jediné místo selhání (single point of failure), které bude dříve či později na dovolené, až se uzel restartuje.
Volba edice
edition je community nebo enterprise a enterprise.enabled s tím musí souhlasit. Chart odmítne neshodu a odmítne jakoukoli edici, která není jednou z těchto dvou.
Edice také rozhoduje o tom, které obrazy nainstalujete. Každý balíček chartu obsahuje zámek obrazů (images lock), což je seznam všech obrazů podle otisku (digest) pro jednu edici. Instalace Community využívá pouze obrazy Community. Instalace Enterprise využívá zámek Enterprise, což jsou obrazy Community plus sestavení Enterprise, a stahuje je pomocí stahovacího tokenu (pull token) z vašeho účtu Adverant. Kapitola 2.4, Získání a ověření vydání, vysvětluje zámek obrazů a kapitola 2.2, Edice pod kapotou, vysvětluje, co jednotlivé edice obsahují.
Nemusíte se rozhodnout natrvalo. Instalace Community přejde na Enterprise na místě, přičemž si zachová své lidi, soubory i historii; kapitola 2.7, Instalace edice Enterprise a použití licence, ukazuje jak. V Harrow jsme pro pilotní provoz spustili edici Community a o šest týdnů později jsme přešli na vyšší.
Licence není nikdy součástí tohoto plánu. Není to hodnota v chartu ani připojený soubor: importujete ji až po instalaci prostřednictvím konzole, nástroje nexusctl nebo rozhraní API.
Volba formy dodání
| Forma | Kdy se hodí | Kapitola |
|---|---|---|
Helm chart z registry.adverant.ai |
Váš vlastní cluster Kubernetes s trasou do registru | 2.6 a 2.7 |
nexusctl install |
Tentýž cluster, přičemž předletová kontrola a kontrola podpisu proběhnou za vás | 2.6 |
nexusctl install --single-node |
Jeden stroj, kde nexusctl nastaví i samotný cluster |
2.8 |
| Obraz instalačního disku | Holý server nebo virtuální stroj (VM), který raději nechcete připravovat ručně | 2.9 |
| Offline balíček | Vůbec žádná trasa ven; obrazy a chart přicházejí na disku | 2.10 |
Chart je v každé formě stejný. Co se mění, je to, kdo vytváří cluster a odkud pocházejí obrazy.
Plánovací pracovní list
Toto je list z Harrow, jak jej schválila Aoife. Zkopírujte levé dva sloupce a ten pravý vyplňte pro svou vlastní instalaci.
| Rozhodnutí | Klíč v souboru hodnot nebo příkaz | Harrow Port Authority |
|---|---|---|
| Kubernetes a verze | (předletová kontrola ji načte) | k3s v1.33.6+k3s1, tři uzly |
| Kontext Kube pro instalaci | --context |
harrow-prod |
| Jmenný prostor (Namespace) | --namespace |
nexus |
| Edice | edition, enterprise.enabled |
community pro pilotní provoz, poté enterprise |
| Registr obrazů | global.imageRegistry |
registry.adverant.ai |
| Doména | global.domain |
harrow.example |
| Adresa konzole | hosts.console |
console.harrow.example |
| Adresa API | hosts.api |
api.harrow.example |
| Adresa pro přihlášení | hosts.auth |
auth.harrow.example |
| TLS na okraji sítě | tls.mode, tls.existingSecret |
existing, Secret harrow-public-tls z interní CA v Harrow |
| Třída ingressu | ingress.className |
traefik |
| Jmenný prostor ingressu | networkPolicy.ingressNamespace |
kube-system |
| Třída úložiště | storage.className |
local-path |
| Datová úložiště | dataTier.<store>.mode |
Vše in-cluster, výchozí velikosti |
| Odchozí rozsahy | networkPolicy.externalEgressCIDRs |
Pouze rozsah poštovního relé |
| Název instalace (trvalý) | keys.installationName |
harrow-port-authority |
| Správci klíčů (v důsledku trvalí) | keys.custody.recipients |
Tři: Aoife Brennan, Tomás Reilly, notebook v trezoru (age1se1) |
| Grafické uzly | (předletová kontrola ji načte) | Žádné pro připojený pilotní provoz; hostovaný model s vlastním klíčem Harrow |
| První administrátor | nexusctl claim-code --administrator |
aoife.brennan@harrow.example |
Dva řádky na tomto listu nelze vzít zpět: název instalace a správce klíčů v tom smyslu, že ztráta všech znamená ztrátu úložiště klíčů. Nechte si tyto dvě položky podepsat někým, kdo má pravomoc říci ano. Všechno ostatní je změna v souboru hodnot.
Jakmile máte pracovní list hotový, přejděte na kapitolu 2.4, Získání a ověření vydání, a stáhněte vydání.
