Přihlásit seDomluvit prezentaci

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ě

16 min čtení

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.

Vlevo tři názvy DNS: console.harrow.example, api.harrow.example a auth.harrow.example, každý se šipkou do jednoho pole označeného „ingress controller, ports 80 and 443“. Z tohoto pole vedou tři šipky do většího pole označeného „namespace nexus“: šipka console do „nexus-alpha :3000“, šipka api do „nexus-gateway :9092“ a šipka auth do „nexus-auth :9101“. Přerušovaný okraj kolem jmenného prostoru je označen „default deny; only the ingress namespace may reach these three“.
Jak se tři veřejné názvy dostanou ke službám za nimi.

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.key

Tento 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.

Získat vydání
Získat vydání
Toto je stránka vydání v účtu Adverant. Všimněte si jasného prohlášení o tom, co vydání alpha slibuje, velikosti a podpisu vedle každého souboru a offline příkazů pro kontrolu stažených dat.

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í.