BejelentkezésBemutató kérése

2.3. fejezet

A telepítés megtervezése

Mire van szüksége a Nexus Kubernetes-alapú telepítésének, mielőtt egyetlen parancsot is begépelne, mekkora a mérete, és melyik az a két döntés, amelyet később nem vonhat vissza: a telepítés neve és a kulcsőrzők személye. A fejezet a Harrow Port Authority kitöltött tervezési munkalapjával zárul.

Ezt az oldalt AI fordította az eredeti angol szövegből. Ha bármi nem egyértelmű, az angol nyelvű oldal az irányadó. Oldal olvasása angolul

16 perc olvasási idő

Amikor telepítettük a Nexust a Harrow Port Authoritynél, a parancsok futtatása egy délutánt vett igénybe. A tervezés egy hétig tartott, és ennek a hétnek a nagy része két olyan kérdésre ment el, amelyeknek semmi közük a Kuberneteshez: minek nevezzük a telepítést, és kik őrzik majd a helyreállítási kulcsait. Mindkét válasz végleges. Az ebben a fejezetben szereplő összes többi dolog később módosítható egy values fájllal és egy helm upgrade paranccsal.

Tomás Reilly vagyok, a Harrow platformmérnöke. A Harrow két telepítést üzemeltet. Ez a fejezet a vállalati hálózatunkban lévő, internetkapcsolattal rendelkező telepítést tervezi meg, ahol először a Community kiadást próbáltuk ki. A kikötő üzemeltetési hálózata, amelynek nincs kijárata az internetre, később saját telepítést kapott; erről a 2.10. fejezet, Zárt hálózati (air-gapped) telepítés szól. Ez a fejezet az, amire az első reggelen vágytam volna: milyen klasztert vár el a Nexus, milyen nevekre hallgat, mekkora erőforrást igényel a csomópontoktól, és milyen döntéseket kell tisztáznia az IT-vezetővel a telepítés előtt. A fejezet azzal a munkalappal zárul, amelyet Aoife Brennan, az IT-vezetőnk írt alá, mielőtt belekezdtünk. A 2.4. fejezet, Kiadás beszerzése és ellenőrzése a kiadás letöltését és ellenőrzését mutatja be, a 2.5. fejezet, Előzetes ellenőrzés a nexusctl-lel pedig összeveti a klaszterét az itt leírtakkal.

Amivel a fürtnek (cluster) rendelkeznie kell

A Nexus egyetlen Helm chartként települ: nexus, 1.0.0-alpha.1 verzió. A chart tartalmazza a platformszolgáltatásokat és azok adatszintjét, és megtagadja a telepítést olyan klaszterre, amelyből hiányoznak az alábbi elemek.

Követelmény Mit vár el a Nexus Miért
Kubernetes 1.33 vagy újabb. k3s v1.33.6+k3s1 verzión tesztelve A chart kubeVersion értéke >=1.33.0-0, és a helm install ezt ki is kényszeríti
cert-manager v1.21.3, a Nexus előtt telepítve A chart létrehozza a saját helyi hitelesítésszolgáltatóját (CA), valamint azokat a tanúsítványokat, amelyeket a szolgáltatásai az egymással való kommunikációhoz használnak
Helm v4 (mi a v4.3.1-et használtuk) A Helm 4 alapértelmezés szerint megvárja a chart hook Job-jainak lefutását, amire a telepítés épít
Tárolóosztály (storage class) Egy alapértelmezettként megjelölt, vagy egy, amelyet a storage.className alatt nevez meg Minden adattár perzisztens kötetet (persistent volume) igényel
Ingress osztály (ingress class) Egy alapértelmezettként megjelölt, vagy egy, amelyet a ingress.className alatt nevez meg A három nyilvános cím egyszerű networking.k8s.io/v1 Ingress erőforrás
80-as és 443-as port Nyitva az ingress vezérlőn, LoadBalancer vagy NodePort Service-ként A felhasználók az ingress vezérlőn keresztül érik el a Nexust
Architektúra linux/amd64 vagy linux/arm64 csomópontok Minden képfájl mindkét architektúrára elkészül

