AutentificareProgramați o prezentare

Capitolul 2.3

Planificarea unei instalări

Ce necesită o instalare Nexus pe Kubernetes înainte de a tasta o comandă, cât de mare este și cele două decizii ireversibile: numele instalării și custozii cheilor. Se încheie cu fișa de planificare completată pentru Harrow Port Authority.

Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

16 minute de lectură

Când am instalat Nexus la Harrow Port Authority, rularea comenzilor a durat o după-amiază. Planificarea a durat o săptămână, iar cea mai mare parte din acea săptămână s-a dus pe două întrebări care nu au nicio legătură cu Kubernetes: cum urma să numim instalarea și ce persoane aveau să dețină cheile sale de recuperare. Ambele răspunsuri sunt permanente. Orice altceva din acest capitol poate fi modificat ulterior cu un fișier de valori și o comandă helm upgrade.

Sunt Tomás Reilly, inginerul de platformă de la Harrow. Harrow rulează două instalări. Acest capitol o planifică pe cea conectată din rețeaua noastră corporativă, unde am testat mai întâi ediția Community într-un proiect pilot. Rețeaua de operațiuni a portului, care nu are rută către internet, a primit propria instalare mai târziu; capitolul 2.10, Instalarea izolată de rețea (air-gapped), acoperă acest subiect. Acest capitol reprezintă ceea ce mi-aș fi dorit să am în prima dimineață: clusterul pe care îl așteaptă Nexus, numele la care răspunde, cât de mult solicită nodurile dumneavoastră și deciziile pe care trebuie să le stabiliți cu directorul IT înainte de instalare. Se încheie cu fișa de lucru pe care Aoife Brennan, directoarea noastră IT, a aprobat-o înainte să începem. Capitolul 2.4, Obținerea și verificarea unei versiuni, acoperă descărcarea și verificarea versiunii, iar capitolul 2.5, Verificarea prealabilă cu nexusctl, vă verifică clusterul în raport cu tot ce este prezentat aici.

Ce trebuie să aibă clusterul

Nexus se instalează ca un singur chart Helm, nexus, versiunea 1.0.0-alpha.1. Chart-ul conține serviciile platformei și nivelul lor de date și refuză instalarea pe un cluster căruia îi lipsesc elementele de mai jos.

Cerință Ce așteaptă Nexus De ce
Kubernetes 1.33 sau o versiune ulterioară. Testat pe k3s v1.33.6+k3s1 Proprietatea kubeVersion a chart-ului este >=1.33.0-0, iar helm install o impune
cert-manager v1.21.3, instalat înainte de Nexus Chart-ul își creează propria autoritate de certificare (CA) locală și certificatele pe care serviciile sale le folosesc pentru a comunica între ele
Helm v4 (noi am folosit v4.3.1) Helm 4 așteaptă în mod implicit finalizarea Job-urilor de tip hook ale chart-ului, de care depinde instalarea
O clasă de stocare Una marcată ca implicită sau una pe care o numiți în storage.className Fiecare depozit de date revendică un volum persistent
O clasă de ingress Una marcată ca implicită sau una pe care o numiți în ingress.className Cele trei adrese publice sunt resurse Ingress networking.k8s.io/v1 standard
Porturile 80 și 443 Deschise pe controllerul de ingress, ca un Service de tip LoadBalancer sau NodePort Utilizatorii accesează Nexus prin intermediul controllerului de ingress
Arhitectură Noduri linux/amd64 sau linux/arm64 Fiecare imagine este construită pentru ambele arhitecturi

Două lucruri lipsesc din acel tabel în mod intenționat. Nexus nu are nevoie de service mesh: criptarea TLS reciprocă (mTLS, Transport Layer Security în ambele direcții) între servicii provine de la autoritatea de certificare (CA) locală a chart-ului, prin intermediul cert-manager. Chart-ul are o cheie istio.enabled a cărei valoare implicită este false, iar dumneavoastră ar trebui să o lăsați așa. De asemenea, Nexus nu are nevoie de un motor propriu de politici de admisie.

Pe stația dumneavoastră de lucru veți avea nevoie de kubectl, Helm v4, cosign v3 pentru verificarea semnăturilor, age pentru crearea cheilor de custode și nexusctl, interfața în linie de comandă (CLI) a operatorului Nexus. Capitolul 2.4, Obținerea și verificarea unei versiuni, indică unde se află fiecare descărcare Nexus.

Trei adrese

Fiecare instalare răspunde la trei nume de gazdă (host). Chart-ul le numește identitatea instalării, iar fiecare serviciu refuză să pornească fără ele.

