PrijavaRezervirajte prezentaciju

Poglavlje 2.3

Planiranje instalacije

Što je potrebno za instalaciju Nexusa na Kubernetes prije nego što upišete naredbu, kolika je te dvije odluke koje ne možete povući: naziv instalacije i čuvari ključeva. Završava ispunjenim radnim listom za planiranje organizacije Harrow Port Authority.

Ovu je stranicu s engleskog izvornika preveo AI. Ako je išta nejasno, mjerodavna je stranica na engleskom jeziku. Pročitajte ovu stranicu na engleskom jeziku

16 min čitanja

Kada smo instalirali Nexus u organizaciji Harrow Port Authority, izvođenje naredbi trajalo je jedno poslijepodne. Planiranje je trajalo tjedan dana, a većina tog tjedna otišla je na dva pitanja koja nemaju nikakve veze sa sustavom Kubernetes: kako ćemo nazvati instalaciju i koje će osobe držati njezine ključeve za oporavak. Oba su odgovora trajna. Sve ostalo u ovom poglavlju može se promijeniti kasnije pomoću datoteke s vrijednostima i naredbe helm upgrade.

Ja sam Tomás Reilly, inženjer platforme u Harrowu. Harrow koristi dvije instalacije. U ovom se poglavlju planira povezana instalacija u našoj korporativnoj mreži, gdje smo najprije proveli pilot-projekt za izdanje Community. Operativna mreža luke, koja nema pristup internetu, dobila je vlastitu instalaciju kasnije; to pokriva poglavlje 2.10, Instalacija u izoliranom okruženju (air-gapped). Ovo poglavlje sadrži ono što bih volio da sam imao prvog jutra: klaster kakav Nexus očekuje, nazive na koje se odaziva, koliko resursa traži od vaših čvorova te odluke koje trebate usuglasiti s voditeljem IT-ja prije instalacije. Poglavlje završava radnim listom koji je Aoife Brennan, naša voditeljica IT-ja, odobrila i potpisala prije nego što smo započeli. Poglavlje 2.4, Preuzimanje i provjera izdanja, pokriva dohvaćanje i provjeru izdanja, a poglavlje 2.5, Predprovjera alatom nexusctl, provjerava vaš klaster u odnosu na sve što je ovdje navedeno.

Što klaster mora imati

Nexus se instalira kao jedan Helm chart, nexus, verzije 1.0.0-alpha.1. Taj chart sadrži usluge platforme i njihov podatkovni sloj te se odbija instalirati na klaster kojem nedostaju dijelovi navedeni u nastavku.

Zahtjev Što Nexus očekuje Zašto
Kubernetes 1.33 ili noviji. Testirano na distribuciji k3s v1.33.6+k3s1 Polje kubeVersion u chartu postavljeno je na >=1.33.0-0, a helm install to obavezno provodi
cert-manager v1.21.3, instaliran prije sustava Nexus Chart stvara vlastito lokalno certifikacijsko tijelo (CA) i certifikate koje njegove usluge koriste za međusobnu komunikaciju
Helm v4 (mi smo koristili v4.3.1) Helm 4 prema zadanim postavkama čeka na izvršavanje hook Jobova iz charta, o čemu instalacija ovisi
Klasa pohrane (StorageClass) Jedna označena kao zadana ili ona koju navedete u storage.className Svako spremište podataka zahtijeva trajni volumen (PersistentVolume)
Ingress klasa (IngressClass) Jedna označena kao zadana ili ona koju navedete u ingress.className Tri javne adrese obični su networking.k8s.io/v1 Ingress resursi
Portovi 80 i 443 Otvoreni na ingress kontroleru, kao LoadBalancer ili NodePort Service Korisnici pristupaju sustavu Nexus putem ingress kontrolera
Arhitektura linux/amd64 ili linux/arm64 čvorovi Svaka je slika izgrađena za obje arhitekture