Két dolog szándékosan hiányzik ebből a táblázatból. A Nexusnak nincs szüksége service mesh-re: a szolgáltatások közötti kölcsönös TLS (mTLS, kétirányú Transport Layer Security) a chart helyi CA-jától származik a cert-manageren keresztül. A chart rendelkezik egy istio.enabled kulccsal, amelynek alapértelmezett értéke false, és ezt érdemes is így hagynia. A Nexusnak saját befogadási házirend-motorra (admission policy engine) sincs szüksége.

A munkaállomásán szüksége lesz a kubectl eszközre, a Helm v4-re, az aláírások ellenőrzéséhez a cosign v3-ra, a kulcsőrzői (custodian) kulcsok előállításához az age eszközre, valamint a nexusctl-re, a Nexus üzemeltetői parancssori felületére (CLI). A 2.4. fejezet, Kiadás beszerzése és ellenőrzése ismerteti, hogy hol találhatók az egyes Nexus-letöltések.

Három cím

Minden telepítés három állomásnéven (host name) válaszol. A chart ezeket nevezi telepítési identitásnak, és nélkülük minden szolgáltatás megtagadja az indulást.

Values kulcs A Harrow neve Mi válaszol ott
hosts.console console.harrow.example A konzol, a webalkalmazás, ahová a felhasználók bejelentkeznek
hosts.api api.harrow.example Az átjáró (gateway), amely kiszolgálja az alkalmazásprogramozási felületet (API), és irányít minden mesterséges intelligenciával (AI) kapcsolatos kérést
hosts.auth auth.harrow.example A bejelentkezési szolgáltatás, nexus-auth

A global.domain tárolja azt a domaint, amely alatt a három név elhelyezkedik, esetünkben ez a harrow.example. Mindegyik állomásnév önmagában is teljes név, és bármely Ön által felügyelt domain alatt elhelyezkedhet. Mi mindhármat egy domain alatt tartottuk, mert így egyetlen tanúsítvány lefedhette őket.

Hozzon létre egy-egy Domain Name System (DNS) rekordot mindhárom névhez, amelyek az ingress vezérlő címére mutatnak. Tegye ezt meg az előzetes ellenőrzés (preflight) előtt. A nexusctl preflight a munkaállomásáról lekérdezi mindegyik nevet, és megszakítja a telepítést, ha bármelyikhez nincs rekord, mivel a felhasználó nem tud elérni egy olyan nevet, amely nem oldható fel.

Bal oldalon három DNS-név: console.harrow.example, api.harrow.example és auth.harrow.example, mindegyiktől egy-egy nyíl mutat egyetlen, "ingress controller, ports 80 and 443" feliratú dobozba. Ebből a dobozból három nyíl vezet egy nagyobb, "namespace nexus" feliratú dobozba: a console nyíl a "nexus-alpha :3000", az api nyíl a "nexus-gateway :9092", az auth nyíl pedig a "nexus-auth :9101" elemhez. A névtér körüli szaggatott keret felirata: "default deny; only the ingress namespace may reach these three".
Hogyan éri el a három nyilvános név a mögöttük lévő szolgáltatásokat.

A TLS-végződtetés módjának kiválasztása

A chart tls.mode beállítása dönti el, hogy ki kezeli a három nyilvános cím tanúsítványait. Három lehetőség van, és később egy frissítéssel (upgrade) válthat közöttük.

tls.mode Amit Ön biztosít Amit a chart tesz
existing (az alapértelmezett) Egy Kubernetes TLS Secret a nexus névtérben, amelynek nevét a tls.existingSecret adja meg Mindhárom Ingress ugyanezt az egy Secretet használja
cert-manager Egy Ön által üzemeltetett ClusterIssuer, amelynek nevét a tls.clusterIssuer adja meg Annotációval lát el minden Ingresst, így a cert-manager kiállítja a nexus-console-tls, nexus-api-tls és nexus-auth-tls tanúsítványokat
none Valami a klaszter előtt, ami lezárja a TLS-t, például a saját terheléselosztója TLS-szakasz nélkül generálja le az Ingresseket

