バージョン 1.0.0-alpha.1最新
第 2.5 章
nexusctlによるプリフライト
`nexusctl preflight`が実行するすべてのチェック、各チェックが何を読み取りどのように失敗するか、出力および保存されるレポート、そのレポートがコンソールのプリフライトページに到達する仕組み、そしてすべてのフラグについて説明します。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

Harrow Port Authorityでの最初のプリフライトでは4つのチェックが失敗し、そのうち2つは半日どころでは済まない損失をもたらすところでした。私たちはチャートの例をコピーしてvaluesファイルを作成し始めましたが、プリフライトは例のインストール名と例のカストディアンの両方を拒否しました。そのカストディアンの秘密鍵は誰も保有していません。それでシールされたインストールは、ノードの再起動後にアンシールできなくなります。プリフライトは、失うものが何もない段階で、わずか数秒のうちにそれを検出しました。
nexusctl preflightはクラスタとvaluesファイルを読み取り、検出した内容を出力し、レポートを保存しますが、クラスタには一切変更を加えません。すべてのインストールおよびアップグレードの前に実行してください。この章では、実行されるすべてのチェック、レポート形式、レポートの保存先、およびフラグについて説明します。
運用
プリフライトには、インストール先クラスタのkubeコンテキストと、インストールで使用するvaluesファイルの2つが必要です。まずvaluesファイルを作成してください。すべてのキーについては、第2.6章「KubernetesへのCommunityのインストール」で順を追って説明しています。次に、以下を実行します。
nexusctl preflight --context harrow-prod --values harrow-values.yamlこれは、getおよびlist呼び出しのみを使用してclient-go経由でクラスタを読み取ります。tls.modeがexistingである場合は、実行する前にnexus名前空間とTransport Layer Security (TLS) Secretを作成してください(第2.6章「KubernetesへのCommunityのインストール」のステップ3)。そうしないと、証明書チェックでSecretが見つからないと報告されます。
| フラグ | 行うこと | デフォルト |
|---|---|---|
--context <name> |
チェックするkubeコンテキスト。必須 | なし |
--values <file> |
インストールで使用するvaluesファイル。必須 | なし |
--namespace <name> |
Nexusのインストール先 | nexus |
--release <version> |
チェック対象のリリース | バンドルされたチャート自身のバージョン |
--report-dir <dir> |
2つのレポートファイルの保存先 | 現在のフォルダ |
--record <mode> |
auto、always、またはnever: インストーラページに表示されるよう、このインストールのキーサービスにレポートを渡すかどうか |
auto |
--kubeconfig <file> |
読み取るkubeconfig | KUBECONFIG、次に~/.kube/config |
--ca-bundle <file> |
チェックで信頼すべきチェーン用の、独自の認証局 (CA) 証明書 | なし |
--single-node |
単一マシンインストール用に1台のマシンをチェックする(第2.8章「単一マシンへのインストール」) | オフ |
このリリースにおけるKubernetesの最低要件はnexusctlに直接記述されていません。内包するチャート自身のkubeVersionの下限を読み取るため、チェックとhelm installが食い違うことは決してありません。
実行時に出力される内容
以下は、Harrowでの初回実行時の出力結果です。
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
失敗がある場合は、最初に失敗、次に警告、その後に合格が表示されます。各行には、結果、チェック名、検出された内容、および必要な要件が表示されます。合格しなかったすべての行の下にはfix行が付きます。最後の2行はサマリーとレポートファイルです。
私たちは値を修正し、2つのDomain Name System (DNS) レコードを追加し、Secretを作成してから再実行しました。
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
失敗がない実行では、Cluster、Network、Time and keysの3つの見出しの下にチェックが一覧表示されます。警告によってブロックされることはありません。グラフィックスの警告は意図的に残しました。この接続されたパイロットクラスタでは、Harrowのアシスタントは港独自のキーを使用してホスト型モデルを利用していたためです。
終了コード
| コード | 意味 |
|---|---|
0 |
インストールを続行できます。警告はブロックしません |
1 |
インストールがブロックされました: 少なくとも1つのチェックが失敗しました |
2 |
プリフライトを実行できませんでした: kubeconfig、コンテキスト、valuesファイル、またはクラスタのアプリケーションプログラミングインターフェース (API) を読み取れなかったか、フラグが間違っていました |
スクリプトはテキストではなく終了コードを読み取るべきです。私たちのスクリプトは、すべてのアップグレードの最初のステップとしてプリフライトを実行し、0以外のコードが出た場合は停止します。
インストール時に使用したものではなく、移行先のリリースのnexusctlを実行してください。要件は内包するチャートから取得されるため、新しいリリースではKubernetesの最低要件が引き上げられたり、より多くのメモリが要求されたりすることがあり、それはそのリリース自身のnexusctlしか把握していません。--releaseはレポートに記載されるバージョンを変更するだけで、どのチャートのルールを適用するかは変更しません。Harrowでは、変更記録内で各リリースのnexusctlをそのチャートの横に保管しているため、ロールバック時にはそれに一致するツールでチェックが行われます。
すべてのチェック項目
チェックは11個あります。そのうち10個はそれぞれ1行を生成し、アドレスチェックはホストごとに1行を生成するため、完全な実行では13行になります。9個のチェックは合格が必須であり、満たさない場合は失敗となります。グラフィックスノードと証明書の2つは合格が推奨され、満たさない場合は警告となります。最後の列は、各行がレポートに出力する要件テキストです。その中のCPUは中央処理装置を指します。
| チェックID | セクション | 合格必須 | 出力される要件 |
|---|---|---|---|
kubernetes-version |
cluster | yes | Kubernetes 1.33以降 |
nodes-ready |
cluster | yes | すべてのノードがReady状態 |
storage-class |
cluster | yes | データ用のストレージクラス |
resources |
cluster | yes | リリースに十分なCPUとメモリ |
graphics-nodes |
cluster | no | グラフィックスノード |
ingress-class |
network | yes | 3つのアドレス用のIngressクラス |
ingress-ports |
network | yes | ポート80および443で開いているIngressコントローラ |
address-console, address-api, address-auth |
network | yes | console、api、またはauthアドレスがDNSで解決されること |
certificate |
network | no | 証明書が残り30日以上有効であること |
custodians |
time-and-keys | yes | このインストールのリカバリキーを保持する担当者 |
installation-name |
time-and-keys | yes | このインストール固有の永続的な名前 |
kubernetes-version
APIサーバーのバージョンを読み取り、チャートの最低要件と比較します。たとえば1.33.6+k3s1などを検出します。1.33未満の場合は失敗し、修正方法としてupgrade the cluster to 1.33 or laterが示されます。バージョン文字列がnexusctlで読み取れる形式でない場合、推測はせず失敗とします。
nodes-ready
ノードを一覧表示し、Ready条件がtrueであるノードを3 of 3のようにカウントします。Readyでないノードがあればその名前が挙げられ、修正方法としてReadyに戻してその条件を確認するよう指示されます。ノードが1つもないクラスタは失敗となり、コンテキストが間違ったクラスタを指している可能性があるというヒントが表示されます。
storage-class
valuesでstorage.classNameが設定されている場合、チェックはそのクラスを検索し、見つからない場合は<name> does not existで失敗します。設定されていない場合は、デフォルトとしてマークされたクラスを検索し、それをlocal-path (default)として報告します。デフォルトがない場合はnone marked defaultで失敗し、needs列にそれが重要である理由(the database cannot claim a disk)が示されます。2つのクラスがデフォルトとしてマークされている場合、クラスタは新しい要求に対して最新のものを割り当てるため、そのクラスが報告されます。
resources
チャートとvaluesからリリースが要求するリソースを算出し、Ready状態であり、cordonされておらず、NoScheduleやNoExecuteのtaintを持たないすべてのノードの割り当て可能な中央処理装置 (CPU) コア数とメモリを合計します。チャートのPodにはtolerationがないため、taintされたノードでは実行できず、カウントされません。クラスタのリソースが不足している場合は、add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yamlのように正確な不足分を示して失敗します。必要量は切り上げられ、供給量は切り捨てられるため、チェックが実際より良く見せることはありません。
graphics-nodes
割り当て可能なグラフィックス処理装置 (GPU) nvidia.com/gpuを持つReadyノードを検索します。存在しない場合は、the assistant will need a hosted modelと警告します。アシスタントは代わりにホスト型の人工知能 (AI) モデルを通じて応答できるため、プリフライトはこれをアドバイスとして扱い、ブロックすることはありません。両方の経路については、第2.14章「AIプロバイダーとモデル」で説明しています。
ingress-class
ingress.classNameが設定されている場合、チェックはそのクラスを検索します。設定されていない場合は、デフォルトとしてマークされたクラスが正確に1つあるかを検索します。デフォルトとしてマークされたクラスが2つある場合も失敗します。これは、APIサーバーがクラス指定のないIngressを拒否するためです。ingress.enabledがfalseの場合、このチェックはスキップされ、行も省かれます。
ingress-ports
networkPolicy.ingressNamespaceで指定された名前空間(デフォルトはk3sがTraefikを実行するkube-system)内で、80と443の両方を公開するLoadBalancerまたはNodePort Serviceを1つ検索します。チャートのネットワークポリシーにより、その名前空間のみが3つのパブリックServiceに到達できるため、他の場所にあるIngressコントローラは、たとえリッスンしていてもNexusにサービスを提供できません。修正方法には、その場所でコントローラを公開するか、コントローラが実行されている場所をnetworkPolicy.ingressNamespaceに設定するかの両方の解決策が示されます。ingress.enabledがfalseの場合はスキップされます。
address
ワークステーションからhosts.console、hosts.api、およびhosts.authをそれぞれ5秒間で検索し、ホストごとに1行を出力します。レコードのないホストは<host> → no recordで失敗します。未設定のホストはhosts.<key> is not setで失敗します。1つの名前に複数のアドレスがある場合、行にはIPv6よりIPv4を優先して最初のアドレスを表示し、他にあと何個あるかを示します。
certificate
tls.modeがexistingであり、tls.existingSecretがSecretを指定している場合にのみ実行されます。cert-managerまたはnoneの場合は読み取るべき独自の証明書がないため、行は省かれます。インストール名前空間内のSecretからtls.crtのみを読み取り、他には何も読み取りません。30日以上有効な証明書はends 3 Nov 2027として合格します。それより早く期限が切れるものはends in 9 daysと警告し、すでに期限が切れているものはended 4 days agoと警告します。Secretが見つからない場合、またはSecret内に証明書がない場合は、修正方法とともに警告します。
custodians
keys.custody.recipientsを読み取ります。指定がない場合はコードKEYS_CUSTODIAN_MISSINGで失敗します。受信者のいずれかがチャート自身のvaluesファイルにある例のカストディアンである場合、そのキーは誰も保持しておらず、インストールのリカバリキーが誰にもシールされないことになるため、KEYS_CUSTODIAN_EXAMPLEで失敗します。合格すると、3 custodiansのように数が表示されます。
installation-name
keys.installationNameを読み取ります。未設定の場合はINSTALLATION_NAME_MISSINGで失敗します。チャートのvaluesファイルにある例の名前に設定されている場合はINSTALLATION_NAME_EXAMPLEで失敗します。合格するとその名前が表示されます。needs列には、これが他の多くの項目よりも重要である理由(the first key-store bootstrap mints the installation identity under it, permanently)が示されます。
最後の2つのチェックは、チャート自身がインストールを拒否する際のコードをそのまま報告します。プリフライトは、Helmが何かを作成する前に、それを先に知らせてくれるだけです。
レポートファイル
実行するたびに、実行時刻にちなんだ名前で2つのファイルが--report-dirに保存されます。カラーコードなしで出力された通りの行を含むpreflight-2026-11-12-0902.txtと、プログラムが読み取れる固定形式で同じ実行内容を記録したpreflight-2026-11-12-0902.jsonです。ターミナルの出力と保存される行は同じリストから生成されるため、食い違うことは決してありません。
JSONレポートはスキーマnexus.preflight/v1に従います。
| フィールド | 保持する内容 |
|---|---|
schema |
正確にnexus.preflight/v1 |
tool |
オブジェクト: name(nexusctl)およびversion |
release |
チェックされたリリース |
ran_at |
実行日時(協定世界時 (UTC)) |
context |
kubeコンテキストの名前 |
values |
valuesファイルのベース名のみ |
read_only |
常にtrue |
checks |
行ごとに1つのエントリ: id、section、name、requirement、must_pass、outcome(pass、warn、またはfail)、found、needs、fix、およびマシン起因で満たさなかった場合はcode |
counts |
passed、warnings、およびfailed |
can_install |
何も失敗しなかった場合はtrue |
report_file |
.txtファイルの名前 |
transcript |
オブジェクト: title(nexusctl preflight)およびlines。各行にはkind(prompt、ok、warn、bad、note、out、またはblank)、textとat、および場合によってはmarksが含まれます |
レポートは誰かがサインインする前に表示されるように作られているため、ユーザー名、ワークステーションのホスト名、ファイルパス、トークン、およびkubeconfigからの情報は一切含まれません。valuesはベース名であり、contextはコンテキストの名前です。実行のレポートがこれらのルールのいずれかに違反する場合、nexusctlは出力、保存、または引き渡しを拒否し、その旨を伝えます。レポートは最大256 KiBで、チェックは最大64個、1つのテキストフィールドは最大512文字です。
レポートがコンソールに到達する仕組み
プリフライトが行う唯一の書き込みは、完成したレポートをインストールのキーサービスであるnexus-keysに渡すことです。これにより、誰かがインストールの所有権を主張(クレーム)する前に、コンソールのインストーラがそのプリフライトページにレポートを表示できるようになります。試行するかどうかは--recordによって決まります。
--record |
動作内容 |
|---|---|
auto |
名前空間にnexus-keys Deploymentがある場合にのみレポートを渡します |
always |
強制します。渡す相手がない場合、プリフライトは2で終了します |
never |
レポートを渡しません |
したがって、初回インストール前の実行では渡す相手が存在しないため、レポートはワークステーション上に保持されます。インストール後かつクレーム前の実行では、レポートが記録されます。
引き渡しには自身のクラスタアクセスが使用されます。nexusctlは、Ready状態のnexus-keys Podのkeysコンテナ内で/app/nexus-keys preflight-recordを実行し、標準入力でレポートを渡します。これは以下と同じです。
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonキーサービスは、nexusctlが適用するのと同じルールに照らしてレポートをチェックし、最新のものだけを保持します。引き渡しが完了すると、nexusctlはその旨を伝える行をもう1行出力し、保存されたJSONには引き渡しを記録するnoteが追加されます。
コンソールのインストーラは、キーサービスのパブリックルートGET /v1/installation/preflightからそれを読み取ります。そのルートは、インストールが未クレームの間だけ応答します。レポートが記録される前は404 RECORD_NOT_FOUNDと応答し、誰かがインストールをクレームすると、クレームルートとまったく同じように、以降は永続的にROUTE_NOT_FOUNDと応答します。クレーム後に渡されたレポートはINSTALLATION_CLAIMEDで拒否されます。
コンソール上では、失敗のある実行は「Preflight cannot continue」として表示されます。失敗、警告、合格の数が示され、その後にすべてのチェックが「Must pass」と「Should pass」の下にグループ化され、合格しなかったものが先頭に、検出された内容がそれぞれの横に表示されます。失敗のない実行ではそのページは表示されず、コンソールはそのままクレームに進みます(第2.12章「初回実行」)。
実行に必要なアクセス権限
プリフライトは、あなたのkubeconfigを使用してあなた自身として実行されます。アカウントには以下の読み取り権限が必要です。
- ノード(バージョン、Ready状態、リソース、およびグラフィックスのチェック用)
- ストレージクラスおよびIngressクラス
- Ingress名前空間内のService
- インストール名前空間内のTLS Secret(証明書チェックが実行される場合)
読み取りが拒否された場合、行にはcould not read <what> (the cluster refused)と表示され、修正方法には付与すべき読み取りアクセス権が示されます。レポートはサインイン前に表示される可能性があるため、文言にサーバーのアドレスやサーバー自身のエラーテキストが含まれることは決してありません。また、引き渡しにはnexus-keys Podに対するpods/execも必要です。これがない場合、autoはファイルを保存して警告を出力し、alwaysは2で終了します。
プリフライト自体を実行できない場合
終了コード2は、レポートが作成されなかったことを意味します。標準エラー出力のメッセージにその理由が示されます。
| メッセージ | 対処法 |
|---|---|
--context is required: the kube context to check |
--contextを追加してください |
--values is required: the values file the install will use |
--valuesを追加してください |
could not read the values file harrow-values.yaml |
パスとファイルの権限を確認してください |
preflight takes flags only |
不要な引数を削除してください |
the report breaks its contract and was not printed, saved or handed over |
フィールドにプライベートな情報が含まれる可能性がありました。実行時のフラグを添えてAdverantに報告してください |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
先にインストールするか、--record autoを使用してください |
could not hand the report to this installation |
nexus-keysへのexecアクセス権を確認してください |
APIに到達できないクラスタも2で終了します。kubeconfigまたはネットワークを修正して、再実行してください。
プリフライトが0 failedで終了したら、Communityをインストールする場合は第2.6章「KubernetesへのCommunityのインストール」へ、Enterpriseの場合は第2.7章「Enterpriseのインストールとライセンスの適用」へ進んでください。

