サインインブリーフィングを予約

第 2.9 章

インストーラーディスクイメージ

ベアメタルサーバーまたは仮想マシンを Nexus インストーラーイメージから起動すると、ネットワークなしでオペレーティングシステム、k3s、cert-manager、および Nexus がインストールされ、すべてのファイルが使用前に検証されます。

このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

読了時間 17 分

Harrowの東岸壁にある港湾長室にはサーバーが1台あるだけで、インターネット接続はなく、現場にKubernetesを運用できる人もいません。それでもTomás Reillyは、そこにNexusを導入する必要がありました。彼はイメージをUSB(Universal Serial Bus)メモリに書き込み、4行の設定を書いた小さな2本目のメモリをその隣に挿して、サーバーを起動しました。1時間後、画面にはコンソールのアドレスと、hostsファイルに追加すべき3行が表示されました。彼はKubernetesのコマンドを1つも入力しませんでした。

それがインストーラー・ディスクイメージの役割です。サーバーのディスクに最小限のオペレーティングシステムを書き込み、初回起動時に、同梱されているすべてのファイルをAdverantのリリースキーと照合して検証し、ネットワークなしでk3sをインストールし、すべてのイメージをインポートし、cert-managerとNexusをインストールして、すべてのPodが稼働していることを確認します。問題が発生した瞬間、各ステップは明確な理由を示して停止します。機能を縮小して続行する経路はなく、どこにもデフォルトのパスワードは存在しません。

2つのイメージ

各リリースには、amd64とarm64の2つのプロセッサ・アーキテクチャ向けに、2種類のイメージが用意されています。

ファイル 保持する内容 ダウンロード可能な対象者
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso インストーラーのみ:オペレーティングシステム、k3s v1.33.6+k3s1、cert-manager v1.21.3、および初回起動インストーラー。どちらのエディションでも動作し、Nexusのイメージは含まれていません。 どなたでも(downloads.adverant.aiから)
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso 同じインストーラーに、該当エディションのオフラインバンドルがNEXUS-BUNDLEというラベルの付いた第2パーティションとして追加されたもの。1つのメディアですべてをインストールできます。 Community:どなたでも。Enterprise:Adverantアカウントからのみ

<arch>はamd64またはarm64であり、<edition>はcommunityまたはenterpriseです。

インストーラーは常にNEXUS-BUNDLEというラベルの付いたファイルシステムのみを探します。オールインワン・イメージでは、それはイメージ自体のパーティションです。インストーラーのみのイメージでは、そのラベルを付けた2つ目のディスクまたはメモリでバンドルを持ち込みます。これは、1本のインストーラー・メモリから複数の拠点にインストールし、バンドルだけを変更する場合に便利です。バンドルについては、第2.10章「エアギャップ環境でのインストール」で説明しています。

EnterpriseイメージとEnterpriseバンドルは、匿名で提供されることは決してありません。https://account.adverant.aiにあるご自身のAdverantアカウントのダウンロードページで、ライセンスの横からダウンロードします。Communityイメージとバンドルは一般公開されています。

2つのディスクの図が並んでいます。左側の「インストーラーのみのイメージ(installer-only image)」には、「オペレーティングシステム・インストーラー、k3s、cert-manager、初回起動インストーラー」というラベルの付いた1つのパーティションがあり、その横に「NEXUS-BUNDLE:エディションのオフラインバンドル」というラベルの付いた別のUSBメモリがあります。右側の「オールインワン・イメージ(all-in-one image)」には、同じ第1パーティションと、同じディスク上に「NEXUS-BUNDLE」というラベルの付いた第2パーティションがあります。両方の下には、小さなUSBメモリがあり、「NEXUS-SEED:seed.yaml、およびEnterprise用のlicence.json」というラベルが付き、「Communityではオプション」という注記があります。3つのラベルすべてから下に向かって、「初回起動時にラベルによってそれぞれを検出」という1つのボックスへ矢印が伸びています。
インストーラーのみのイメージとオールインワン・イメージ、および初回起動時に各パーツが検出される場所。

イメージの構成要素

オペレーティングシステムはDebian 13をベースとしていますが、公式のDebianイメージではありません。Debianの基本システムのみが含まれており、他には何もありません(追加パッケージ、デスクトップ、ミラーは一切ありません)。k3sは独自のコンテナランタイムとネットワーキングを備えています。ブートチェーン(shim、GRUB、カーネル、および初期RAMディスク)はDebianが出荷するものとバイト単位で同一であるため、セキュアブートが有効なマシンでも通常のDebianインストーラーと同様に起動します。