Az existing használatakor egyetlen tanúsítvány szolgálja ki mindhárom állomásnevet, ezért mindhármat tartalmaznia kell, vagy három alternatív kérelmezőnévként (SAN), vagy a domainjére szóló helyettesítő karakteres (wildcard) tanúsítványként. Mi a Harrow belső CA-jától származó tanúsítványt használtunk. Az előzetes ellenőrzés a telepítés előtt beolvassa a Secretet, és figyelmeztet, ha a tanúsítvány 30 napon belül lejár.

A cert-manager és egy Automatic Certificate Management Environment (ACME) kibocsátó használatakor a chart nem ad hozzá saját átirányítást, így a 80-as porton érkező /.well-known/acme-challenge/ kérés érintetlenül eljut a solverhez. Ne adjon hozzá olyan HTTP–HTTPS átirányítást az ingress vezérlőjén, amely a challenge útvonal előtt fut le; egy olyan tanúsítvány, amely nem tud megújulni, hetekkel később csendben hibára fut.

Bármit is választ a nyilvános végponthoz, a névtéren belüli szolgáltatások mindig a chart helyi CA-jától származó TLS-en keresztül kommunikálnak. Ez a rész nem választható, és ezért előfeltétel a cert-manager még akkor is, ha a tls.mode értéke existing vagy none.

Mi hagyja el a fürtöt, és mi nem

A chart egy alapértelmezett tiltó (default-deny) hálózati házirendet generál a nexus névtérhez. Ezután csak a következő adatfolyamok engedélyezettek:

  • forgalom a névtéren belüli Nexus podok között;
  • DNS-lekérdezések a klaszter DNS-szolgáltatása felé;
  • a Kubernetes API-szerver elérése azon néhány szolgáltatás számára, amelyek munkaterhelés-tokeneket (workload token) ellenőriznek;
  • az ingress vezérlő névtere a három nyilvános Service felé;
  • bármely Classless Inter-Domain Routing (CIDR) tartomány, amelyet felsorol a networkPolicy.externalEgressCIDRs alatt.

Ez az utolsó lista alapértelmezés szerint üres. Ha a klaszteren kívüli levelezőátjárót (mail relay) vagy modellszervert fog használni, annak a tartománya ide kerül. A telemetria ki van kapcsolva, és ki is marad: a séma csak a telemetry.enabled: false értéket fogadja el, és az adattárak saját használati jelentései is ki vannak kapcsolva.

A chart a telepítéskor kiolvassa az API-szerver címeit a klaszterből. Ha a fiókja nem tudja olvasni a kubernetes Endpoints erőforrást a default névtérben, adja meg őket saját maga a networkPolicy.apiServerCIDRs alatt, /32 tartományokként. A proxy.trustedCIDRs nevezi meg azt a podhálózatot, amelyen az ingress vezérlője ül, így a nexus-auth tudja, kinek az X-Forwarded-For fejlécében bízhat meg. Az alapértelmezett 10.42.0.0/16 a k3s podhálózata.

Méretezés

A chart alapértelmezett erőforrásigényei (requests) összesen körülbelül 2.05 központi feldolgozóegység (CPU) magot és 6.7 GiB memóriát tesznek ki. Ennyit foglal le az ütemező; a korlátok (limits) magasabbak, és az adattárak fokozatosan belenőnek ezekbe, ahogy felhasználókat és fájlokat ad hozzá.

