Sürüm 1.0.0-alpha.1en son
Bölüm 2.5
nexusctl ile ön kontrol
`nexusctl preflight` komutunun yaptığı her kontrol, her birinin neyi okuduğu ve nasıl başarısız olduğu, yazdırdığı ve kaydettiği rapor, bu raporun konsolun ön kontrol sayfasına nasıl ulaştığı ve tüm bayraklar.
Bu sayfa, İngilizce aslından YZ tarafından çevrilmiştir. Anlaşılmayan bir yer olursa İngilizce sayfa esas alınır. Bu sayfayı İngilizce okuyun

Harrow Port Authority'deki ilk ön kontrolümüz dört denetimde başarısız oldu ve bunlardan ikisi bize bir öğleden sonradan çok daha fazlasına mal olabilirdi. Değerler (values) dosyasına chart'ın örneğini kopyalayarak başlamıştık ve ön kontrol hem örnek kurulum adını hem de örnek saklama görevlisini (custodian) reddetti. O saklama görevlisinin özel anahtarı hiç kimsede bulunmaz. Ona mühürlenmiş bir kurulumun mührü, bir düğüm (node) yeniden başlatıldıktan sonra asla açılamaz. Ön kontrol, kaybedecek hiçbir şey yokken birkaç saniye içinde bunu yakaladı.
nexusctl preflight kümenizi ve değerler dosyanızı okur, bulduklarını yazdırır, bir rapor kaydeder ve kümede hiçbir şeyi değiştirmez. Her kurulumdan ve her yükseltmeden önce çalıştırın. Bu bölüm, yaptığı her denetimi, rapor biçimini, raporun nereye gittiğini ve bayrakları (flags) kapsar.
Çalıştırma
Ön kontrolün iki şeye ihtiyacı vardır: kurulum yapacağınız kümenin kube bağlamı (context) ve kurulumun kullanacağı değerler dosyası. Önce değerler dosyasını yazın; bölüm 2.6, Kubernetes Üzerine Community Kurulumu, her anahtarı adım adım açıklar. Ardından:
nexusctl preflight --context harrow-prod --values harrow-values.yamlKümeyi yalnızca get ve list çağrılarıyla client-go üzerinden okur. tls.mode değeriniz existing ise, çalıştırmadan önce nexus ad alanını (namespace) ve Taşıma Katmanı Güvenliği (TLS) Secret'ını oluşturun (bölüm 2.6, Kubernetes Üzerine Community Kurulumu, adım 3); aksi takdirde sertifika denetimi Secret'ın eksik olduğunu bildirir.
| Bayrak | Yaptığı iş | Varsayılan |
|---|---|---|
--context <name> |
Denetlenecek kube bağlamı. Zorunlu | yok |
--values <file> |
Kurulumun kullanacağı değerler dosyası. Zorunlu | yok |
--namespace <name> |
Nexus'un kurulacağı yer | nexus |
--release <version> |
Denetlenen sürüm | paketlenmiş chart'ın kendi sürümü |
--report-dir <dir> |
İki rapor dosyasının kaydedileceği yer | mevcut klasör |
--record <mode> |
auto, always veya never: kurulum sayfasının göstermesi için raporun bu kurulumun anahtar servisine teslim edilip edilmeyeceği |
auto |
--kubeconfig <file> |
Okunacak kubeconfig | KUBECONFIG, ardından ~/.kube/config |
--ca-bundle <file> |
Denetimlerin güvenmesi gereken bir zincir için kendi sertifika yetkilisi (CA) sertifikalarınız | yok |
--single-node |
Tek makineli kurulum için bir makineyi denetleyin (bölüm 2.8, Tek makineli kurulumlar) | kapalı |
Sürümün Kubernetes için alt sınırı nexusctl içine yazılmamıştır. Taşıdığı chart'tan, chart'ın kendi kubeVersion değerinin alt sınırını okur; böylece denetim ve helm install asla çelişmez.
Bir çalıştırmanın yazdırdıkları
Harrow'un ilk çalıştırması, yazdırıldığı şekliyle şöyledir:
Adverant Nexus 1.0.0-alpha.1 · preflight · Tue 10 Nov 2026 08:40 · read-only
Failed first
FAIL Address (api) api.harrow.example → no record people reach Nexus by this name
fix add a DNS record for api.harrow.example that points at the ingress, then run preflight again
FAIL Address (auth) auth.harrow.example → no record people reach Nexus by this name
fix add a DNS record for auth.harrow.example that points at the ingress, then run preflight again
FAIL Key custodians the example custodian of the chart's values-community.yaml and values-enterprise.yaml (age1u63etg5v…) the key store seals its recovery keys to them; no one holds the example custodian's key
fix replace it in keys.custody.recipients in harrow-values.yaml with your custodians' own recipients: each custodian makes a key on their own machine with `age-keygen -o custodian.key` (the `# public key: age1...` line is the recipient), or `age-plugin-se keygen --access-control=any-biometry -o custodian.key` for a Secure Enclave key, keeps the identity file offline, and gives you only the recipient
FAIL Installation name nexus-example, the example name of the chart's values-community.yaml and values-enterprise.yaml the first key-store bootstrap mints the installation identity under it, permanently
fix set keys.installationName in harrow-values.yaml to this installation's own name
Warnings
warn Graphics nodes none the assistant will need a hosted model
fix add a node with a graphics card and its device plugin, or have the assistant use a hosted model
warn Certificate secret harrow-public-tls not found in nexus the public address needs it before people sign in
fix create the TLS secret harrow-public-tls in nexus before installing, or change tls.existingSecret in harrow-values.yaml
Passed
pass Kubernetes version 1.33.6+k3s1 needs 1.33 or later
pass Nodes ready 3 of 3
pass Storage class local-path (default)
pass Resources 24 cores, 93.9 GiB needs 2.1 cores, 6.7 GiB
pass Ingress class traefik (default)
pass Ingress ports traefik (LoadBalancer) on 80 and 443
pass Address (console) console.harrow.example → 10.20.4.10
────────────────────────────────────────────────────────────────────────────
7 passed · 2 warnings · 4 failed Install cannot continue until the failures pass.
Nothing was changed. Report saved to preflight-2026-11-10-0840.txt
Herhangi bir şey başarısız olduğunda önce hatalar, ardından uyarılar, sonra da başarılı olanlar gelir. Her satır sonucu, denetimin adını, ne bulunduğunu ve neye ihtiyaç duyduğunu gösterir; geçemeyen her satırın altında bir fix satırı bulunur. Son iki satır özet ve rapor dosyasıdır.
Değerleri düzelttik, iki Alan Adı Sistemi (DNS) kaydını ekledik, Secret'ı oluşturduk ve tekrar çalıştırdık:
Adverant Nexus 1.0.0-alpha.1 · preflight · Thu 12 Nov 2026 09:02 · read-only
Cluster
pass Kubernetes version 1.33.6+k3s1 needs 1.33 or later
pass Nodes ready 3 of 3
pass Storage class local-path (default)
pass Resources 24 cores, 93.9 GiB needs 2.1 cores, 6.7 GiB
warn Graphics nodes none the assistant will need a hosted model
fix add a node with a graphics card and its device plugin, or have the assistant use a hosted model
Network
pass Ingress class traefik (default)
pass Ingress ports traefik (LoadBalancer) on 80 and 443
pass Address (console) console.harrow.example → 10.20.4.10
pass Address (api) api.harrow.example → 10.20.4.10
pass Address (auth) auth.harrow.example → 10.20.4.10
pass Certificate ends 3 Nov 2027
Time and keys
pass Key custodians 3 custodians
pass Installation name harrow-port-authority
────────────────────────────────────────────────────────────────────────────
12 passed · 1 warning · 0 failed You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed on the cluster
Hatasız bir çalıştırma, denetimleri üç başlık altında listeler: Küme, Ağ ve Zaman ve anahtarlar. Uyarılar asla engellemez. Grafik uyarısını bilerek tuttuk: bu bağlantılı pilot kümede, Harrow'un asistanı limanın kendi anahtarıyla barındırılan bir model kullandı.
Çıkış kodları
| Kod | Anlamı |
|---|---|
0 |
Kurulum devam edebilir. Uyarılar engellemez |
1 |
Kurulum engellendi: en az bir denetim başarısız oldu |
2 |
Ön kontrol çalıştırılamadı: kubeconfig, bağlam, değerler dosyası veya kümenin uygulama programlama arayüzü (API) okunamadı ya da bir bayrak yanlıştı |
Betikler kelimeleri değil, çıkış kodunu okumalıdır. Bizimki, her yükseltmenin ilk adımı olarak ön kontrolü çalıştırır ve 0 dışındaki her şeyde durur.
Kurulum yaptığınız sürümün değil, geçmekte olduğunuz sürümün nexusctl aracını çalıştırın. Gereksinimler taşıdığı chart'tan gelir; dolayısıyla daha yeni bir sürüm Kubernetes alt sınırını yükseltebilir veya daha fazla bellek isteyebilir ve bunu yalnızca kendi nexusctl aracı bilir. --release raporun adlandırdığı sürümü değiştirir; hangi chart'ın kurallarının uygulanacağını değiştirmez. Harrow'da her sürümün nexusctl aracını değişiklik kaydında kendi chart'ının yanında tutuyoruz, böylece bir geri alma işlemi kendisiyle eşleşen araç tarafından denetleniyor.
Her kontrol
On bir denetim vardır. Bunlardan onu birer satır üretir; adres denetimi ana bilgisayar (host) başına bir satır üretir, böylece tam bir çalıştırma on üç satırdan oluşur. Dokuz denetimin başarılı olması zorunludur ve bir eksiklik başarısızlık sayılır. İkisinin, yani grafik düğümlerinin ve sertifikanın başarılı olması önerilir ve bir eksiklik uyarı sayılır. Son sütun, her satırın rapora taşıdığı gereksinim metnidir; buradaki CPU, merkezi işlem birimidir.
| Denetim kimliği | Bölüm | Geçmesi zorunlu | Yazdırdığı gereksinim |
|---|---|---|---|
kubernetes-version |
cluster | evet | Kubernetes 1.33 veya sonrası |
nodes-ready |
cluster | evet | Her düğüm hazır |
storage-class |
cluster | evet | Veriler için bir depolama sınıfı (storage class) |
resources |
cluster | evet | Sürüm için yeterli CPU ve bellek |
graphics-nodes |
cluster | hayır | Grafik düğümleri |
ingress-class |
network | evet | Üç adres için bir ingress sınıfı |
ingress-ports |
network | evet | 80 ve 443 numaralı bağlantı noktalarında açık ingress denetleyicisi |
address-console, address-api, address-auth |
network | evet | Konsol, api veya auth adresi DNS'te çözümleniyor |
certificate |
network | hayır | Sertifika 30 gün daha geçerli |
custodians |
time-and-keys | evet | Bu kurulumun kurtarma anahtarlarını tutan kişiler |
installation-name |
time-and-keys | evet | Bu kurulumun kendi kalıcı adı |
kubernetes-version
API sunucusunun sürümünü okur ve chart'ın alt sınırıyla karşılaştırır. Örneğin 1.33.6+k3s1 bulur. 1.33'ün altında upgrade the cluster to 1.33 or later çözümüyle başarısız olur. Sürüm dizgesi nexusctl tarafından okunabilecek bir dizge değilse, tahmin yürütmek yerine başarısız olur.
nodes-ready
Düğümleri listeler ve Ready koşulu doğru olanları 3 of 3 olarak sayar. Hazır olmayan herhangi bir düğüm adlandırılır ve çözüm size onu tekrar Ready durumuna getirmenizi ve koşullarını okumanızı söyler. Hiç düğümü olmayan bir küme, bağlamın yanlış kümeyi işaret ediyor olabileceği ipucuyla başarısız olur.
storage-class
Değerleriniz storage.className ayarını yapıyorsa, denetim o sınıfı arar ve eksik olduğunda <name> does not exist ile başarısız olur. Yapmıyorsa, varsayılan olarak işaretlenmiş bir sınıf arar ve bunu local-path (default) olarak bildirir. Varsayılan yoksa none marked default ile başarısız olur ve gereksinimler sütunu bunun neden önemli olduğunu söyler: the database cannot claim a disk. İki sınıf varsayılan olarak işaretlenmişse, küme yeni bir talebe (claim) en yenisini verir, bu nedenle bildirilen sınıf odur.
resources
Chart'tan ve değerlerinizden sürümün ne istediğini hesaplar, ardından Ready durumunda olan, kordona alınmamış (not cordoned) ve NoSchedule veya NoExecute lekesi (taint) taşımayan her düğümün ayrılabilir merkezi işlem birimi (CPU) çekirdeklerini ve belleğini toplar. Chart'ın pod'ları hiçbir tolerans taşımaz, bu nedenle lekeli bir düğüm bunları çalıştıramaz ve hesaba katılmaz. Yetersiz bir küme, add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml gibi tam eksiklik miktarıyla başarısız olur. Gereksinimler yukarı, arz ise aşağı yuvarlanır; böylece denetim size asla iyimser bir tablo çizmez.
graphics-nodes
Ayırabileceği bir grafik işlem birimine (GPU) sahip Ready durumunda bir düğüm arar, nvidia.com/gpu. Hiç yoksa uyarır: the assistant will need a hosted model. Ön kontrol bunu bir tavsiye olarak ele alır ve asistan bunun yerine barındırılan bir yapay zeka (YZ) modeli üzerinden yanıt verebileceği için bunu asla bir engel olarak görmez. Bölüm 2.14, YZ sağlayıcıları ve modelleri, her iki yolu da kapsar.
ingress-class
ingress.className ayarlanmışsa, denetim o sınıfı arar. Ayarlanmamışsa, varsayılan olarak işaretlenmiş tam olarak bir sınıf arar. Varsayılan olarak işaretlenmiş iki sınıf da başarısız olur, çünkü API sunucusu bu durumda sınıfı olmayan bir Ingress'i reddeder. ingress.enabled değeri false olduğunda denetim atlanır ve satırı dışarıda bırakılır.
ingress-ports
Hem 80 hem de 443'ü dışa açan bir LoadBalancer veya NodePort Servisi için networkPolicy.ingressNamespace ile adlandırılan ad alanında (varsayılan olarak k3s'in Traefik'i çalıştırdığı kube-system) arama yapar. Chart'ın ağ politikası yalnızca o ad alanının üç genel Servise ulaşmasına izin verir; dolayısıyla başka herhangi bir yerdeki bir ingress denetleyicisi dinliyor olsa bile Nexus'a hizmet veremez. Çözüm her iki çıkış yolunu da belirtir: denetleyiciyi orada dışa açın veya networkPolicy.ingressNamespace değerini çalıştığı yere ayarlayın. ingress.enabled değeri false olduğunda atlanır.
address
İş istasyonunuzdan her biri beş saniye olmak üzere hosts.console, hosts.api ve hosts.auth adreslerini arar ve ana bilgisayar başına bir satır yazdırır. Kaydı olmayan bir ana bilgisayar <host> → no record ile başarısız olur. Ayarlanmamış bir ana bilgisayar hosts.<key> is not set ile başarısız olur. Bir adın birden fazla adresi olduğunda, satır IPv6'dan önce IPv4 olmak üzere ilkini ve kaç tane daha olduğunu gösterir.
certificate
Yalnızca tls.mode değeri existing olduğunda ve tls.existingSecret bir Secret adlandırdığında çalışır; cert-manager veya none ile okunacak size ait bir sertifika yoktur ve satır dışarıda bırakılır. Kurulum ad alanındaki Secret'tan yalnızca tls.crt okur, başka hiçbir şey okumaz. 30 gün veya daha uzun süre geçerli bir sertifika ends 3 Nov 2027 olarak geçer. Daha erken sona erecek olan bir sertifika ends in 9 days uyarısı verir; süresi zaten dolmuş olan bir sertifika ended 4 days ago uyarısı verir. Eksik bir Secret veya içinde sertifika olmayan bir Secret, çözümle birlikte uyarı verir.
custodians
keys.custody.recipients değerini okur. Hiç yoksa KEYS_CUSTODIAN_MISSING koduyla başarısız olur. Herhangi bir alıcı chart'ın kendi değerler dosyalarındaki örnek saklama görevlisi ise KEYS_CUSTODIAN_EXAMPLE ile başarısız olur; çünkü o anahtarı hiç kimse tutmaz ve kurulumun kurtarma anahtarları hiç kimseye mühürlenmiş olur. Başarılı bir geçiş, 3 custodians gibi sayıyı yazdırır.
installation-name
keys.installationName değerini okur. Ayarlanmamışsa INSTALLATION_NAME_MISSING ile başarısız olur. Chart'ın değerler dosyalarındaki örnek ada ayarlanmışsa INSTALLATION_NAME_EXAMPLE ile başarısız olur. Başarılı bir geçiş adı yazdırır. Gereksinimler sütunu, bunun neden çoğundan daha önemli olduğunu söyler: the first key-store bootstrap mints the installation identity under it, permanently.
Son iki denetim, tam olarak chart'ın kendisinin bir kurulumu reddederken kullandığı kodları bildirir. Ön kontrol bunu yalnızca Helm herhangi bir şey oluşturmadan önce size ilk olarak söyler.
Rapor dosyaları
Her çalıştırma, --report-dir içine çalıştığı zamana göre adlandırılan iki dosya kaydeder: preflight-2026-11-12-0902.txt, renk kodları olmadan yazdırıldığı şekliyle satırlar ve preflight-2026-11-12-0902.json, bir programın okuyabileceği sabit bir biçimde aynı çalıştırma. Terminal çıktısı ve kaydedilen satırlar aynı listeden gelir, dolayısıyla asla farklılık göstermezler.
JSON raporu nexus.preflight/v1 şemasını izler:
| Alan | Ne barındırır |
|---|---|
schema |
Tam olarak nexus.preflight/v1 |
tool |
Bir nesne: name (nexusctl) ve version |
release |
Denetlenen sürüm |
ran_at |
Ne zaman çalıştığı, Eşgüdümlü Evrensel Zaman (UTC) cinsinden |
context |
Kube bağlamının adı |
values |
Yalnızca değerler dosyasının temel adı |
read_only |
Her zaman true |
checks |
Satır başına bir girdi: id, section, name, requirement, must_pass, outcome (pass, warn veya fail), found, needs, fix ve makine kaynaklı bir eksiklik durumunda code |
counts |
passed, warnings ve failed |
can_install |
Hiçbir şey başarısız olmadığında true |
report_file |
.txt dosyasının adı |
transcript |
Bir nesne: title (nexusctl preflight) ve lines; her satır kendi kind değeri (prompt, ok, warn, bad, note, out veya blank), text ve at değerleri ve bazen marks ile |
Rapor, herhangi biri oturum açmadan önce gösterilmek üzere oluşturulmuştur; bu nedenle kullanıcı adı, iş istasyonu ana bilgisayar adı, dosya yolu, belirteç (token) ve kubeconfig'inizden hiçbir şey taşımaz. values bir temel addır ve context bağlamın adıdır. Bir çalıştırmanın raporu bu kurallardan herhangi birini ihlal edecek olursa, nexusctl onu yazdırmayı, kaydetmeyi veya teslim etmeyi reddeder ve bunu belirtir. Bir rapor en fazla 256 KiB boyutundadır, en fazla 64 denetim ve herhangi bir metin alanında 512 karakter içerir.
Rapor konsola nasıl ulaşır
Ön kontrolün tek yazma işlemi, herhangi biri kurulumu sahiplenmeden (claim) önce konsolun yükleyicisinin kendi ön kontrol sayfasında gösterebilmesi için kurulumun anahtar servisi olan nexus-keys servisine teslim edilen bitmiş rapordur. Denenip denenmeyeceğine --record karar verir:
--record |
Ne olur |
|---|---|
auto |
Raporu yalnızca ad alanında bir nexus-keys Deployment'ı olduğunda teslim eder |
always |
Israr eder; teslim edecek bir şey yoksa ön kontrol 2 ile çıkar |
never |
Teslim etmez |
Dolayısıyla ilk kurulumdan önceki bir çalıştırmanın teslim edeceği bir yer yoktur ve raporu iş istasyonunuzda tutar. Kurulumdan sonraki ve sahiplenmeden önceki bir çalıştırma ise onu kaydeder.
Teslim işlemi kendi küme erişiminizi kullanır. nexusctl, hazır bir nexus-keys pod'unun keys kapsayıcısında (container) /app/nexus-keys preflight-record çalıştırır ve raporu standart girdide (standard input) iletir. Şununla aynıdır:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonAnahtar servisi, raporu nexusctl aracının uyguladığı aynı kurallara göre denetler ve yalnızca en sonuncusunu tutar. Teslim edildiğinde, nexusctl bunu belirten bir satır daha yazdırır ve kaydedilen JSON, teslim işlemini kaydeden bir note kazanır.
Konsolun yükleyicisi bunu anahtar servisinin genel rotası olan GET /v1/installation/preflight üzerinden okur. Bu rota yalnızca kurulum sahiplenilmemişken yanıt verir: herhangi bir rapor kaydedilmeden önce 404 RECORD_NOT_FOUND yanıtını verir ve birisi kurulumu sahiplendiğinde, tıpkı sahiplenme rotasının yaptığı gibi kalıcı olarak ROUTE_NOT_FOUND yanıtını verir. Sahiplenmeden sonra teslim edilen bir rapor INSTALLATION_CLAIMED ile reddedilir.
Konsolda, hataları olan bir çalıştırma "Ön kontrol devam edemiyor" olarak görünür: başarısız olanların, uyarıların ve geçenlerin sayısı, ardından geçemeyenler ilk sırada ve her birinin yanında bulunan ifadeler olacak şekilde "Geçmesi zorunlu" ve "Geçmesi önerilir" altında gruplandırılmış her denetim. Hatasız bir çalıştırma o sayfayı almaz; konsol doğrudan sahiplenme işlemine geçer (bölüm 2.12, İlk çalıştırma).
Çalıştırmanın ihtiyaç duyduğu erişim
Ön kontrol, kubeconfig'inizle sizin adınıza çalışır. Hesabın şunları okuması gerekir:
- sürüm, hazırlık, kaynaklar ve grafik denetimleri için düğümler;
- depolama sınıfları ve ingress sınıfları;
- ingress ad alanındaki Servisler;
- sertifika denetimi çalıştığında, kurulum ad alanındaki TLS Secret'ı.
Bir okuma reddedildiğinde satır could not read <what> (the cluster refused) der ve çözüm hangi okuma erişiminin verileceğini söyler. Rapor oturum açmadan önce gösterilebileceği için kelimeler asla sunucunun adresini veya kendi hata metnini içermez. Teslim işlemi ayrıca nexus-keys pod'larında pods/exec gerektirir; bu olmadan auto dosyaları kaydedip bir uyarı yazdırır ve always ise 2 ile çıkar.
Ön kontrolün kendisi çalışamadığında
2 çıkış kodu, hiçbir rapor oluşturulmadığı anlamına gelir. Standart hatadaki (standard error) ileti nedenini söyler:
| İleti | Ne yapılmalı |
|---|---|
--context is required: the kube context to check |
--context ekleyin |
--values is required: the values file the install will use |
--values ekleyin |
could not read the values file harrow-values.yaml |
Yolu ve dosyanın izinlerini denetleyin |
preflight takes flags only |
Fazladan argümanı kaldırın |
the report breaks its contract and was not printed, saved or handed over |
Bir alan özel bir şey taşıyacaktı; çalıştırmanın bayraklarıyla birlikte Adverant'a bildirin |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Önce kurulum yapın veya --record auto kullanın |
could not hand the report to this installation |
nexus-keys içine exec yapma erişiminizi denetleyin |
API'sine ulaşılamayan bir küme de 2 ile çıkar. Kubeconfig'i veya ağı düzeltin ve tekrar çalıştırın.
Ön kontrol 0 failed ile sona erdiğinde, Community kurmak için bölüm 2.6, Kubernetes Üzerine Community Kurulumu bölümüne veya Enterprise için bölüm 2.7, Enterprise Kurulumu ve Lisans Uygulama bölümüne geçin.

