Zaloguj sięUmów spotkanie

Rozdział 2.3

Planowanie instalacji

Czego wymaga instalacja systemu Nexus na platformie Kubernetes przed wpisaniem polecenia, jak duża jest, oraz dwie decyzje, których nie można cofnąć: nazwa instalacji i depozytariusze kluczy. Kończy się wypełnionym arkuszem planowania dla Harrow Port Authority.

Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Czas czytania: 16 min

Gdy instalowaliśmy system Nexus w Harrow Port Authority, wykonanie poleceń zajęło jedno popołudnie. Planowanie trwało tydzień, z czego większość czasu pochłonęły dwa pytania niemające nic wspólnego z Kubernetes: jak nazwiemy tę instalację i kto będzie przechowywał jej klucze odzyskiwania. Obie te decyzje są nieodwracalne. Wszystko inne opisane w tym rozdziale można zmienić później za pomocą pliku wartości i polecenia helm upgrade.

Nazywam się Tomás Reilly i jestem inżynierem platformy w Harrow. W Harrow działają dwie instalacje. W tym rozdziale zaplanowano instalację z dostępem do internetu w naszej sieci korporacyjnej, gdzie najpierw przeprowadziliśmy pilotaż edycji Community. Sieć operacyjna portu, która nie ma trasy do internetu, otrzymała własną instalację później; omawia to rozdział 2.10, Instalacja w środowisku odizolowanym (air-gapped). Ten rozdział zawiera wszystko to, co sam chciałbym mieć pierwszego dnia rano: informacje o klastrze wymaganym przez Nexus, nazwach, na które odpowiada, wymaganiach wobec węzłów oraz decyzjach, które należy uzgodnić z szefem działu IT przed instalacją. Kończy się on arkuszem roboczym, który Aoife Brennan, nasza szefowa IT, zatwierdziła przed rozpoczęciem prac. Rozdział 2.4, Pobieranie i weryfikacja wydania, opisuje pobieranie i sprawdzanie wydania, a rozdział 2.5, Kontrola wstępna z nexusctl, weryfikuje Państwa klaster pod kątem wszystkich opisanych tu wymogów.

Co musi posiadać klaster

Nexus instaluje się jako jeden pakiet Helm chart, nexus, w wersji 1.0.0-alpha.1. Pakiet ten obejmuje usługi platformowe oraz ich warstwę danych i odmawia instalacji w klastrze, w którym brakuje poniższych elementów.

Wymaganie Czego oczekuje Nexus Dlaczego
Kubernetes 1.33 lub nowszy. Przetestowano na k3s v1.33.6+k3s1 Wartość kubeVersion pakietu chart to >=1.33.0-0, a helm install ją egzekwuje
cert-manager v1.21.3, zainstalowany przed systemem Nexus Pakiet chart tworzy własne lokalne centrum certyfikacji (CA) oraz certyfikaty, których usługi używają do wzajemnej komunikacji
Helm v4 (my użyliśmy wersji v4.3.1) Helm 4 domyślnie czeka na zakończenie zadań typu hook Job pakietu chart, od których zależy instalacja
Klasa pamięci masowej (StorageClass) Jedna oznaczona jako domyślna lub wskazana w storage.className Każdy magazyn danych rezerwuje wolumen trwały (PersistentVolume)
Klasa ingress (IngressClass) Jedna oznaczona jako domyślna lub wskazana w ingress.className Trzy adresy publiczne to zwykłe zasoby Ingress typu networking.k8s.io/v1
Porty 80 i 443 Otwarte na kontrolerze ingress, jako usługa typu LoadBalancer lub NodePort Użytkownicy łączą się z systemem Nexus przez kontroler ingress
Architektura Węzły linux/amd64 lub linux/arm64 Każdy obraz jest budowany dla obu tych architektur

W powyższej tabeli celowo pominięto dwie rzeczy. Nexus nie potrzebuje siatki usług (service mesh): dwustronny TLS (mTLS, Transport Layer Security w obu kierunkach) pomiędzy usługami pochodzi z lokalnego CA pakietu chart za pośrednictwem cert-manager. Pakiet chart posiada klucz istio.enabled, który domyślnie ma wartość false i należy go tak pozostawić. Nexus nie wymaga też własnego silnika polityk dopuszczania (admission policy engine).