Dvije stvari namjerno nisu u toj tablici. Nexus ne treba servisnu mrežu (service mesh): obostrani TLS (mTLS, Transport Layer Security u oba smjera) između usluga dolazi iz lokalnog CA-a charta putem komponente cert-manager. Chart ima ključ istio.enabled čija je zadana vrijednost false, i trebali biste je tako ostaviti. Sustavu Nexus također ne treba vlastiti sustav za politike odobravanja pristupa (admission policy engine).

Na svojoj radnoj stanici trebat ćete kubectl, Helm v4, cosign v3 za provjeru potpisa, age za izradu ključeva skrbnika i nexusctl, sučelje naredbenog retka (CLI) za operatere sustava Nexus. Poglavlje 2.4, Preuzimanje i provjera izdanja, navodi gdje se nalazi svako preuzimanje za Nexus.

Tri adrese

Svaka se instalacija odaziva na tri naziva poslužitelja (host names). Chart ih naziva identitetom instalacije i svaka se usluga odbija pokrenuti bez njih.

Ključ u datoteci values Naziv u Harrowu Što se tamo odaziva
hosts.console console.harrow.example Konzola, web-aplikacija u koju se korisnici prijavljuju
hosts.api api.harrow.example Pristupnik (gateway), koji poslužuje aplikacijsko programsko sučelje (API) i usmjerava svaki zahtjev za umjetnu inteligenciju (AI)
hosts.auth auth.harrow.example Usluga za prijavu, nexus-auth

global.domain sadrži domenu pod kojom se nalaze sva tri naziva, u našem slučaju harrow.example. Svaki naziv poslužitelja potpuni je naziv sam za sebe i može se nalaziti pod bilo kojom domenom kojom upravljate. Mi smo zadržali sva tri pod jednom domenom jer ih je tada mogao pokriti jedan certifikat.

Izradite zapis u sustavu naziva domena (DNS) za svaki od ta tri naziva, koji pokazuje na adresu vašeg ingress kontrolera. Učinite to prije predprovjere. nexusctl preflight pretražuje svaki naziv s vaše radne stanice i prekida instalaciju ako bilo koji od njih nema zapis, jer korisnik ne može pristupiti nazivu koji se ne može razriješiti.

Na lijevoj strani nalaze se tri DNS naziva: console.harrow.example, api.harrow.example i auth.harrow.example, svaki sa strelicom koja vodi u jedan okvir s oznakom "ingress controller, ports 80 and 443". Iz tog okvira tri strelice vode u veći okvir s oznakom "namespace nexus": strelica za console vodi do "nexus-alpha :3000", strelica za api do "nexus-gateway :9092", a strelica za auth do "nexus-auth :9101". Isprekidani rub oko imenskog prostora nosi oznaku "default deny; only the ingress namespace may reach these three".
Kako tri javna naziva dolaze do usluga u pozadini.

Odabir mjesta završetka TLS-a

Polje tls.mode u chartu određuje tko drži certifikate za tri javne adrese. Postoje tri mogućnosti, a između njih se možete prebacivati kasnije pomoću nadogradnje.

tls.mode Vi osiguravate Što chart radi
existing (zadano) Kubernetes TLS Secret u imenskom prostoru nexus, naveden u tls.existingSecret Sva tri Ingress resursa koriste taj jedan Secret
cert-manager ClusterIssuer koji vi održavate, naveden u tls.clusterIssuer Dodaje anotacije svakom Ingress resursu tako da cert-manager izdaje nexus-console-tls, nexus-api-tls i nexus-auth-tls
none Nešto ispred klastera što terminira TLS, kao što je vaš vlastiti usmjerivač opterećenja (load balancer) Generira Ingress resurse bez TLS odjeljka