同じリリースの2回のビルドは、バイト単位で同一のイメージを生成し、そうなるまでリリースは公開されません。イメージ上のすべてのバイナリに対応するDebianソースパッケージは、同じチェックサムリスト内のnexus-alpha-installer-1.0.0-alpha.1-debian-source.tarとして、イメージと並べて公開されます。

書き込む前にダウンロードを確認する

downloads.adverant.ai上のイメージディレクトリには、イメージ、公開されているすべてのファイルを網羅するSHA256SUMSファイル、およびAdverantのリリースキーでそのリストに対して作成された署名であるSHA256SUMS.sigstore.jsonが格納されています。リリースの公開鍵を別途取得してrelease.pubとして保存し、第2.4章「リリースの取得と検証」の説明に従ってそのフィンガープリントを確認してください。

  1. チェックサムリストの署名を検証します。Nexusのリリースには透明性ログ(Transparency Log)がないため、ログの検索をスキップするフラグが必要です。
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. ダウンロードしたイメージをリストと照合して確認します:
grep nexus-alpha-community-1.0.0-alpha.1-amd64.iso SHA256SUMS | sha256sum -c -
nexus-alpha-community-1.0.0-alpha.1-amd64.iso: OK

Macでは、sha256sum -c -の代わりにshasum -a 256 -c -を使用してください。

  1. 普段使用しているツールでイメージをUSBメモリに書き込むか、光学ディスクとして仮想マシンにアタッチします。

k3sはリリースファイルのチェックサムを公開しており、署名は公開していないため、イメージ内のk3sファイルは、ファイルと同じオリジンからk3sが公開しているチェックサムと照合されます。Adverantがビルドしたものはすべて署名されています。

分割されたバンドル

別のメモリで持ち運ぶバンドルは数ギガバイトになります。FAT(File Allocation Table)をはじめとする一部のファイルシステムは4 GiB以上のファイルを保持できないため、バンドルファイルはどのメモリにも収まるよう2047 MiBの断片に分割して公開されています。使用する前に、断片を順番通りに結合し、結合されたファイルをその.sha256と照合して確認してください。

必要なハードウェア

初回起動時は、何かに手を加える前にマシンをチェックし、マシンが小さすぎる場合は続行を拒否します。

チェック項目 フロア チェックされるタイミング
アーキテクチャ イメージ自身のもの:amd64上ではamd64イメージ、arm64上ではarm64 初回起動時
メモリ 16 GiB 初回起動時
ターゲットディスク 64 GB以上の空のディスクが正確に1つ、またはシードが指定するディスク オペレーティングシステムが書き込まれる前
/の空き容量 オペレーティングシステム配置後に50 GB 初回起動時
クロック イメージがビルドされた日付より古くないこと 初回起動時

これらは最低限の基準であり、推奨値ではありません。チャートのデフォルト設定では、Nexusのボリュームだけで合計142 GiBになるため、64 GBのディスクはインストーラーを通過しても数日以内にいっぱいになります。シングルノードが備えるべきスペックを使用してください:8 vCPU(仮想中央処理装置)、32 GiBのメモリ、および250 GBのSSD(ソリッドステートドライブ)。評価用であれば、4 vCPU、16 GiB、200 GBで十分です。

クロックのチェックがあるのは、インストール時にサーバーにネットワークがなく、したがって時刻サービスもないためです。証明書と署名はクロックに照らしてチェックされます。マシンのハードウェアクロックがイメージのビルド日時より遅れている場合、初回起動は停止し、設定するよう求められます。ファームウェアのセットアップで設定してから、再度起動してください。

ベアメタルと仮想マシン

このイメージは、物理サーバーでも仮想マシンでも同様に、UEFI(Unified Extensible Firmware Interface)ファームウェア上で起動します。通常のパスだけでなくリムーバブルメディアのパスにもブートローダーをインストールするため、保存されたブートエントリを持たないVM(仮想マシン)でも、最初の再起動後にそれを見つけることができます。VMには、上記の表にあるメモリとディスク、1つの空の仮想ディスク、およびCDとしてのイメージを割り当ててください。

インストーラーは厳格なルールに従ってターゲットディスクを選択し、「最初のディスク」を選ぶことは決してありません。

  • 起動元のメディアをスキップします。
  • シードで指定されていない限り、リムーバブルディスクをスキップします。
  • 種類を問わず、すでにパーティションテーブルが存在するディスクをスキップします。
  • 64 GB未満のディスクをスキップし、その旨をコンソールに表示します。
  • 残ったディスクが正確に1つである場合にのみインストールします。