Na stacji roboczej przydadzą się Państwu: kubectl, Helm v4, cosign v3 do sprawdzania podpisów, age do tworzenia kluczy depozytariuszy oraz nexusctl, czyli wiersz poleceń (CLI) operatora Nexus. Rozdział 2.4, Pobieranie i weryfikacja wydania, wskazuje, gdzie znajdują się poszczególne pliki systemu Nexus do pobrania.

Trzy adresy

Każda instalacja odpowiada pod trzema nazwami hostów. Pakiet chart nazywa je tożsamością instalacji, a żadna usługa nie uruchomi się bez nich.

Klucz wartości Nazwa w Harrow Co odpowiada pod tym adresem
hosts.console console.harrow.example Konsola, czyli aplikacja internetowa, do której logują się użytkownicy
hosts.api api.harrow.example Brama (gateway), która obsługuje interfejs programowania aplikacji (API) i kieruje każdym żądaniem sztucznej inteligencji (AI)
hosts.auth auth.harrow.example Usługa logowania, nexus-auth

global.domain przechowuje domenę, w której znajdują się wszystkie trzy hosty – w naszym przypadku harrow.example. Każdy host jest sam w sobie pełną nazwą i może znajdować się w dowolnej kontrolowanej przez Państwa domenie. My umieściliśmy wszystkie trzy w jednej domenie, ponieważ pozwala to objąć je jednym certyfikatem.

Dla każdej z tych trzech nazw należy utworzyć rekord w systemie nazw domen (DNS), wskazujący adres kontrolera ingress. Należy to zrobić przed kontrolą wstępną (preflight). nexusctl preflight sprawdza każdą nazwę z poziomu stacji roboczej i przerywa instalację, jeśli którakolwiek z nich nie ma rekordu, ponieważ użytkownik nie połączy się z nazwą, której nie da się rozwiązać.

Po lewej stronie trzy nazwy DNS: console.harrow.example, api.harrow.example oraz auth.harrow.example, z których każda prowadzi strzałką do jednego bloku z etykietą „ingress controller, ports 80 and 443”. Z tego bloku trzy strzałki prowadzą do większego bloku z etykietą „namespace nexus”: strzałka console do „nexus-alpha :3000”, strzałka api do „nexus-gateway :9092”, a strzałka auth do „nexus-auth :9101”. Przerywana ramka wokół przestrzeni nazw ma etykietę „default deny; only the ingress namespace may reach these three”.
W jaki sposób trzy nazwy publiczne docierają do stojących za nimi usług.

Wybór miejsca terminacji TLS

Parametr tls.mode pakietu chart decyduje o tym, kto przechowuje certyfikaty dla trzech adresów publicznych. Dostępne są trzy opcje, a wybór można później zmienić podczas aktualizacji.

tls.mode Co Państwo zapewniają Co robi pakiet chart
existing (domyślnie) Obiekt Secret TLS w Kubernetes w przestrzeni nazw nexus, o nazwie podanej w tls.existingSecret Wszystkie trzy zasoby Ingress używają tego jednego obiektu Secret
cert-manager Utrzymywany przez Państwa zasób ClusterIssuer, o nazwie podanej w tls.clusterIssuer Dodaje adnotacje do każdego zasobu Ingress, aby cert-manager wystawił nexus-console-tls, nexus-api-tls oraz nexus-auth-tls
none Element przed klastrem, który kończy połączenie TLS (terminacja TLS), np. Państwa własny load balancer Renderuje zasoby Ingress bez sekcji TLS

W przypadku existing jeden certyfikat obsługuje wszystkie trzy hosty, musi więc zawierać nazwy wszystkich trzech – albo jako trzy alternatywne nazwy podmiotu (SAN), albo jako certyfikat typu wildcard dla domeny. My użyliśmy certyfikatu z wewnętrznego CA w Harrow. Kontrola wstępna (preflight) odczytuje obiekt Secret przed instalacją i wyświetla ostrzeżenie, jeśli ważność certyfikatu wygasa w ciągu 30 dni.