Rész Igényelt CPU Igényelt memória
Kilenc platformszolgáltatás (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 mag 2.6 GiB
A kulcsszolgáltatás, nexus-keys 0.05 mag 64 MiB
PostgreSQL 0.25 mag 1 GiB
Neo4j 0.25 mag 2 GiB
A Valkey, a Qdrant és az objektumtár együtt 0.25 mag 640 MiB
A kulcstár két OpenBao szervere 0.15 mag 384 MiB

Az alapértelmezett kötetek összesen 142 GiB-ot tesznek ki:

Adattár Values kulcs Alapértelmezett méret
PostgreSQL 16 PostGIS 3-mal és pgvector 0.8-cal dataTier.postgres.size 50Gi
Objektumtár (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
A kulcstár és a feloldója (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi és 1Gi
Kulcsszolgáltatási nyugták keys.receiptsStorage 1Gi

Egyetlen csomóponthoz tervezzen 8 vCPU-val, 32 GiB operatív memóriával (RAM) és egy 250 GB-os félvezető-alapú meghajtóval (SSD). Kipróbáláshoz 4 vCPU, 16 GiB és 200 GB is elegendő. A telepítő lemezképe elutasítja a 16 GiB-nál kevesebb memóriával rendelkező gépeket (lásd a 2.9. fejezetet, A telepítő lemezképe), és én ezt tekinteném az alsó határnak mindenhol.

A grafikus csomópontok opcionálisak. Grafikus feldolgozóegységet (GPU) kínáló csomópont nélkül az asszisztens egy hosztolt modellen keresztül válaszol, a szervezet saját kulcsát használva. Az előzetes ellenőrzés ezt figyelmeztetésként jelzi, soha nem hibaként. A 2.14. fejezet, AI-szolgáltatók és modellek mindkét utat bemutatja.

Mindegyik adattár futhat a klaszteren kívül is: állítsa a dataTier.<store>.mode értékét external-re, és adja meg az állomásnevét, valamint egy Secretet. Egy külső PostgreSQL-nek szüksége van egy superuser fiókra a telepítés kezdeti betöltéséhez (bootstrap), és egy olyan tanúsítványra, amelyet a Nexus ellenőrizni tud. Erről a 2.11. fejezet, Variációk: külső adattárak, TLS és ingress szól. Ha a klaszterben tartja őket, helyezze őket olyan tárolóosztályra, amely mögött valódi lemezek vannak. Az adatbázis az a rész, amely a legjobban fog hiányozni, ha egy csomópont helyi lemeze tönkremegy.

A telepítés neve végleges

A keys.installationName az a név, ahogyan az üzemeltetők ezt a telepítést hívják. Meg kell felelnie a ^[a-z][a-z0-9-]{0,62}$ kifejezésnek: egy kisbetű, majd legfeljebb 62 kisbetű, számjegy vagy kötőjel.

Amikor a kulcstár először elindul, ezen a néven hozza létre a telepítés identitását, és ez az identitás véglegesen rögzül. Az Adveranttól származó licenc erre az identitásra szól, így egy másik telepítéshez készült licencet a rendszer LICENCE_OTHER_INSTALLATION hibával elutasít. Az átnevezés új telepítést, új identitást és új licenceket jelentene.

A chart nem tartalmaz alapértelmezett értéket a névhez. Elutasítja a név nélküli telepítést (INSTALLATION_NAME_MISSING), és elutasítja a saját példa values fájljaiban szereplő példanevet is (INSTALLATION_NAME_EXAMPLE). Az előzetes ellenőrzés mindkettőt jelzi, mielőtt idáig eljutna.

A Harrow-nál több időt töltöttünk ezzel, mint amennyit szívesen bevallanék. Végül a harrow-port-authority mellett döntöttünk: megnevezi a szervezetet, semmit sem mond arról, hogy melyik klaszteren fut, és akkor is igaz marad, amikor a hardvert lecserélik. Kerülje a prod-k3s-2 jellegű neveket, amelyek a mai gépeket írják le.

Kulcsőrzés

A Nexus minden szervezet kulcsait a saját kulcstárában, a klaszteren belül tartja. Ezt nem kell napi szinten üzemeltetnie, de a telepítés előtt el kell döntenie, hogy ki tudja visszaállítani egy újraindítás után. Ez az a döntés, amely a legtöbbe kerül, ha elhibázza.

A kulcstár két OpenBao szerverből áll. A fő szerver, a openbao tárolja a kulcsokat, és egy második, kisebb szerveren, a openbao-unsealer-n keresztül oldja fel magát (unseal). A feloldó Shamir sémájával van lezárva: öt részlet (share), amelyek közül bármelyik három kinyitja. A telepítéskor egy custody Job inicializálja mindkét szervert a klaszteren belül. Ennek a Jobnak a memóriájában a rendszer titkosítja a feloldó részleteit és a kulcstár helyreállítási kulcsait minden Ön által megnevezett kulcsőrző (custodian) számára, csak a titkosított szöveget tárolja el (a openbao-unseal-shares-encrypted és openbao-recovery-keys-encrypted Secretekben), és a befejezés előtt visszavonja mindkét root tokent. Nyílt szövegű részlet soha nem kerül lemezre vagy naplóba.

A feloldó csomópontjának bármilyen újraindítása után a feloldó lezárt (sealed) állapotban indul. A kulcstár vár rá, és semmi, aminek kulcsra van szüksége, nem működik addig, amíg egy kulcsőrző fel nem oldja. Ehhez egyetlen visszafejtésre van szükség a kulcsőrző saját privát kulcsával. Az eljárás a 2.15. fejezetben, Második nap: a Nexus üzemeltetése található.

Kulcsőrzői kulcs készítése

A kulcsőrzőt egy age kulcs nyilvános fele azonosítja, amelyet címzettnek (recipient) nevezünk. Minden kulcsőrző a saját gépén készíti el a saját kulcsát, és Önnek csak a címzettet adja át:

age-keygen -o custodian.key

A fájl # public key: sora a címzett, amely age1 előtaggal kezdődik. A Macet használó kulcsőrzők a Mac Secure Enclave-jében is tarthatják a kulcsot, így a privát fél soha nem hagyja el a chipet, és minden használat ujjlenyomatot kér:

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

Ez a címzett age1se1 előtaggal kezdődik. A custody Job ötféle címzettformátumra képes titkosítani: age1 (X25519), age1tag1 és age1tagpq1 (tag), age1pq1 (hibrid posztkvantum) és age1se1 (Secure Enclave). Minden más bővítményformátumot elutasít, például az age1yubikey1-t; az ilyen kulcsot inkább az elfogadott formák valamelyikében adja meg.

A chart generáláskor ellenőrzi mindegyik címzettet. Az elgépelt címzett megbukik a bech32 ellenőrzőösszeg-vizsgálaton, és a rendszer elutasítja, így soha semmi nem kerül lezárásra olyan kulccsal, amely senkinél sincs meg. Ha valaki véletlenül privát kulcsot illeszt be a listába, a chart anélkül utasítja el, hogy visszakiírná a képernyőre. A chart saját values fájljaiban szereplő példacímzettet is elutasítja (KEYS_CUSTODIAN_EXAMPLE); annak a privát fele senkinél sincs meg.

Hány kulcsőrző legyen

Minden részlet minden kulcsőrző számára titkosítva van, így bármelyik kulcsőrző egyedül is képes a feloldásra. A több kulcsőrző több helyreállítási lehetőséget és több olyan embert jelent, akik egyedül is eljárhatnak. A Harrow-nál hármat választottunk: Aoifét, engem és egy Secure Enclave kulcsot egy tartalék laptopon, amely a kikötő széfjében van. Kettő a legkevesebb, amit elfogadnék. Az egyetlen kulcsőrző egyetlen hibapontot (single point of failure) jelent, aki előbb-utóbb szabadságon lesz, amikor egy csomópont újraindul.

A kiadás kiválasztása

A edition értéke community vagy enterprise, és a enterprise.enabled értékének egyeznie kell vele. A chart elutasítja az eltérést, és elutasít minden olyan kiadást, amely nem e kettő valamelyike.

A kiadás azt is eldönti, hogy mely képfájlokat telepíti. Minden chartcsomag tartalmaz egy képfájl-zárolást (images lock), vagyis az összes képfájl digest szerinti listáját az adott kiadáshoz. A Community telepítés csak a Community képfájlokat használja. Az Enterprise telepítés az Enterprise zárolást használja, amely a Community képfájlokból és az Enterprise buildekből áll, és a letöltéshez az Ön Adverant-fiókjából származó pull tokent használja. A 2.4. fejezet, Kiadás beszerzése és ellenőrzése elmagyarázza a zárolást, a 2.2. fejezet, Kiadások a motorháztető alatt pedig bemutatja, mit tartalmaznak az egyes kiadások.

Nem kell véglegesen döntenie. A Community telepítés helyben (in place) átállítható Enterprise-ra, megtartva a felhasználókat, a fájlokat és az előzményeket; a 2.7. fejezet, Az Enterprise telepítése és a licenc alkalmazása megmutatja, hogyan. A Harrow-nál a próbaüzemhez a Communityt futtattuk, majd hat héttel később váltottunk.

A licenc soha nem része ennek a tervnek. Nem chart-érték és nem felcsatolt fájl: a telepítés után importálja a konzolon, a nexusctl eszközön vagy az API-n keresztül.

A szállítási forma kiválasztása

Forma Mikor megfelelő Fejezet
Helm chart a registry.adverant.ai tárolóból Saját Kubernetes klaszter, útvonallal a registry felé 2.6 és 2.7
nexusctl install Ugyanaz a klaszter, ahol az előzetes ellenőrzést és az aláírás-ellenőrzést a rendszer elvégzi Ön helyett 2.6
nexusctl install --single-node Egyetlen gép, ahol a nexusctl a klasztert is felépíti 2.8
A telepítő lemezképfájl Fizikai szerver (bare server) vagy virtuális gép (VM), amelyet inkább nem készítene elő kézzel 2.9
Az offline csomag Egyáltalán nincs kifelé vezető útvonal; a képfájlok és a chart lemezen érkeznek 2.10

A chart minden formában ugyanaz. Ami változik, az az, hogy ki hozza létre a klasztert, és honnan származnak a képfájlok.

A kiadás beszerzése
A kiadás beszerzése
Ez a kiadási oldal az Adverant-fiókban. Figyelje meg az egyértelmű nyilatkozatot arról, hogy mit ígér egy alfa kiadás, a méretet és az aláírást minden fájl mellett, valamint a letöltés ellenőrzésére szolgáló offline parancsokat.

A tervezési munkalap

Ez a Harrow munkalapja, ahogyan Aoife jóváhagyta. Másolja le a bal oldali két oszlopot, és töltse ki a jobb oldalit a saját telepítéséhez.

Döntés Values kulcs vagy parancs Harrow Port Authority
Kubernetes és verzió (az előzetes ellenőrzés kiolvassa) k3s v1.33.6+k3s1, három csomópont
Kube kontextus a telepítéshez --context harrow-prod
Névtér --namespace nexus
Kiadás edition, enterprise.enabled community a próbaüzemhez, majd enterprise
Képfájl-tároló (image registry) global.imageRegistry registry.adverant.ai
Tartomány global.domain harrow.example
Konzol címe hosts.console console.harrow.example
API címe hosts.api api.harrow.example
Bejelentkezési cím hosts.auth auth.harrow.example
TLS a peremen (edge) tls.mode, tls.existingSecret existing, harrow-public-tls Secret a Harrow belső CA-jától
Ingress osztály ingress.className traefik
Ingress névtér networkPolicy.ingressNamespace kube-system
Tárolóosztály storage.className local-path
Adattárak dataTier.<store>.mode Mind in-cluster, alapértelmezett méretek
Kimenő tartományok networkPolicy.externalEgressCIDRs Csak a levelezőátjáró tartománya
Telepítési név (végleges) keys.installationName harrow-port-authority
Kulcsőrzők (gyakorlatilag végleges) keys.custody.recipients Három: Aoife Brennan, Tomás Reilly, a széfben lévő laptop (age1se1)
Grafikus csomópontok (az előzetes ellenőrzés kiolvassa) Nincs az internetkapcsolattal rendelkező próbaüzemhez; hosztolt modell a Harrow saját kulcsával
Első adminisztrátor nexusctl claim-code --administrator aoife.brennan@harrow.example

Ezen a lapon két sor nem vonható vissza: a telepítés neve, valamint a kulcsőrzők abban az értelemben, hogy ha mindegyikük elvész, a kulcstár is elvész. Ezt a kettőt hagyassa jóvá valakivel, akinek megvan a jogosultsága ahhoz, hogy igent mondjon. Minden más csupán egy values-módosítás.

Ha elkészült a munkalappal, lépjen tovább a 2.4. fejezetre, Kiadás beszerzése és ellenőrzése, és töltse le a kiadást.