空のディスクが2つあるサーバーでは、停止して選択を求めます。選択するには、シード内でwipe: trueとともにディスクを指定します。すでにパーティションがあるディスクに書き込むには、この方法しかありません。

NEXUS-SEED ボリューム

シードとは、通常はUSBメモリである小さなボリュームで、NEXUS-SEEDというラベルの付いたファイルシステムを持ち、その最上位階層にファイルseed.yamlがあります。インストーラーはこれを読み取り専用でマウントして設定を読み取り、オペレーティングシステムのパスワードを残すために、一番最後の段階でだけ書き込み可能として再マウントします。

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
キー 設定する内容 省略された場合
domain インストールのドメイン。インストーラーはこれから3つのホスト(console.<domain>、api.<domain>、およびauth.<domain>)を導き出します。 サーバーのコンソールで尋ねられます
adminEmail 最初の管理者となる人物のメールアドレス サーバーのコンソールで尋ねられます
edition communityまたはenterprise。設定する場合、バンドルのエディションと一致している必要があります。 バンドルから取得されます
timeout cert-managerとNexusのインストールに許容される所要時間(30mや1hなどの期間形式) 30m
time ハードウェアクロックを設定できない、または設定を保持できないマシン向けの、クロックメッセージが表示する形式(2026-11-14T09:00:00Z)でのUTCの現在時刻。オフラインのマシンには問い合わせるタイムサーバーがありません。 ハードウェアクロックが使用されます
disk /dev/<name>としてのターゲットディスク(wipe: trueと併用する場合のみ使用) 上記の空ディスクのルール
wipe trueにより、インストーラーはdiskが指定するディスクを消去できるようになります ディスクは一切消去されません

Enterpriseの場合、ライセンスファイルをlicence.jsonとして同じボリュームに配置してください。これがないと、初回起動はシードのステップで停止し、ライセンスがない旨を表示します。Communityはライセンスを必要とせず、Communityではシード全体がオプションです。インストーラーはコンソールでドメインとメールアドレスを尋ねてから処理を続行します。

インストーラーは各行を行頭のkey: valueとして読み取ります。最上位階層に、引用符やインデントなしで、1行につき1つのキーを記述してください。引用符で囲まれた値は、引用符も含めて読み取られます。

初回起動時、インストーラーはコンソールでキーストアのカストディアン(管理者)についても尋ねます。これは、カストディアン自身のマシンでage-keygen -o custodian.keyを使って作成された、ageキーの公開部分(age1...)です。キーストアはそのリカバリキーをこれに封印(シール)します。カストディアンについては、第2.8章「単一マシンへのインストール」で説明しています。カストディアンは秘密部分をオフラインで安全に保管します。これがないと、再起動後に誰もキーストアの封印を解除(アンシール)できなくなります。

電源オンからコンソールアドレス表示までの流れ

ステージ1:オペレーティングシステム

イメージは自動実行のDebianインストーラーとして起動します。ネットワークの構成、ミラーの使用、基本システム以外のパッケージのインストールは行いません。タイムゾーンをUTC(協定世界時)に設定し、rootログインを無効にし、パスワードがロックされた1つのユーザー(nexus)を作成します。上記のルールに従ってターゲットディスクを選択し、EFI(Extensible Firmware Interface)システムパーティションと1つのext4ルートファイルシステムを持つGPT(GUIDパーティションテーブル)ディスクを、スワップなしで書き込みます。

最後に、Nexusインストーラーを新しいシステムにコピーし、コピーされたすべてのファイルをイメージのチェックサムリストと照合して、初回起動サービスを有効にします。コピーされたファイルのいずれかが一致しない場合は、そこで停止します。その後、メディアをイジェクトして再起動します。

ステージ2:初回起動

