Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.4
Pobieranie i weryfikacja wydania
Gdzie znajduje się każda część wydania systemu Nexus, jak obrazy Enterprise są pobierane za pomocą tokenu pobierania (pull token) oraz jak udowodnić offline, przed zainstalowaniem czegokolwiek, że każdy obraz, pakiet chart i pobrany plik pochodzą od firmy Adverant w niezmienionej postaci.
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

Każdy obraz w wydaniu Nexus jest podpisany kluczem wydania Adverant, a każdy obraz jest identyfikowany za pomocą skrótu (digest), nigdy za pomocą tagu. Chart wyrenderuje wyłącznie obrazy wymienione według skrótu we własnym pliku blokady obrazów (images lock). W połączeniu oznacza to, że na własnej stacji roboczej i bez połączenia z kimkolwiek mogą Państwo udowodnić, że to, co zamierzają Państwo uruchomić, jest dokładnie tym, co zbudował Adverant.
W Harrow Port Authority sprawdziliśmy wszystko przed pierwszą instalacją. Zajęło to około dwudziestu minut, z czego większość stanowiła pętla po obrazach. Ten rozdział prowadzi tą samą ścieżką: gdzie znajduje się każda część wydania, token pobierania (pull token) dla obrazów Enterprise, blokada obrazów, weryfikacje cosign wraz z dokładnymi poleceniami oraz co zrobić, gdy weryfikacja zakończy się niepowodzeniem.
Gdzie znajduje się wydanie
| Adres | Co można stamtąd pobrać |
|---|---|
registry.adverant.ai |
Obrazy platformy pod adresem registry.adverant.ai/nexus/<service>@sha256:<digest> oraz chart Helm pod adresem oci://registry.adverant.ai/nexus/charts/nexus |
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ |
Klucz publiczny wydania i jego odcisk palca, pliki binarne nexusctl oraz pakiety offline |
https://account.adverant.ai |
Państwa konto Adverant: Pobrania, Tokeny pobierania i polecenia instalacyjne, Wdrożenia oraz strony licencji |
Obrazy Community oraz chart Community są publiczne; można je pobrać bez logowania. Obrazy Enterprise są pobierane za pomocą tokenu pobierania z Państwa konta, a chart i pakiet Enterprise znajdują się na stronie Pobrania na koncie, zgodnie z Państwa licencją.
Przede wszystkim proszę przeczytać informacje o wydaniu
Informacje o wydaniu (release notes) są dostarczane wewnątrz każdego pakietu jako plik docs/RELEASE-NOTES.md, wymieniony w jego pliku SHA256SUMS, a te same informacje znajdują się na stronie wydania na Państwa koncie. Należy je przeczytać przed instalacją lub aktualizacją. Dla wersji 1.0.0-alpha.1 są one krótkie. Jest to pierwsze wydanie, więc świeża instalacja nie obejmuje żadnego z opisanych tam punktów dotyczących aktualizacji, a lista znanych problemów wskazuje, że nic z niej nie wpływa na świeżą instalację przeprowadzoną zgodnie z udokumentowanymi krokami. Późniejsze wydania wymieniają każdy znany problem wraz z wersją, która go naprawia.
Strona wydania określa również w trzech wierszach, co obiecuje wydanie alfa: funkcje mogą ulec zmianie przed pierwszą wersją stabilną, aktualizacja zachowuje dane i najpierw wykonuje kopię zapasową, a poprawki bezpieczeństwa pojawiają się w ciągu 7 dni. Wydrukowaliśmy tę stronę i dołączyliśmy ją do rejestru zmian w Harrow, ponieważ jest to dokument najbliższy oświadczeniu o wsparciu, o które zapytałaby komisja ds. zmian.
Krok 1: pobranie klucza wydania i sprawdzenie go drugą drogą
Wszystko poniżej opiera się na jednym pliku: kluczu publicznym wydania Adverant. Klucz pochodzący z tego samego miejsca, co element, za który poręcza, dowodzi bardzo niewiele, dlatego należy sprawdzić jego odcisk palca z kopią, która dotarła do Państwa inną drogą.
Proszę pobrać klucz z folderu wydania na stronie Pobrania.
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pubProszę wyliczyć jego odcisk palca. Odcisk palca to skrót SHA-256 (Secure Hash Algorithm 256) samego pliku klucza.
sha256sum release.pubW systemie macOS polecenie
shasum -a 256 release.pubdaje ten sam wynik.Proszę porównać go, znak po znaku, z odciskiem palca wydrukowanym w Państwa umowie z Adverant oraz w informacjach o wydaniu. Strona Pobrania również publikuje odcisk palca, ale ta kopia dotarła tą samą drogą co klucz, więc nie stanowi to weryfikacji.
Jeśli którykolwiek znak się różni, należy przerwać. Proszę nie instalować systemu i nie szukać innej kopii klucza w internecie. Proszę otworzyć zgłoszenie serwisowe ze swojego konta i zacytować to, co Państwo zobaczyli.
Krok 2: pobranie nexusctl
nexusctl to interfejs wiersza poleceń (CLI) operatora systemu Nexus. Działa on na Państwa stacji roboczej i odczytuje klaster poprzez plik kubeconfig. Strona Pobrania oferuje cztery kompilacje:
| Plik | Platforma |
|---|---|
nexusctl-linux-amd64 |
Linux na procesorach Intel lub AMD |
nexusctl-darwin-arm64 |
macOS na procesorach Apple silicon |
nexusctl-darwin-amd64 |
macOS na procesorach Intel |
nexusctl-windows-amd64.exe |
Windows |
Obok każdego pliku znajduje się jego pakiet podpisu o tej samej nazwie z końcówką .sigstore.json. Przed uruchomieniem pliku binarnego należy go sprawdzić:
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64.sigstore.json
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
--bundle nexusctl-linux-amd64.sigstore.json nexusctl-linux-amd64Verified OK
Następnie należy umieścić go w ścieżce systemowej (PATH) i odpytać o wersję:
install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl versionOd tego momentu narzędzie nexusctl verify może wykonywać sprawdzanie plików za Państwa. Rozdział 2.5, Kontrola wstępna (preflight) za pomocą nexusctl, omawia jego główne zadanie, czyli kontrolę wstępną.
Dlaczego flaga zawiera słowo „insecure”
Każde polecenie cosign w tym rozdziale zawiera flagę --insecure-ignore-tlog=true. Wydania Nexus są podpisywane kluczem Adverant i nie są rejestrowane w żadnym publicznym dzienniku przejrzystości (transparency log), dzięki czemu sprawdzenie wydania nigdy nie wymaga połączenia z kimkolwiek, włączając w to Sigstore. Domyślnie cosign wymaga wpisu w dzienniku; flaga ta nakazuje mu polegać wyłącznie na kluczu. Bez niej weryfikacja kończy się niepowodzeniem w następujący sposób:
Error: not enough verified log entries from transparency log: 0 < 1
Gdy flaga jest ustawiona, cosign nadal wypisuje zdanie „Existence of the claims in the transparency log was verified offline”. Jest to stałe sformułowanie w cosign; nie stoi za nim żaden wpis w dzienniku. Weryfikacja podpisu względem klucza jest rzeczywista i to ta część ma znaczenie.
Krok 3: token pobierania dla edycji Enterprise
Obrazy Enterprise są chronione tokenem pobierania. Można go utworzyć na swoim koncie, na stronie Tokeny pobierania i polecenia instalacyjne:
- Proszę nacisnąć Dodaj token.
- Proszę określić, dla którego klastra jest przeznaczony, co może pobierać i kiedy wygasa.
- Proszę nacisnąć Kopiuj token i wkleić go bezpośrednio w miejscu, w którym przechowują Państwo dane uwierzytelniające, ponieważ strona wyświetla go tylko ten jeden raz.
Każdy token jest ograniczony do tego, co może pobierać, i ma datę ważności. Wycofanie tokenu natychmiast zatrzymuje nowe pobrania; obrazy, które klaster już pobrał, działają nadal. W Harrow utworzyliśmy po jednym tokenie na klaster, dzięki czemu wycofanie tokenu klastra testowego nigdy nie dotyka środowiska produkcyjnego. Instalacja Community w ogóle nie wymaga tokenu; tworzy się go dopiero przy przejściu na wersję Enterprise i można to zrobić tego samego dnia.
Chart nie posiada wartości pull-secret. Obrazy są pobierane przez Państwa węzły, więc token należy do środowiska uruchomieniowego kontenerów na węzłach. W systemie k3s należy dodać rejestr do pliku /etc/rancher/k3s/registries.yaml na każdym węźle i zrestartować tam usługę k3s:
# /etc/rancher/k3s/registries.yaml (on every node)
configs:
"registry.adverant.ai":
auth: {username: "<registry-user>", password: "<pull-token>"}<registry-user> to nazwa użytkownika rejestru z Państwa zaproszenia od Adverant, a <pull-token> to skopiowany przez Państwa token. Plik zawiera dane uwierzytelniające, dlatego należy zachować uprawnienia do odczytu wyłącznie dla użytkownika root.
W klastrze zarządzanym, którego węzły nie odczytują tego pliku, należy skopiować obrazy do rejestru, któremu węzły już ufają, i ustawić na niego parametr global.imageRegistry; każdy węzeł musi ufać certyfikatowi Transport Layer Security (TLS) tego rejestru. Omawia to rozdział 2.11, Warianty: zewnętrzne magazyny danych, TLS i ingress, natomiast rozdział 2.10, Instalacja w środowisku odizolowanym (air-gapped), omawia to samo kopiowanie dla lokalizacji bez dostępu do sieci zewnętrznej.
Krok 4: odczytanie pliku blokady obrazów
Chart Nexus nigdy nie identyfikuje obrazu za pomocą tagu. Identyfikuje każdy z nich za pomocą skrótu (digest) jego wieloplatformowego indeksu, pobranego z blokady obrazów – pliku, który chart zawiera jako files/images.lock.json. Pakiet offline zawiera tę samą blokadę jako release/images.lock.json.
Proszę pobrać chart i rozpakować go, aby odczytać blokadę:
helm pull oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1
tar -xzf nexus-1.0.0-alpha.1.tgz
jq -r '.version, .edition' nexus/files/images.lock.json1.0.0-alpha.1
community
Najwyższy poziom blokady określa, do którego wydania i której edycji ona należy. Każdy wpis pod kluczem images opisuje jeden obraz:
| Pole | Co zawiera |
|---|---|
svc |
Usługę, taką jak nexus-auth lub nexus-postgres |
index |
Skrót sha256: indeksu obrazu, który obejmuje zarówno linux/amd64, jak i linux/arm64 |
edition |
community, enterprise lub all dla warstwy danych |
kind |
service, migrations lub data-tier dla pięciu magazynów danych oraz OpenBao |
verified |
Czas, kiedy kompilacja wydania zweryfikowała jego podpis i poświadczenia (attestations) |
Chart renderuje każdy obraz jako <global.imageRegistry>/nexus/<svc>@<index>. Zatem przy global.imageRegistry: registry.adverant.ai, usługa logowania to registry.adverant.ai/nexus/nexus-auth@sha256: z następującymi po nim 64 znakami szesnastkowymi i nic w klastrze nie może podmienić go na nic innego o tej samej nazwie.
Blokada jest przypisana do edycji. Blokada Community wymienia tylko obrazy, których edycja to community lub all. Blokada Enterprise wymienia te same obrazy oraz kompilacje Enterprise. Chart sprawdza to przy każdym renderowaniu i odmawia wykonania operacji, zamiast zgadywać:
| Co zwraca chart | Dlaczego |
|---|---|
edition=enterprise but enterprise.enabled=false: they must agree |
Dwie wartości edycji w Państwa pliku values są ze sobą sprzeczne |
files/images.lock.json is the community lock; this install is edition enterprise |
Instalują Państwo edycję Enterprise z chartu Community lub odwrotnie |
image nexus-auth is not in files/images.lock.json |
Chart i jego blokada nie pasują do siebie; proszę pobrać chart ponownie |
image ... is in the lock but was never verified by build-all |
Wpis blokady nie zawiera czasu weryfikacji; proszę nie instalować z tego źródła |
NEXUS_EDITION_INVALID |
Wartość edition jest pusta lub nie jest jedną z wartości: community i enterprise |
RELEASE_VERSION_MISSING |
Blokada nie określa żadnej wersji |
Aby wyświetlić listę wszystkich obrazów i skrótów za jednym razem:
jq -r '.images[] | "\(.svc) \(.index)"' nexus/files/images.lock.jsonKrok 5: weryfikacja podpisu każdego obrazu
Każdy indeks obrazu jest podpisany, podobnie jak każdy zawarty w nim manifest platformy. Proszę przeprowadzić weryfikację według skrótu, bezpośrednio z blokady, aby sprawdzić dokładnie to, co uruchomi chart:
jq -r '.images[] | "\(.svc)@\(.index)"' nexus/files/images.lock.json |
while read -r ref; do
cosign verify --key release.pub --insecure-ignore-tlog=true \
"registry.adverant.ai/nexus/$ref" > /dev/null && echo "OK $ref" || echo "FAILED $ref"
doneKażdy wiersz powinien zaczynać się od OK. Na naszym łączu pętla zajęła kilka minut, z czego większość czasu upłynęła na oczekiwaniu na rejestr. Odczytuje ona wyłącznie podpisy i nie pobiera żadnych warstw obrazu, dzięki czemu powtarzanie jej po każdej aktualizacji jest mało obciążające. Wiersz FAILED oznacza konieczność zatrzymania: kolejna sekcja wyjaśnia znaczenie poszczególnych komunikatów.
Dla pojedynczego obrazu można pominąć przekierowanie i odczytać, co sprawdziło narzędzie cosign:
cosign verify --key release.pub --insecure-ignore-tlog=true \
registry.adverant.ai/nexus/nexus-auth@sha256:<digest>The following checks were performed on each of these signatures:
- Existence of the claims in the transparency log was verified offline
- The signatures were verified against the specified public key
<digest> to 64 znaki szesnastkowe z pola index blokady dla danego obrazu. Obrazy Enterprise wymagają Państwa tokenu pobierania do tego sprawdzenia, podobnie jak do każdego pobierania z rejestru.
Obie platformy i co należy zachować
Każdy indeks obrazu zawiera dwa manifesty platform, linux/amd64 oraz linux/arm64, a każdy z nich jest również podpisany. Polecenie cosign verify kończy się powodzeniem zarówno dla skrótu indeksu, jak i dla skrótu każdej z platform, dzięki czemu klaster z mieszanymi węzłami jest objęty tym samym sprawdzeniem. Aby zobaczyć dwie platformy kryjące się za indeksem, należy odpytać rejestr o surowy indeks:
docker buildx imagetools inspect registry.adverant.ai/nexus/nexus-auth@sha256:<digest> --rawJego lista manifests wymienia jeden wpis amd64 i jeden wpis arm64.
Wynik powyższej pętli należy zachować w rejestrze zmian, obok sprawdzonego odcisku palca. Gdy po miesiącach ktoś zapyta, skąd wiadomo, że w klastrze działa to, co dostarczył Adverant, ten plik oraz skróty z blokady stanowią odpowiedź. Nasz audytor w Harrow zadał dokładnie to pytanie, a udzielenie odpowiedzi zajęło minutę.
Krok 6: odczytanie poświadczeń (attestations)
Każdy obraz zawiera również dwa podpisane poświadczenia (attestations), utworzone z obrazu w czasie kompilacji: wykaz komponentów oprogramowania (SBOM – software bill of materials) oraz oświadczenie o pochodzeniu (provenance statement).
Dokument SBOM ma format Software Package Data Exchange (SPDX), po jednym na każdą platformę, więc indeks zawiera dwa takie dokumenty. Wymienia on każdy pakiet w obrazie wraz z jego licencją. Przed wydaniem licencje te są sprawdzane względem listy zabronionej (deny list); żaden obraz Community nie zawiera kodu na licencji GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) ani Business Source License (BUSL). Oświadczenie o pochodzeniu jest zgodne ze standardem Supply-chain Levels for Software Artifacts (SLSA) v1. Wymienia ono zatwierdzenie źródłowe (commit), z którego zbudowano obraz, skróty obrazów bazowych oraz narzędzia kompilacji i ich wersje, dzięki czemu obraz można prześledzić wstecz do zweryfikowanego kodu źródłowego bez pytania firmy Adverant.
Oba elementy są sprawdzane względem klucza wydania, który już Państwo posiadają:
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
--type spdxjson registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
--type slsaprovenance1 registry.adverant.ai/nexus/nexus-auth@sha256:<digest>Weryfikacja spdxjson wypisuje dwa wyniki, po jednym dla dokumentu SBOM każdej platformy. Aby zobaczyć wszystko, co jest dołączone do obrazu, bez przeprowadzania weryfikacji, należy użyć polecenia cosign tree:
cosign tree registry.adverant.ai/nexus/nexus-auth@sha256:<digest>Wymienia ono jeden pakiet podpisu, dwa poświadczenia spdx.dev/Document oraz jedno poświadczenie slsa.dev/provenance/v1. Odpytanie o typ, którego obraz nie zawiera, taki jak --type cyclonedx, kończy się błędem none of the attestations matched the predicate type: cyclonedx. To niepowodzenie jest prawidłowe; wydanie dołącza format SPDX, a nie CycloneDX.
Krok 7: weryfikacja pakietu chart i pobranych plików
Chart w rejestrze jest podpisany na swoim skrócie OCI (OCI to Open Container Initiative – format obrazów i artefaktów używany przez rejestry). Polecenie helm pull wypisuje pobrany skrót; skrót ten należy sprawdzić w taki sam sposób jak obraz:
cosign verify --key release.pub --insecure-ignore-tlog=true \
registry.adverant.ai/nexus/charts/nexus@sha256:<chart-digest>W przypadku pobranego pliku chartu lub pakietu offline polecenie nexusctl verify sprawdza plik względem klucza wydania Adverant:
nexusctl verify nexus-1.0.0-alpha.1.tgzPrawidłowy wynik kończy się wymienieniem klucza wydania Adverant oraz początku jego odcisku palca. Proszę porównać te grupy ze sprawdzonym w kroku 1 odciskiem palca.
Pakiet offline to jeden nieskompresowany plik tar na edycję, nexus-alpha-1.0.0-alpha.1-community.tar lub nexus-alpha-1.0.0-alpha.1-enterprise.tar, z towarzyszącym mu plikiem .sha256. Wewnątrz zawiera on:
| Ścieżka | Czym to jest |
|---|---|
release/images.lock.json |
Blokada obrazów dla danej edycji |
release/facts.json |
Dane o wydaniu: wersja, edycja, architektury oraz odcisk palca klucza wydania |
images/<service>/ |
Każdy obraz z obiema platformami, jego podpisem i poświadczeniami |
charts/nexus-1.0.0-alpha.1.tgz |
Chart |
sbom/ |
Dokument SBOM w formacie SPDX dla każdego obrazu, z podziałem na platformy |
docs/ |
Informacje o wydaniu, podręcznik instalacji w środowisku odizolowanym (air-gap) oraz przykładowe wartości |
SHA256SUMS oraz SHA256SUMS.sigstore.json |
Suma kontrolna każdego pliku oraz jej podpis |
Klucz publiczny wydania nigdy nie znajduje się wewnątrz pakietu; klucz dostarczany razem z elementem, który podpisuje, niczego nie dowodzi. Cały pakiet można sprawdzić dwoma poleceniami z wnętrza jego folderu:
sha256sum -c SHA256SUMS
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
--bundle SHA256SUMS.sigstore.json SHA256SUMSKażdy wiersz pierwszego polecenia powinien kończyć się ciągiem OK, a drugie powinno wypisać Verified OK. Rozdział 2.10, Instalacja w środowisku odizolowanym (air-gapped), przejmuje ten pakiet na tym etapie: obejmuje załadowanie obrazów do Państwa własnego rejestru, ponowną weryfikację każdego z nich w tym miejscu oraz własne kompleksowe sprawdzenie pakietu.
Gdy weryfikacja podpisu się nie powiedzie
Proszę przerwać. Proszę nie instalować i nie zmieniać polecenia, dopóki nie przejdzie ono pomyślnie. Nieudana weryfikacja podpisu oznacza, że system działa prawidłowo: świadczy to o tym, że posiadany przez Państwa plik nie jest plikiem podpisanym przez Adverant lub posiadany klucz nie należy do Adverant.
| Co Państwo widzą | Co to oznacza | Co należy zrobić |
|---|---|---|
accepted signatures do not match threshold, Found: 0, Expected 1 (kod wyjścia 1) |
Obraz jest podpisany, ale nie za pomocą podanego przez Państwa klucza | Proszę sprawdzić, czy użyli Państwo klucza wydania, którego odcisk palca został zweryfikowany w kroku 1 |
no signatures found (kod wyjścia 10) |
Pod tym skrótem nic nie jest podpisane | Proszę sprawdzić, czy skrót pochodzi z blokady; nigdy nie należy weryfikować tagu |
not enough verified log entries from transparency log: 0 < 1 |
Brak flagi --insecure-ignore-tlog=true |
Proszę dodać flagę; z obrazem nie dzieje się nic złego |
none of the attestations matched the predicate type |
Zażądano typu poświadczenia, którego obraz nie zawiera | Proszę użyć spdxjson lub slsaprovenance1 |
Error: invalid signature when validating ASN.1 encoded signature |
Pobrany plik został zmieniony po jego podpisaniu | Proszę pobrać go ponownie |
FAILED z sha256sum -c |
Plik nie jest tym plikiem, dla którego obliczono sumę kontrolną | Proszę pobrać go ponownie |
Jeśli pobieranie zakończy się niepowodzeniem dwukrotnie, proszę otworzyć zgłoszenie serwisowe ze swojego konta i podać nazwę pliku oraz komunikat. Proszę zachować plik powodujący błąd; Państwa zespół ds. bezpieczeństwa może go potrzebować.
W instalacji, która ładuje wydania z dysku, konsola uruchamia te same weryfikacje i odrzuca wydanie, którego podpis nie pasuje do zainstalowanego klucza, zwracając błąd MEDIA_SIGNATURE_INVALID. Informuje, co sprawdziła, w jakiej kolejności, gdzie się zatrzymała oraz że nic nie zostało zmienione: żaden obraz nie został załadowany, a działająca wersja pozostała nietknięta.
Gdy klucz, obrazy i chart przejdą pomyślnie weryfikację, kolejnym krokiem jest kontrola wstępna (preflight) względem Państwa klastra, opisana w rozdziale 2.5, Kontrola wstępna (preflight) za pomocą nexusctl.