Uz existing, jedan certifikat poslužuje sva tri poslužitelja, pa mora sadržavati nazive za sva tri, bilo kao tri alternativna naziva subjekta (SAN) ili kao zamjenski znak (wildcard) za vašu domenu. Mi smo koristili certifikat internog CA-a u Harrowu. Predprovjera čita Secret prije nego što započnete instalaciju i upozorava ako njegov certifikat istječe u roku od 30 dana.

Uz cert-manager i izdavatelja za automatsko upravljanje certifikatima (ACME), chart ne dodaje vlastito preusmjeravanje, tako da zahtjev /.well-known/acme-challenge/ na portu 80 dolazi do razrješivača (solvera) neizmijenjen. Nemojte dodavati preusmjeravanje s HTTP-a na HTTPS na svom ingress kontroleru koje se izvršava prije putanje za provjeru (challenge path); certifikat koji se ne može obnoviti tiho će zakazati tjednima kasnije.

Što god odabrali za javni rub mreže, usluge unutar imenskog prostora uvijek komuniciraju putem TLS-a iz lokalnog CA-a charta. Taj dio nije stvar izbora i zato je cert-manager preduvjet čak i kada je tls.mode postavljen na existing ili none.

Što napušta klaster, a što ne

Chart generira mrežnu politiku zadane zabrane (default-deny) za imenski prostor nexus. Nakon toga dopušteni su samo sljedeći tokovi prometa:

  • promet između Nexus podova unutar imenskog prostora;
  • DNS upiti prema DNS usluzi klastera;
  • Kubernetes API poslužitelj, za nekoliko usluga koje provjeravaju tokene radnog opterećenja;
  • imenski prostor ingress kontrolera, prema trima javnim Service resursima;
  • bilo koji CIDR (Classless Inter-Domain Routing) rasponi koje navedete u networkPolicy.externalEgressCIDRs.

Taj je posljednji popis prema zadanim postavkama prazan. Ako ćete koristiti posrednik za e-poštu (mail relay) ili poslužitelj modela izvan klastera, njegov raspon ide tamo. Telemetrija je isključena i ostaje isključena: shema prihvaća samo telemetry.enabled: false, a vlastito izvješćivanje o upotrebi spremišta podataka također je isključeno.

Chart čita adrese API poslužitelja iz klastera prilikom instalacije. Ako vaš račun ne može čitati kubernetes Endpoints resurse u imenskom prostoru default, navedite ih sami u networkPolicy.apiServerCIDRs, kao /32 raspone. proxy.trustedCIDRs imenuje mrežu podova na kojoj se nalazi vaš ingress kontroler, tako da nexus-auth zna čijem zaglavlju X-Forwarded-For može vjerovati. Zadana vrijednost, 10.42.0.0/16, mreža je podova u distribuciji k3s.

Dimenzioniranje

Zadani zahtjevi (requests) charta zbrajaju se na oko 2.05 jezgri središnje procesorske jedinice (CPU) i 6.7 GiB memorije. To je ono što raspoređivač (scheduler) rezervira; ograničenja (limits) su viša, a spremišta podataka rastu prema njima kako dodajete korisnike i datoteke.