Cheie în fișierul de valori Numele folosit la Harrow Ce răspunde acolo
hosts.console console.harrow.example Consola, aplicația web în care se autentifică utilizatorii
hosts.api api.harrow.example Gateway-ul, care deservește interfața de programare a aplicațiilor (API) și rutează fiecare cerere de inteligență artificială (IA)
hosts.auth auth.harrow.example Serviciul de autentificare, nexus-auth

global.domain reține domeniul sub care se află cele trei, harrow.example în cazul nostru. Fiecare gazdă este un nume complet în sine și se poate afla sub orice domeniu pe care îl controlați. Noi le-am păstrat pe toate trei sub un singur domeniu, deoarece un singur certificat le putea acoperi astfel pe toate.

Creați o înregistrare în sistemul de nume de domenii (DNS) pentru fiecare dintre cele trei, care să indice adresa controllerului dumneavoastră de ingress. Faceți acest lucru înainte de verificarea prealabilă (preflight). nexusctl preflight caută fiecare nume de pe stația dumneavoastră de lucru și oprește instalarea dacă vreunul dintre ele nu are înregistrare, deoarece o persoană nu poate accesa un nume care nu se rezolvă.

În stânga, trei nume DNS: console.harrow.example, api.harrow.example și auth.harrow.example, fiecare cu o săgeată către o casetă etichetată „controller de ingress, porturile 80 și 443”. Din acea casetă, trei săgeți duc într-o casetă mai mare etichetată „namespace nexus”: săgeata console către „nexus-alpha :3000”, săgeata api către „nexus-gateway :9092” și săgeata auth către „nexus-auth :9101”. Un chenar întrerupt în jurul namespace-ului este etichetat „refuz implicit; doar namespace-ul de ingress poate accesa aceste trei servicii”.
Cum ajung cele trei nume publice la serviciile din spatele lor.

Alegerea modului de terminare TLS

Cheia tls.mode a chart-ului decide cine deține certificatele pentru cele trei adrese publice. Există trei opțiuni și puteți schimba între ele ulterior printr-un upgrade.

tls.mode Ce furnizați dumneavoastră Ce face chart-ul
existing (valoarea implicită) Un Secret TLS Kubernetes în namespace-ul nexus, numit în tls.existingSecret Toate cele trei resurse Ingress folosesc acel unic Secret
cert-manager Un ClusterIssuer pe care îl rulați, numit în tls.clusterIssuer Adaugă adnotări fiecărui Ingress astfel încât cert-manager să emită nexus-console-tls, nexus-api-tls și nexus-auth-tls
none Un element în fața clusterului care termină conexiunea TLS, cum ar fi propriul dumneavoastră load balancer Generează resursele Ingress fără nicio secțiune TLS

Cu existing, un singur certificat deservește toate cele trei gazde, deci trebuie să le numească pe toate trei, fie ca trei nume alternative ale subiectului (SAN), fie ca un certificat wildcard pentru domeniul dumneavoastră. Noi am folosit un certificat de la autoritatea de certificare (CA) internă a Harrow. Verificarea prealabilă citește Secretul înainte de instalare și emite un avertisment atunci când certificatul său expiră în mai puțin de 30 de zile.

Cu cert-manager și un emițător Automatic Certificate Management Environment (ACME), chart-ul nu adaugă nicio redirecționare proprie, astfel încât o cerere /.well-known/acme-challenge/ pe portul 80 ajunge la rezolvitor neatinsă. Nu adăugați o redirecționare de la HTTP la HTTPS la nivelul controllerului de ingress care să se execute înaintea căii de validare (challenge path); un certificat care nu se poate reînnoi eșuează în tăcere, săptămâni mai târziu.

Orice ați alege pentru marginea publică a rețelei (public edge), serviciile din interiorul namespace-ului comunică întotdeauna prin TLS emis de autoritatea de certificare (CA) locală a chart-ului. Această parte nu este opțională și acesta este motivul pentru care cert-manager este o cerință prealabilă chiar și atunci când tls.mode este existing sau none.

Ce părăsește clusterul și ce nu

Chart-ul generează o politică de rețea de refuz implicit (default-deny) pentru namespace-ul nexus. După aceea, sunt permise doar următoarele fluxuri:

  • traficul între pod-urile Nexus din interiorul namespace-ului;
  • interogările DNS către serviciul DNS al clusterului;
  • serverul API Kubernetes, pentru puținele servicii care verifică token-urile sarcinilor de lucru (workload tokens);
  • namespace-ul controllerului de ingress, către cele trei resurse Service publice;
  • orice intervale Classless Inter-Domain Routing (CIDR) pe care le enumerați în networkPolicy.externalEgressCIDRs.