初回起動時に、サービスnexus-installが1回実行されます。すべてのステップはサーバーのコンソールとジャーナルに出力され、完了として自身を記録するため、再試行時は未完了の最初のステップから再開されます。サービス全体は、systemdによって停止されるまで最大4時間実行される場合があり、これによって低速なディスクや、バンドル用メモリが挿されるまでの1時間の待機に対応できる余裕が確保されています。

  1. プリフライト(Preflight)。上記の表にある通りの、アーキテクチャ、クロック、メモリ、およびディスクの空き容量。
  2. ペイロード(Payload)。インストーラー自身のファイル:保持しているリリースキーを使ったチェックサムリストの署名、次にそのリストに対するすべてのファイル。
  3. シード(Seed)。seed.yamlを読み取り、不足しているものがあればコンソールで尋ねます。
  4. バンドル(Bundle)。NEXUS-BUNDLEというラベルの付いたボリュームを見つけて、読み取り専用でマウントします。存在しない場合はwaiting-for-bundleと表示し、アタッチされるまで最大1時間待機します。その後、何かをインポートする前に、保持しているリリースキーを使って、最後にVERIFY-BUNDLE PASSを出力する完全なバンドルチェックを実行します。Enterpriseバンドルにはシード上のlicence.jsonが必要であり、シードのエディションはバンドルのものと一致している必要があります。
  5. k3s。ダウンロードをオフにした状態でイメージ自身のファイルからk3s v1.33.6+k3s1をインストールし、ノードがReadyになるまで最大10分間待機します。その後、起動のたびにイメージが再インポートされないよう、k3sのエアギャップ・イメージアーカイブを削除します。
  6. インポート(Import)。検証済みのすべてのイメージをバンドルから、そしてcert-managerのイメージを、ノードのコンテナストアにインポートします。レジストリからプルされることは一切ありません。
  7. cert-manager、次にNexus。シードのtimeoutの時間内に、cert-manager v1.21.3をインストールし、次にバンドルからNexusチャートをインストールします。
  8. 受け入れ(Acceptance)。すべてのPodがRunningであり、すべてのフックJobが完了していることを確認します。
  9. 認証情報(Credential)。オペレーティングシステムのユーザーnexusに新しいランダムなパスワードを付与し、コンソールに1回表示して、シードボリュームが書き込み可能な場合はそのボリューム上のnexus-os-password.txtに書き込みます。

ステップ4のバンドルチェックは、第2.10章「エアギャップ環境でのインストール」で手動で実行するものと同じスクリプトであり、同じ行を出力します:

  1 SHA256SUMS OK files=<n>
  2 SHA256SUMS signature OK
  3 images signed + SBOM-attested: <n>
  4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
  5 coverage OK rendered=<n> lock=<n>
  6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>

3行目は、有効な署名と、各イメージに含まれるもののリストである署名付きSBOM(ソフトウェア部品表)を持つイメージの数をカウントします。カウント数(<n>)はエディションによって異なります。重要なのは最後の行です。

インストールでは、チャートの現在の形式で値を書き込みます:シードのドメインからのglobal.domainと3つのhosts.*名、およびコンソールで指定したカストディアンからのkeys.custody.recipientsです。バンドル自身のチャートとイメージからインストールされるため、ディスク上のリリースはチェックされたリリースと完全に一致します。

水平に連なる9つのボックス:Preflight、Payload、Seed、Bundle、k3s、Import、cert-manager and Nexus、Acceptance、Credential。各ボックスの下には、それを停止させる原因を示す短い赤いラベルがあります:「メモリ、ディスク、クロック、アーキテクチャ」、「署名またはチェックサム」、「ドメインまたはメールアドレスなし;Enterpriseのライセンスなし」、「1時間以内にNEXUS-BUNDLEなし;VERIFY-BUNDLE FAIL」、「10分以内にノードがReadyにならない」、「イメージがインポートできない」、「タイムアウト時間内にhelm installが失敗」、「Podが実行されていない、Jobが未完了」、そしてCredentialの下には何もありません。すべてのボックスからチェーンの先頭に戻る矢印には、「nexus-install retryは未完了の最初のステップから再開する」というラベルが付いています。
インストーラーイメージの初回起動。ステップが1つずつ順番に実行され、各ステップはインストールを停止させることができます。

コンソールの最後の行

すべてのステップを通過すると、コンソールにはオペレーティングシステムのパスワードが1回表示され、開くべきアドレスが示されます:

nexus-install: OS login: user nexus, password <shown-once>  (shown once; change it with passwd)
nexus-install: DONE: https://console.harrow.example  (add to /etc/hosts: 10.20.4.15 console.harrow.example api.harrow.example auth.harrow.example)

パスワードを書き留めるかシードメモリから取得し、nexusとしてログインしてpasswdで変更してください。デフォルトのパスワードは存在しないため、Adverantを含め、誰もこのマシンのデフォルトパスワードを知りません。

hostsの行にあるアドレスは、サーバー自身のものです。岸壁にはDNS(Domain Name System)がないため、Tomásはコンソールを使用する各ノートパソコンのhostsファイルにその1行を追加しました。DNSがある拠点では、代わりに3つの名前のレコードを追加してください。

準備完了、または未完了
準備完了、または未完了
インストール後、準備完了リストにはアウトバウンドトラフィックのテストが含まれるため、オペレーターは直近1時間に外部へ出ようとした通信が皆無であったことを証明できます。