W przypadku cert-manager i wystawcy korzystającego z protokołu ACME (Automatic Certificate Management Environment) pakiet chart nie dodaje własnego przekierowania, dzięki czemu żądanie /.well-known/acme-challenge/ na porcie 80 dociera do mechanizmu weryfikacji bez zmian. Nie należy dodawać przekierowania z HTTP na HTTPS na kontrolerze ingress, które uruchamiałoby się przed ścieżką wyzwania (challenge); certyfikat, którego nie można odnowić, wygaśnie po cichu kilka tygodni później.

Niezależnie od wybranego rozwiązania na publicznym brzegu sieci, usługi wewnątrz przestrzeni nazw zawsze komunikują się przez TLS oparty na lokalnym CA pakietu chart. Ta część nie podlega wyborowi i właśnie dlatego cert-manager jest wymagany nawet wtedy, gdy tls.mode ma wartość existing lub none.

Co opuszcza klaster, a co nie

Pakiet chart renderuje politykę sieciową domyślnej odmowy (default-deny) dla przestrzeni nazw nexus. Po jej zastosowaniu dozwolone są wyłącznie następujące przepływy ruchu:

  • ruch pomiędzy podami systemu Nexus wewnątrz przestrzeni nazw;
  • zapytania DNS do usługi DNS klastra;
  • serwer API Kubernetes, dla kilku usług weryfikujących tokeny obciążeń (workload tokens);
  • przestrzeń nazw kontrolera ingress, do trzech publicznych usług (Services);
  • dowolne zakresy adresów CIDR (Classless Inter-Domain Routing) wymienione na liście networkPolicy.externalEgressCIDRs.

Ta ostatnia lista jest domyślnie pusta. Jeśli będą Państwo korzystać z przekaźnika pocztowego (mail relay) lub serwera modeli poza klastrem, należy tam wpisać jego zakres adresów. Telemetria jest wyłączona i taka pozostaje: schemat akceptuje wyłącznie wartość telemetry.enabled: false, a własne raportowanie użycia w magazynach danych również jest wyłączone.

Podczas instalacji pakiet chart odczytuje adresy serwera API z klastra. Jeśli Państwa konto nie ma uprawnień do odczytu zasobów Endpoints kubernetes w przestrzeni nazw default, należy podać je samodzielnie w networkPolicy.apiServerCIDRs, jako zakresy /32. Parametr proxy.trustedCIDRs określa sieć podów, w której działa kontroler ingress, dzięki czemu nexus-auth wie, czyjemu nagłówkowi X-Forwarded-For może ufać. Wartość domyślna, 10.42.0.0/16, to sieć podów klastra k3s.

Dobór rozmiaru

Domyślne zapotrzebowanie (requests) pakietu chart sumuje się do około 2.05 rdzenia procesora (CPU) i 6.7 GiB pamięci. Tyle rezerwuje harmonogram (scheduler); limity są wyższe, a magazyny danych stopniowo je wypełniają w miarę dodawania użytkowników i plików.