Această ultimă listă este goală în mod implicit. Dacă veți folosi un releu de e-mail (mail relay) sau un server de modele în afara clusterului, intervalul acestuia trebuie trecut acolo. Telemetria este dezactivată și rămâne dezactivată: schema acceptă doar telemetry.enabled: false, iar raportarea proprie a utilizării din depozitele de date este, de asemenea, dezactivată.

Chart-ul citește adresele serverului API din cluster atunci când instalați. Dacă contul dumneavoastră nu poate citi resursele Endpoints kubernetes din namespace-ul default, furnizați-le chiar dumneavoastră în networkPolicy.apiServerCIDRs, ca intervale /32. proxy.trustedCIDRs numește rețeaua de pod-uri pe care se află controllerul dumneavoastră de ingress, astfel încât nexus-auth să știe în al cui antet X-Forwarded-For să aibă încredere. Valoarea implicită, 10.42.0.0/16, este rețeaua de pod-uri a k3s.

Dimensionare

Cererile implicite ale chart-ului însumează aproximativ 2.05 nuclee de unitate centrală de procesare (CPU) și 6.7 GiB de memorie. Aceasta este capacitatea pe care o rezervă planificatorul (scheduler); limitele sunt mai mari, iar depozitele de date cresc până la acestea pe măsură ce adăugați utilizatori și fișiere.