インストール後

インストールされた環境は未請求(unclaimed)の状態です。誰かがブラウザでインストールのフィンガープリントとサーバーが表示するものを比較して請求(クレーム)を行うまで、誰もサインインできません。請求、最初の管理者、およびパスキーについては、第2.12章「初回実行」で扱っています。最初の管理者は、シードにメールアドレスが記載されている人物であるべきです。

ノード自身のkubeconfigは/etc/rancher/k3s/k3s.yamlにあり、rootのみが読み取り可能です。ワークステーションからクラスタで作業するには、第2.8章「単一マシンへのインストール」で説明されているように、nexusctl kubeconfigでそれを出力します。

アップデートはインストールと同じ方法で届きます。つまり、署名されたメディア上のリリースとして提供され、ディスクが持ち込むキーではなく、すでにサーバーにインストールされているキーと照合してチェックされます。そのチェックについては、第2.10章「エアギャップ環境でのインストール」で説明しています。

このインストール環境をクレームする
このインストール環境をクレームする
インストール後に表示される請求ページ。サーバーのコンソールと1行ずつ比較できるよう、フィンガープリントは4文字ずつ8つのグループで表示されます。

これが失敗する場合

失敗すると、いかなる場合もコンソールにnexus-install: FAILED <step>: <what is missing>が表示され、/var/lib/nexus/install.stateに同じ内容が書き込まれます。原因を修正し、未完了の最初のステップからインストールを再実行してください:

sudo nexus-install retry
メッセージ 意味 対処法
FAILED preflight: payload is for arm64, this machine is amd64 別のアーキテクチャのイメージを起動しました。 このマシンのアーキテクチャ用のイメージを使用してください。
FAILED preflight: memory 11 GiB, need >= 16 GiB マシンが最低基準を下回っています。 メモリを追加するか、VMにより多く割り当ててください。
FAILED preflight: free disk 38 GB on /, need >= 50 GB ルートファイルシステムが小さすぎます。 より大きなディスクにインストールしてください。
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed ハードウェアクロックがインストーラーのビルド日時より遅れています。 ファームウェアでクロックを設定するか、seed.yamlでtimeを指定して、再試行してください。
FAILED payload: SHA256SUMS signature does not verify インストーラー自身のファイルが、Adverantが署名したものではありません。 中止してください。イメージを再度ダウンロードし、書き込む前に確認してください。
FAILED seed: the installation domain and the first administrator e-mail are required シードからもコンソールからもそれらが与えられませんでした。 それらをseed.yamlに追加するか、プロンプトに回答してください。
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) バンドルがEnterpriseであり、シードにライセンスがありません。 シードボリュームにlicence.jsonを配置してください。
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h 時間内にバンドルがアタッチされませんでした。 バンドルメモリをアタッチして、再試行してください。
FAILED bundle: the bundle does not verify with this installer's release key バンドルチェックがVERIFY-BUNDLE PASSで終わりませんでした。メッセージの上にあるその出力自体が、該当するステップを示しています。 中止してください。そのバンドルは使用しないでください。新しいものを取得してください。
FAILED bundle: the seed asks for enterprise, the bundle is community シードとバンドルが一致していません。 シード内のeditionを修正するか、正しいバンドルを用意してください。
FAILED k3s: node not Ready within 10 min k3sが起動しませんでした。 k3sのジャーナルを確認してから、再試行してください。
FAILED nexus: helm install nexus タイムアウト時間内にチャートがインストールされませんでした。 kubectl -n nexus get pods,jobsを確認し、マシンが低速な場合はシード内のtimeoutを引き上げてから、再試行してください。
FAILED acceptance: pods not ready インストール後に一部のPodが実行されていません。 メッセージには最大5つまで名前が挙げられます。それらのイベントを読み、修正して、再試行してください。
FAILED acceptance: jobs not complete: <jobs> フックJobが完了していません。 指定されたJobのログをkubectl -n nexus logs job/<name>で読み、報告されている内容を修正して、再試行してください。

オペレーティングシステムが書き込まれる前に、ディスクの選択によってインストールが停止することもあります。そのメッセージはnexus select-disk: REFUSED:で始まります。よくあるものはfound 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: trueです。シード内でディスクを指定し、再度起動してください。

バンドルチェックの失敗は、重く受け止めるべきものです。これは、ディスク上のファイルがAdverantが署名したファイルではないか、ファイルが追加されたことを意味します。インストーラーはその時点では何もインポートしていないため、サーバーは変更されていません。セキュリティチームのためにそのディスクを保管してください。