Wersja 1.0.0-alpha.1najnowsza
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

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ć.
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.keyWiersz # 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.keyTaki 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.
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.