Componentă CPU solicitat Memorie solicitată
Nouă servicii de platformă (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 nuclee 2.6 GiB
Serviciul de chei, nexus-keys 0.05 nuclee 64 MiB
PostgreSQL 0.25 nuclee 1 GiB
Neo4j 0.25 nuclee 2 GiB
Valkey, Qdrant și depozitul de obiecte împreună 0.25 nuclee 640 MiB
Cele două servere OpenBao ale depozitului de chei 0.15 nuclee 384 MiB

Volumele implicite însumează 142 GiB:

Depozit de date Cheie în fișierul de valori Dimensiune implicită
PostgreSQL 16 cu PostGIS 3 și pgvector 0.8 dataTier.postgres.size 50Gi
Depozit de obiecte (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Depozitul de chei și deblocatorul său (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi și 1Gi
Chitanțe ale serviciului de chei keys.receiptsStorage 1Gi

Pentru un singur nod, planificați 8 vCPU, 32 GiB de memorie cu acces aleatoriu (RAM) și o unitate solid-state (SSD) de 250 GB. Pentru o evaluare, 4 vCPU, 16 GiB și 200 GB vor fi suficiente. Imaginea de disc a instalatorului refuză o mașină cu mai puțin de 16 GiB de memorie (consultați capitolul 2.9, Imaginea de disc a instalatorului), și aș trata această valoare drept pragul minim peste tot.

Nodurile grafice sunt opționale. Fără un nod care să ofere o unitate de procesare grafică (GPU), asistentul răspunde printr-un model găzduit, folosind propria cheie a organizației. Verificarea prealabilă raportează acest lucru ca pe un avertisment, niciodată ca pe o eroare. Capitolul 2.14, Furnizori și modele de IA, acoperă ambele variante.

Fiecare depozit poate rula și în afara clusterului: setați dataTier.<store>.mode la external și numiți gazda acestuia și un Secret. Un PostgreSQL extern are nevoie de un cont de superutilizator pentru inițializarea (bootstrap) instalării și de un certificat pe care Nexus să îl poată verifica. Capitolul 2.11, Variații: depozite externe, TLS și ingress, acoperă acest aspect. Dacă le păstrați în cluster, plasați-le pe o clasă de stocare care are discuri reale în spate. Baza de date este componenta căreia îi veți simți cel mai mult lipsa dacă discul local al unui nod cedează.

Numele instalării este permanent

keys.installationName este numele pe care operatorii îl dau acestei instalări. Trebuie să respecte expresia ^[a-z][a-z0-9-]{0,62}$: o literă mică, urmată de până la 62 de litere mici, cifre sau cratime.

Prima dată când pornește depozitul de chei, acesta creează identitatea instalării sub acest nume, iar acea identitate este fixată definitiv. O licență de la Adverant este emisă pentru acea identitate, astfel încât o licență creată pentru o instalare este refuzată pe o alta cu eroarea LICENCE_OTHER_INSTALLATION. Redenumirea ar însemna o instalare nouă, o identitate nouă și licențe noi.

Chart-ul nu are o valoare implicită pentru nume. Refuză o instalare fără nume (INSTALLATION_NAME_MISSING) și refuză numele de exemplu din propriile sale fișiere cu valori de exemplu (INSTALLATION_NAME_EXAMPLE). Verificarea prealabilă le raportează pe amândouă înainte să ajungeți atât de departe.

La Harrow am petrecut mai mult timp pe acest subiect decât mi-ar plăcea să recunosc. Ne-am oprit asupra harrow-port-authority: numește organizația, nu spune nimic despre clusterul pe care rulează și va rămâne valabil și atunci când hardware-ul va fi înlocuit. Evitați nume precum prod-k3s-2, care descriu mașinile de astăzi.

Custodia cheilor

Nexus păstrează cheile fiecărei organizații în propriul său depozit de chei, în interiorul clusterului. Nu îl operați zi de zi, dar decideți, înainte de instalare, cine îl poate repune în funcțiune după o repornire. Aceasta este decizia care costă cel mai mult dacă o greșiți.

Depozitul de chei este format din două servere OpenBao. Cel principal, openbao, deține cheile și se deblochează (unseals) singur prin intermediul unui al doilea server, mai mic, openbao-unsealer. Deblocatorul (unsealer) este sigilat cu schema lui Shamir: cinci fragmente (shares), dintre care oricare trei îl deschid. Când instalați, un Job de custodie inițializează ambele servere în interiorul clusterului. În memoria acelui Job, acesta criptează fragmentele deblocatorului și cheile de recuperare ale depozitului de chei pentru fiecare custode pe care îl numiți, stochează doar textul cifrat (în resursele Secret openbao-unseal-shares-encrypted și openbao-recovery-keys-encrypted) și revocă ambele token-uri root înainte de a se încheia. Niciun fragment în text clar nu ajunge vreodată pe un disc sau într-un jurnal (log).

După orice repornire a nodului pe care rulează deblocatorul, acesta pornește sigilat. Depozitul de chei îl așteaptă, iar nimic din ceea ce are nevoie de o cheie nu funcționează până când un custode nu îl deblochează. Acest lucru necesită o singură decriptare cu propria cheie privată a custodelui. Procedura se află în capitolul 2.15, A doua zi: operarea Nexus.

Crearea unei chei de custode

Un custode este desemnat prin jumătatea publică a unei chei age, numită destinatarul său (recipient). Fiecare custode își creează propria cheie pe propria mașină și vă oferă doar destinatarul:

age-keygen -o custodian.key

Linia # public key: a fișierului este destinatarul, începând cu age1. Un custode cu un Mac poate păstra cheia în Secure Enclave al Mac-ului în schimb, astfel încât jumătatea privată nu părăsește niciodată cipul și fiecare utilizare solicită o amprentă:

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

Acel destinatar începe cu age1se1. Job-ul de custodie criptează către cinci forme de destinatar: age1 (X25519), age1tag1 și age1tagpq1 (tag), age1pq1 (hibrid post-cuantic) și age1se1 (Secure Enclave). Refuză orice altă formă de plugin, cum ar fi age1yubikey1; numiți acea cheie într-una dintre formele acceptate în schimb.

Chart-ul verifică fiecare destinatar atunci când generează șabloanele. Unul scris greșit eșuează la suma de control bech32 și este refuzat, astfel încât nimic nu este vreodată sigilat către o cheie pe care nu o deține nimeni. Dacă cineva lipește din greșeală o cheie privată în listă, chart-ul o refuză fără a o afișa în răspuns. Destinatarul de exemplu din propriile fișiere de valori ale chart-ului este, de asemenea, refuzat (KEYS_CUSTODIAN_EXAMPLE); nimeni nu deține jumătatea sa privată.

Câți custozi

Fiecare fragment este criptat pentru fiecare custode, astfel încât oricare custode poate debloca singur. Mai mulți custozi înseamnă mai multe modalități de recuperare și mai multe persoane care pot acționa fiecare pe cont propriu. Noi am ales trei la Harrow: Aoife, eu și o cheie Secure Enclave pe un laptop de rezervă care stă în seiful portului. Doi este minimul pe care l-aș accepta. Unul singur reprezintă un punct unic de eșec care, mai devreme sau mai târziu, va fi în concediu atunci când repornește un nod.

Alegerea ediției

edition este community sau enterprise, iar enterprise.enabled trebuie să corespundă cu aceasta. Chart-ul refuză o nepotrivire și refuză orice ediție care nu este una dintre cele două.

Ediția decide, de asemenea, ce imagini instalați. Fiecare pachet chart conține un fișier de blocare a imaginilor (images lock), lista fiecărei imagini după amprenta sa (digest), pentru o singură ediție. O instalare Community preia doar imagini Community. O instalare Enterprise preia fișierul de blocare Enterprise, care conține imaginile Community plus versiunile Enterprise, și le descarcă folosind un token de descărcare (pull token) din contul dumneavoastră Adverant. Capitolul 2.4, Obținerea și verificarea unei versiuni, explică fișierul de blocare, iar capitolul 2.2, Edițiile sub capotă, explică ce conține fiecare ediție.

Nu trebuie să decideți definitiv. O instalare Community trece la Enterprise pe loc, păstrându-și utilizatorii, fișierele și istoricul; capitolul 2.7, Instalarea ediției Enterprise și aplicarea unei licențe, arată cum. Noi am rulat Community pentru proiectul pilot de la Harrow și am făcut trecerea șase săptămâni mai târziu.

Licența nu face niciodată parte din acest plan. Nu este o valoare în chart sau un fișier montat: o importați după instalare, prin intermediul consolei, al nexusctl sau al API-ului.

Alegerea formei de livrare

Formă Când se potrivește Capitol
Chart Helm din registry.adverant.ai Propriul dumneavoastră cluster Kubernetes, cu o rută către registru 2.6 și 2.7
nexusctl install Același cluster, cu verificarea prealabilă și verificarea semnăturii rulate pentru dumneavoastră 2.6
nexusctl install --single-node O singură mașină, unde nexusctl configurează și clusterul 2.8
Imaginea de disc a programului de instalare Un server fizic (bare metal) sau o mașină virtuală (VM) pe care ați prefera să nu o pregătiți manual 2.9
Pachetul offline Nicio rută către exterior; imaginile și chart-ul vin pe un disc 2.10

Chart-ul este același în fiecare formă. Ceea ce se schimbă este cine creează clusterul și de unde provin imaginile.

Obțineți versiunea
Obțineți versiunea
Aceasta este pagina versiunii din contul Adverant. Observați declarația clară despre ceea ce promite o versiune alpha, dimensiunea și semnătura de lângă fiecare fișier și comenzile offline pentru verificarea unei descărcări.

Fișa de planificare

Aceasta este fișa de la Harrow, așa cum a aprobat-o Aoife. Copiați cele două coloane din stânga și completați-o pe cea din dreapta pentru propria dumneavoastră instalare.

Decizie Cheie în fișierul de valori sau comandă Harrow Port Authority
Kubernetes și versiunea (verificarea prealabilă o citește) k3s v1.33.6+k3s1, trei noduri
Contextul Kube pentru instalare --context harrow-prod
Namespace --namespace nexus
Ediție edition, enterprise.enabled community pentru proiectul pilot, apoi enterprise
Registrul de imagini global.imageRegistry registry.adverant.ai
Domeniu global.domain harrow.example
Adresa consolei hosts.console console.harrow.example
Adresa API hosts.api api.harrow.example
Adresa de autentificare hosts.auth auth.harrow.example
TLS la marginea rețelei (edge) tls.mode, tls.existingSecret existing, Secretul harrow-public-tls de la autoritatea de certificare (CA) internă a Harrow
Clasa de ingress ingress.className traefik
Namespace-ul de ingress networkPolicy.ingressNamespace kube-system
Clasa de stocare storage.className local-path
Depozite de date dataTier.<store>.mode Toate in-cluster, dimensiuni implicite
Intervale de ieșire (outbound) networkPolicy.externalEgressCIDRs Doar intervalul releului de e-mail
Numele instalării (permanent) keys.installationName harrow-port-authority
Custozi (în practică, permanenți) keys.custody.recipients Trei: Aoife Brennan, Tomás Reilly, laptopul din seif (age1se1)
Noduri grafice (verificarea prealabilă o citește) Niciunul pentru proiectul pilot conectat; model găzduit cu propria cheie a Harrow
Primul administrator nexusctl claim-code --administrator aoife.brennan@harrow.example

Două rânduri din acea fișă sunt ireversibile: numele instalării și custozii, în sensul că pierderea tuturor duce la pierderea depozitului de chei. Obțineți aprobarea pentru aceste două rânduri de la cineva care are autoritatea de a spune da. Orice altceva este o modificare în fișierul de valori.

Odată finalizată fișa de lucru, treceți la capitolul 2.4, Obținerea și verificarea unei versiuni, și descărcați versiunea.