Dio Zatraženi CPU Zatražena memorija
Devet usluga platforme (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 jezgri 2.6 GiB
Usluga za ključeve, nexus-keys 0.05 jezgri 64 MiB
PostgreSQL 0.25 jezgri 1 GiB
Neo4j 0.25 jezgri 2 GiB
Valkey, Qdrant i spremište objekata zajedno 0.25 jezgri 640 MiB
Dva OpenBao poslužitelja spremišta ključeva 0.15 jezgri 384 MiB

Zadani volumeni zbrajaju se na 142 GiB:

Spremište Ključ u datoteci values Zadana veličina
PostgreSQL 16 uz PostGIS 3 i pgvector 0.8 dataTier.postgres.size 50Gi
Spremište objekata (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Spremište ključeva i njegov servis za otključavanje (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi i 1Gi
Potvrde usluge za ključeve keys.receiptsStorage 1Gi

Za jedan čvor planirajte 8 vCPU-a, 32 GiB radne memorije (RAM) i SSD (solid-state drive) od 250 GB. Za evaluaciju će biti dovoljno 4 vCPU-a, 16 GiB i 200 GB. Slika instalacijskog diska odbija stroj s manje od 16 GiB memorije (pogledajte poglavlje 2.9, Slika instalacijskog diska), i ja bih to posvuda tretirao kao apsolutni minimum.

Grafički čvorovi nisu obavezni. Bez čvora koji nudi grafičku procesorsku jedinicu (GPU), asistent odgovara putem hostiranog modela, koristeći vlastiti ključ organizacije. Predprovjera to prijavljuje kao upozorenje, nikada kao pogrešku. Poglavlje 2.14, Pružatelji i modeli AI-ja, pokriva oba načina.

Svako se spremište može izvoditi i izvan klastera: postavite dataTier.<store>.mode na external te navedite njegovog poslužitelja i Secret. Vanjski PostgreSQL treba korisnički račun superkorisnika (superuser) za početno postavljanje (bootstrap) instalacije i certifikat koji Nexus može provjeriti. Poglavlje 2.11, Varijacije: vanjska spremišta, TLS i ingress, pokriva tu temu. Ako ih zadržite u klasteru, stavite ih na klasu pohrane iza koje stoje stvarni diskovi. Baza podataka je dio koji će vam najviše nedostajati ako lokalni disk čvora otkaže.

Naziv instalacije je trajan

keys.installationName je naziv kojim operateri nazivaju ovu instalaciju. Mora odgovarati izrazu ^[a-z][a-z0-9-]{0,62}$: malo slovo, a zatim do 62 mala slova, znamenke ili crtice.

Kada se spremište ključeva prvi put pokrene, ono stvara identitet instalacije pod tim nazivom, i taj je identitet trajno fiksiran. Licenca tvrtke Adverant izdaje se za taj identitet, pa se licenca izrađena za jednu instalaciju odbija na drugoj uz pogrešku LICENCE_OTHER_INSTALLATION. Preimenovanje bi značilo novu instalaciju, novi identitet i nove licence.

Chart nema zadanu vrijednost za naziv. Odbija instalaciju bez naziva (INSTALLATION_NAME_MISSING) i odbija ogledni naziv iz vlastitih oglednih datoteka s vrijednostima (INSTALLATION_NAME_EXAMPLE). Predprovjera prijavljuje oboje prije nego što uopće dođete do tog koraka.

U Harrowu smo na to potrošili više vremena nego što bih volio priznati. Odlučili smo se za harrow-port-authority: imenuje organizaciju, ne govori ništa o tome na kojem se klasteru izvodi i ostat će točan i kada se hardver zamijeni. Izbjegavajte nazive poput prod-k3s-2 koji opisuju današnje strojeve.

Čuvanje ključeva

Nexus čuva ključeve svake organizacije u vlastitom spremištu ključeva, unutar klastera. Njime ne upravljate u svakodnevnom radu, ali prije instalacije morate odlučiti tko ga može vratiti u rad nakon ponovnog pokretanja. To je odluka koja najviše košta ako pogriješite.

Spremište ključeva sastoji se od dva OpenBao poslužitelja. Glavni, openbao, drži ključeve i otključava sam sebe putem drugog, manjeg poslužitelja, openbao-unsealer. Taj servis za otključavanje (unsealer) zaključan je Shamirovom shemom: pet dijelova (shares), od kojih bilo koja tri otvaraju sustav. Prilikom instalacije, Job za skrbništvo (custody Job) inicijalizira oba poslužitelja unutar klastera. U memoriji tog Joba, on šifrira dijelove servisa za otključavanje i ključeve za oporavak spremišta ključeva za svakog skrbnika kojeg navedete, pohranjuje samo šifrirani tekst (u Secret resursima openbao-unseal-shares-encrypted i openbao-recovery-keys-encrypted) te opoziva oba korijenska (root) tokena prije nego što završi. Nijedan nešifrirani dio nikada ne dospije na disk ili u zapisnik (log).

Nakon svakog ponovnog pokretanja čvora na kojem se nalazi servis za otključavanje, taj se servis pokreće u zaključanom stanju. Spremište ključeva čeka na njega i ništa što treba ključ ne radi dok ga skrbnik ne otključa. Za to je potrebno jedno dešifriranje vlastitim privatnim ključem skrbnika. Postupak se nalazi u poglavlju 2.15, Drugi dan: upravljanje sustavom Nexus.

Izrada ključa skrbnika

Skrbnik se imenuje javnom polovicom age ključa, koja se naziva primateljem (recipient). Svaki skrbnik izrađuje vlastiti ključ na vlastitom računalu i daje vam samo primatelja:

age-keygen -o custodian.key

Redak # public key: u datoteci predstavlja primatelja i počinje s age1. Skrbnik koji koristi Mac može umjesto toga čuvati ključ u čipu Secure Enclave na Macu, tako da privatna polovica nikada ne napušta čip i svaka upotreba traži otisak prsta:

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

Taj primatelj počinje s age1se1. Job za skrbništvo šifrira podatke za pet oblika primatelja: age1 (X25519), age1tag1 i age1tagpq1 (tag), age1pq1 (hibridni postkvantni) te age1se1 (Secure Enclave). Odbija bilo koji drugi oblik dodatka (plugina), kao što je age1yubikey1; umjesto toga navedite taj ključ u jednom od prihvaćenih oblika.

Chart provjerava svakog primatelja prilikom generiranja manifesta. Pogrešno upisan primatelj ne prolazi bech32 kontrolni zbroj i biva odbijen, tako da se ništa nikada ne zaključava ključem koji nitko ne posjeduje. Ako netko zabunom zalijepi privatni ključ na popis, chart ga odbija bez ispisivanja njegovog sadržaja. Ogledni primatelj u vlastitim datotekama s vrijednostima charta također se odbija (KEYS_CUSTODIAN_EXAMPLE); nitko ne posjeduje njegovu privatnu polovicu.

Koliko skrbnika odabrati

Svaki je dio šifriran za svakog skrbnika, tako da bilo koji pojedinačni skrbnik može samostalno otključati sustav. Više skrbnika znači više načina za oporavak i više ljudi od kojih svaki može djelovati samostalno. U Harrowu smo odabrali tri: Aoife, mene i Secure Enclave ključ na rezervnom prijenosnom računalu koje se čuva u sefu luke. Dva je najmanji broj koji bih prihvatio. Jedan predstavlja jedinstvenu točku kvara koja će, prije ili kasnije, biti na godišnjem odmoru kada se čvor ponovno pokrene.

Odabir izdanja

edition je community ili enterprise, a enterprise.enabled se mora podudarati s tim. Chart odbija nepodudaranje i odbija bilo koje izdanje koje nije jedno od ta dva.

Izdanje također određuje koje ćete slike instalirati. Svaki paket charta nosi zaključani popis slika (images lock), odnosno popis svake slike prema njezinom sažetku (digest), za jedno izdanje. Instalacija izdanja Community preuzima samo Community slike. Instalacija izdanja Enterprise preuzima Enterprise zaključani popis, koji sadrži Community slike plus Enterprise verzije, te ih povlači pomoću tokena za preuzimanje (pull token) s vašeg Adverant računa. Poglavlje 2.4, Preuzimanje i provjera izdanja, objašnjava zaključani popis, a poglavlje 2.2, Izdanja ispod haube, objašnjava što svako izdanje sadrži.

Ne morate donijeti konačnu odluku odmah. Instalacija izdanja Community prelazi na Enterprise na istom mjestu (in place), zadržavajući svoje korisnike, datoteke i povijest; poglavlje 2.7, Instalacija izdanja Enterprise i primjena licence, pokazuje kako. Mi smo u Harrowu koristili Community za pilot-projekt i prešli na Enterprise šest tjedana kasnije.

Licenca nikada nije dio ovog plana. Ona nije vrijednost u chartu niti montirana datoteka: uvozite je nakon instalacije, putem konzole, alata nexusctl ili API-ja.

Odabir oblika isporuke

Oblik Kada odgovara Poglavlje
Helm chart iz registry.adverant.ai Vaš vlastiti Kubernetes klaster, s mrežnim putem do registra 2.6 i 2.7
nexusctl install Isti klaster, uz predprovjeru i provjeru potpisa koje se izvršavaju umjesto vas 2.6
nexusctl install --single-node Jedan stroj, gdje nexusctl ujedno postavlja i sam klaster 2.8
Slika instalacijskog diska Fizički poslužitelj (bare metal) ili virtualni stroj (VM) koji radije ne biste pripremali ručno 2.9
Izvanmrežni paket (offline bundle) Bez ikakvog izlaza na vanjsku mrežu; slike i chart dolaze na disku 2.10

Chart je isti u svakom obliku. Ono što se mijenja jest tko stvara klaster i odakle dolaze slike.

Preuzmite izdanje
Preuzmite izdanje
Ovo je stranica izdanja na Adverant računu. Obratite pozornost na jasnu izjavu o tome što alfa izdanje obećava, veličinu i potpis pokraj svake datoteke te izvanmrežne naredbe za provjeru preuzimanja.

Radni list za planiranje

Ovo je radni list za Harrow, kakvog je Aoife odobrila. Kopirajte lijeva dva stupca i ispunite desni za vlastitu instalaciju.

Odluka Ključ u datoteci values ili naredba Harrow Port Authority
Kubernetes i verzija (predprovjera to očitava) k3s v1.33.6+k3s1, tri čvora
Kube kontekst za instalaciju --context harrow-prod
Imenski prostor (namespace) --namespace nexus
Izdanje edition, enterprise.enabled community za pilot-projekt, zatim enterprise
Registar slika global.imageRegistry registry.adverant.ai
Domena global.domain harrow.example
Adresa konzole hosts.console console.harrow.example
Adresa API-ja hosts.api api.harrow.example
Adresa za prijavu hosts.auth auth.harrow.example
TLS na rubu mreže tls.mode, tls.existingSecret existing, Secret harrow-public-tls iz internog CA-a u Harrowu
Ingress klasa ingress.className traefik
Imenski prostor ingressa networkPolicy.ingressNamespace kube-system
Klasa pohrane storage.className local-path
Spremišta podataka dataTier.<store>.mode Sva in-cluster, zadane veličine
Odlazni rasponi networkPolicy.externalEgressCIDRs Samo raspon posrednika za e-poštu
Naziv instalacije (trajno) keys.installationName harrow-port-authority
Skrbnici (u praksi trajni) keys.custody.recipients Tri: Aoife Brennan, Tomás Reilly, prijenosno računalo u sefu (age1se1)
Grafički čvorovi (predprovjera to očitava) Nijedan za povezani pilot-projekt; hostirani model s vlastitim ključem organizacije Harrow
Prvi administrator nexusctl claim-code --administrator aoife.brennan@harrow.example

Dva retka u tom listu ne mogu se poništiti: naziv instalacije te skrbnici u smislu da gubitak svih njih znači i gubitak spremišta ključeva. Pobrinite se da ta dva retka potpiše i odobri netko tko ima ovlasti reći „da”. Sve ostalo samo je promjena vrijednosti u konfiguraciji.

Kada završite s radnim listom, prijeđite na poglavlje 2.4, Preuzimanje i provjera izdanja, i dohvatite izdanje.