Element Żądane CPU Żądana pamięć
Dziewięć usług platformowych (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 rdzenia 2.6 GiB
Usługa kluczy, nexus-keys 0.05 rdzenia 64 MiB
PostgreSQL 0.25 rdzenia 1 GiB
Neo4j 0.25 rdzenia 2 GiB
Valkey, Qdrant oraz magazyn obiektów łącznie 0.25 rdzenia 640 MiB
Dwa serwery OpenBao magazynu kluczy 0.15 rdzenia 384 MiB

Domyślne wolumeny dają w sumie 142 GiB:

Magazyn Klucz wartości Domyślny rozmiar
PostgreSQL 16 z PostGIS 3 oraz pgvector 0.8 dataTier.postgres.size 50Gi
Magazyn obiektów (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Magazyn kluczy i jego usługa odpieczętowania (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi oraz 1Gi
Potwierdzenia usługi kluczy (receipts) keys.receiptsStorage 1Gi

W przypadku pojedynczego węzłu należy zaplanować 8 vCPU, 32 GiB pamięci o dostępie swobodnym (RAM) oraz dysk półprzewodnikowy (SSD) o pojemności 250 GB. Do celów ewaluacyjnych wystarczy 4 vCPU, 16 GiB RAM i 200 GB dysku. Obraz dysku instalatora odmawia instalacji na maszynie z mniej niż 16 GiB pamięci (zob. rozdział 2.9, Obraz dysku instalatora) i traktowałbym to jako absolutne minimum w każdym przypadku.

Węzły graficzne są opcjonalne. Bez węzła oferującego procesor graficzny (GPU) asystent odpowiada za pośrednictwem modelu hostowanego zewnętrznie, używając własnego klucza organizacji. Kontrola wstępna (preflight) zgłasza to jako ostrzeżenie, a nie błąd. Rozdział 2.14, Dostawcy i modele AI, omawia oba te rozwiązania.

Każdy magazyn danych może również działać poza klastrem: należy ustawić dataTier.<store>.mode na external oraz podać nazwę jego hosta i obiekt Secret. Zewnętrzna baza PostgreSQL wymaga konta superużytkownika na potrzeby inicjalizacji (bootstrap) podczas instalacji oraz certyfikatu, który Nexus może zweryfikować. Omawia to rozdział 2.11, Warianty: zewnętrzne magazyny danych, TLS i ingress. Jeśli pozostawią je Państwo w klastrze, należy umieścić je w klasie pamięci masowej opartej na fizycznych dyskach. Baza danych to element, którego brak odczują Państwo najbardziej w razie awarii lokalnego dysku węzła.

Nazwa instalacji jest stała

keys.installationName to nazwa, jaką operatorzy nadają tej instalacji. Musi ona pasować do wyrażenia ^[a-z][a-z0-9-]{0,62}$: mała litera, a po niej do 62 małych liter, cyfr lub dywizów.

Gdy magazyn kluczy uruchamia się po raz pierwszy, generuje tożsamość instalacji pod tą nazwą i tożsamość ta zostaje przypisana na stałe. Licencja od Adverant jest wystawiana dla tej konkretnej tożsamości, dlatego licencja utworzona dla jednej instalacji zostanie odrzucona na innej z błędem LICENCE_OTHER_INSTALLATION. Zmiana nazwy oznaczałaby nową instalację, nową tożsamość i nowe licencje.

Pakiet chart nie ma domyślnej wartości dla tej nazwy. Odmawia instalacji w przypadku jej braku (INSTALLATION_NAME_MISSING) i odrzuca przykładową nazwę pochodzącą z własnych przykładowych plików wartości (INSTALLATION_NAME_EXAMPLE). Kontrola wstępna zgłasza oba te przypadki, zanim jeszcze dojdą Państwo do etapu instalacji.

W Harrow spędziliśmy nad tym więcej czasu, niż chciałbym przyznać. Zdecydowaliśmy się na harrow-port-authority: nazwa ta wskazuje organizację, nie mówi nic o klastrze, na którym działa, i pozostanie aktualna po wymianie sprzętu. Należy unikać nazw takich jak prod-k3s-2, które opisują dzisiejsze maszyny.

Pieczą nad kluczami

Nexus przechowuje klucze każdej organizacji we własnym magazynie kluczy, wewnątrz klastra. Nie obsługują go Państwo na co dzień, ale przed instalacją muszą Państwo zdecydować, kto będzie mógł przywrócić go do działania po restarcie. To decyzja, która kosztuje najwięcej, jeśli popełni się w niej błąd.

Magazyn kluczy składa się z dwóch serwerów OpenBao. Główny, openbao, przechowuje klucze i odpieczętowywuje się (unseals) za pośrednictwem drugiego, mniejszego serwera, openbao-unsealer. Serwer odpieczętowania (unsealer) jest zapieczętowany za pomocą schematu Shamira: pięć udziałów, z których dowolne trzy go otwierają. Podczas instalacji zadanie powiernicze (custody Job) inicjalizuje oba serwery wewnątrz klastra. W pamięci tego zadania udziały serwera odpieczętowania oraz klucze odzyskiwania magazynu kluczy są szyfrowane dla każdego wskazanego przez Państwa depozytariusza, zapisywany jest wyłącznie szyfrogram (w obiektach Secret openbao-unseal-shares-encrypted i openbao-recovery-keys-encrypted), a przed zakończeniem zadania oba tokeny główne (root tokens) są unieważniane. Żaden jawny udział nigdy nie trafia na dysk ani do logów.

Po każdym restarcie węzła serwera odpieczętowania uruchamia się on w stanie zapieczętowanym. Magazyn kluczy czeka na niego i żadna funkcja wymagająca klucza nie zadziała, dopóki depozytariusz go nie odpieczętuje. Wymaga to jednokrotnego odszyfrowania przy użyciu prywatnego klucza depozytariusza. Procedura ta została opisana w rozdziale 2.15, Dzień drugi: eksploatacja systemu Nexus.

Tworzenie klucza depozytariusza

Depozytariusz jest identyfikowany przez publiczną część klucza age, zwaną odbiorcą (recipient). Każdy depozytariusz tworzy własny klucz na swojej maszynie i przekazuje Państwu wyłącznie odbiorcę:

age-keygen -o custodian.key

Wiersz # public key: w pliku to odbiorca, zaczynający się od age1. Depozytariusz korzystający z komputera Mac może zamiast tego przechowywać klucz w układzie Secure Enclave komputera Mac, dzięki czemu część prywatna nigdy nie opuszcza czipu, a każde użycie wymaga odcisku palca:

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

Taki odbiorca zaczyna się od age1se1. Zadanie powiernicze szyfruje dane dla pięciu form odbiorców: age1 (X25519), age1tag1 oraz age1tagpq1 (tag), age1pq1 (hybrydowy postkwantowy) i age1se1 (Secure Enclave). Odrzuca ono wszelkie inne formy wtyczek, takie jak age1yubikey1; taki klucz należy wskazać w jednej z akceptowanych form.

Pakiet chart sprawdza każdego odbiorcę podczas renderowania. Błędnie wpisany odbiorca nie przechodzi weryfikacji sumy kontrolnej bech32 i zostaje odrzucony, dzięki czemu nic nie zostanie nigdy zapieczętowane kluczem, którego nikt nie posiada. Jeśli ktoś przez pomyłkę wklei na listę klucz prywatny, pakiet chart odrzuci go bez wyświetlania jego treści w komunikacie zwrotnym. Przykładowy odbiorca z własnych plików wartości pakietu chart również jest odrzucany (KEYS_CUSTODIAN_EXAMPLE); nikt nie posiada jego części prywatnej.

Ilu depozytariuszy

Każdy udział jest szyfrowany dla każdego depozytariusza, dzięki czemu dowolny pojedynczy depozytariusz może samodzielnie dokonać odpieczętowania. Większa liczba depozytariuszy oznacza więcej sposobów na odzyskanie dostępu i więcej osób, które mogą działać samodzielnie. W Harrow wybraliśmy troje: Aoife, mnie oraz klucz Secure Enclave na zapasowym laptopie przechowywanym w portowym sejfie. Dwoje to absolutne minimum, jakie bym zaakceptował. Jedna osoba to pojedynczy punkt awarii, który prędzej czy później będzie na urlopie akurat wtedy, gdy zrestartuje się węzeł.

Wybór edycji

edition przyjmuje wartość community lub enterprise, a enterprise.enabled musi się z nią zgadzać. Pakiet chart odmawia działania w przypadku niezgodności i odrzuca każdą edycję, która nie jest jedną z tych dwóch.

Edycja decyduje również o tym, które obrazy są instalowane. Każda paczka z pakietem chart zawiera blokadę obrazów (images lock), czyli listę wszystkich obrazów według ich skrótów (digest) dla danej edycji. Instalacja Community pobiera wyłącznie obrazy Community. Instalacja Enterprise wykorzystuje blokadę Enterprise, która obejmuje obrazy Community oraz kompilacje Enterprise, i pobiera je przy użyciu tokenu pobierania (pull token) z Państwa konta Adverant. Rozdział 2.4, Pobieranie i weryfikacja wydania, wyjaśnia działanie blokady, natomiast rozdział 2.2, Edycje od podszewki, omawia zawartość każdej z edycji.

Nie muszą Państwo podejmować ostatecznej decyzji od razu. Instalację Community można przekształcić w Enterprise w miejscu (in place), zachowując użytkowników, pliki i historię; rozdział 2.7, Instalacja edycji Enterprise i stosowanie licencji, pokazuje, jak to zrobić. W Harrow używaliśmy edycji Community podczas pilotażu i przeszliśmy na wyższą edycję sześć tygodni później.

Licencja nigdy nie jest częścią tego planu. Nie jest wartością w pakiecie chart ani zamontowanym plikiem: importuje się ją po instalacji, za pośrednictwem konsoli, narzędzia nexusctl lub API.

Wybór formy dostarczania

Forma Kiedy się sprawdza Rozdział
Pakiet Helm chart z registry.adverant.ai Państwa własny klaster Kubernetes z trasą sieciową do rejestru 2.6 oraz 2.7
nexusctl install Ten sam klaster, z kontrolą wstępną i weryfikacją podpisu uruchamianymi automatycznie za Państwa 2.6
nexusctl install --single-node Jedna maszyna, na której nexusctl konfiguruje również sam klaster 2.8
Obraz dysku instalatora Serwer fizyczny (bare metal) lub maszyna wirtualna (VM), których wolą Państwo nie przygotowywać ręcznie 2.9
Pakiet offline (offline bundle) Całkowity brak połączenia ze światem zewnętrznym; obrazy i pakiet chart są dostarczane na dysku 2.10

Pakiet chart jest taki sam w każdej formie. Zmienia się tylko to, kto tworzy klaster i skąd pochodzą obrazy.

Pobierz wydanie
Pobierz wydanie
To jest strona wydania na koncie Adverant. Proszę zwrócić uwagę na jasną deklarację tego, co zapewnia wydanie alfa, rozmiar i podpis obok każdego pliku oraz polecenia offline służące do weryfikacji pobranych plików.

Arkusz planowania

Oto arkusz z Harrow, zatwierdzony przez Aoife. Proszę skopiować dwie lewe kolumny i wypełnić prawą dla własnej instalacji.

Decyzja Klucz wartości lub polecenie Harrow Port Authority
Kubernetes i wersja (odczytywane przez kontrolę wstępną) k3s v1.33.6+k3s1, trzy węzły
Kontekst kube dla instalacji --context harrow-prod
Przestrzeń nazw (Namespace) --namespace nexus
Edycja edition, enterprise.enabled community na czas pilotażu, następnie enterprise
Rejestr obrazów global.imageRegistry registry.adverant.ai
Domena global.domain harrow.example
Adres konsoli hosts.console console.harrow.example
Adres API hosts.api api.harrow.example
Adres logowania hosts.auth auth.harrow.example
TLS na brzegu sieci tls.mode, tls.existingSecret existing, obiekt Secret harrow-public-tls z wewnętrznego CA w Harrow
Klasa ingress (IngressClass) ingress.className traefik
Przestrzeń nazw ingress networkPolicy.ingressNamespace kube-system
Klasa pamięci masowej (StorageClass) storage.className local-path
Magazyny danych dataTier.<store>.mode Wszystkie in-cluster, domyślne rozmiary
Zakresy ruchu wychodzącego networkPolicy.externalEgressCIDRs Wyłącznie zakres przekaźnika pocztowego (mail relay)
Nazwa instalacji (stała) keys.installationName harrow-port-authority
Depozytariusze (w praktyce stali) keys.custody.recipients Troje: Aoife Brennan, Tomás Reilly, laptop w sejfie (age1se1)
Węzły graficzne (odczytywane przez kontrolę wstępną) Brak w pilotażu z dostępem do internetu; model hostowany z własnym kluczem Harrow
Pierwszy administrator nexusctl claim-code --administrator aoife.brennan@harrow.example

Dwóch wierszy w tym arkuszu nie da się cofnąć: nazwy instalacji oraz depozytariuszy – w tym sensie, że utrata ich wszystkich oznacza utratę magazynu kluczy. Te dwie pozycje powinny zostać zatwierdzone przez osobę decyzyjną. Wszystko inne to tylko zmiana w pliku wartości.

Po wypełnieniu arkusza roboczego proszę przejść do rozdziału 2.4, Pobieranie i weryfikacja wydania, i pobrać wydanie.