バージョン 1.0.0-alpha.1最新
第 2.8 章
単一マシンへのインストール
nexusctl を使用して1台の Linux サーバーに Nexus をインストールするか、k3d を使用してノート PC で評価を行い、サインインとパスキーが機能するように HTTPS 経由でコンソールにアクセスします。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

Harrow Port Authorityが本番クラスターにNexusを導入する前、Tomás Reillyは2つの小規模なインストールを望んでいました。1つは、最初に試用する12人のために、運用棟の予備のLinuxサーバーに構築するパイロット環境でした。もう1つは、誰にも気づかれずにいろいろ試して壊せるように、自身のノートPC上で実行する環境でした。本章ではこの両方を扱います。これらは完全なKubernetesインストールと同じチャート、同じイメージ、同じ初回実行を使用するため、1台のマシンで学んだことはそのまま次に活かせます。
サーバーでの手順はコマンド1つです。nexusctl install --single-node がマシン上にk3sクラスターを構築し、cert-managerをインストールしてから、Nexusをインストールします。ノートPCでの手順はより実践的です。自分でk3dクラスターを構築し、Helmでcert-managerとチャートをインストールしたあと、ほぼ全員がつまずく追加の作業を1つ行います。単なるポートフォワードでは誰もサインインできないため、自身のマシン上でコンソールをHTTPSの背後に配置する必要があります。
必要なマシンの規模
Nexusはチャートのデフォルト設定でのリクエストにおいて、約2.05個のCPU(中央処理装置)コアと6.7 GiBのメモリを要求し、そのボリュームの合計は142 GiBになります。内訳は、PostgreSQLが50、Valkeyが5、Neo4jが20、Qdrantが10、オブジェクトストアが50、2つのOpenBaoストアが1と5、そしてレシートボリュームが1です。リクエスト値はスケジューラが予約する量であり、実際に人が作業を始めると実使用量はさらに高くなります。
| マシン | CPU | メモリ(RAM、ランダムアクセスメモリ) | ディスク |
|---|---|---|---|
| 推奨シングルノード | 8 vCPU | 32 GiB | 250 GB SSD(ソリッドステートドライブ) |
| 評価用の最小構成 | 4 vCPU | 16 GiB | 200 GB |
評価用の最小構成を満たすノートPCであればNexusを実行できますが、ノートPC自体のメモリではなく、Docker自身のメモリ制限が影響します。開始する前に、Dockerに少なくとも16 GiBを割り当ててください。
どちらの手順でもKubernetes 1.33以降が必要です。シングルノードの手順では、すべてのリリースでテストに使用されているディストリビューションであるk3s v1.33.6+k3s1が自動的に導入されます。
パート1:nexusctl を使用した1台の Linux サーバー
Tomásのパイロットサーバーは、8コア、32 GiBのメモリ、500 GBのSSDを備えたマシンで、最新のLinuxが稼働しており、他には何も入っていません。k3sをシステムサービスとしてインストールするため、インストールにはroot権限が必要です。
nexusctlの取得と確認
- お使いのアーキテクチャ用の
nexusctlを、リリースの公開鍵とともにhttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/からダウンロードします。鍵をrelease.pubとして保存します。リリースの取得と検証に関する第2.4章では、鍵のフィンガープリントをAdverantが公開しているものと照合する方法を説明しています。 - 鍵を使用してバイナリとリリースを確認します。
nexusctl version --json
nexusctl verifynexusctl verify はダウンロードしたファイルをAdverantのリリース鍵と照合し、検証できないものはすべて拒否します。失敗した場合は中止し、再度ダウンロードしてください。検証を通過しなかったファイルからインストールを実行しないでください。
カストディアン鍵の作成
インストール環境のキーストアは、リカバリキーを1人以上のカストディアンに対して封印(シール)します。カストディアンとは、ageのIDファイルをオフラインで保持する人物のことであり、少なくとも1人のカストディアンがいなければチャートはインストールを拒否します。カストディアン自身のマシン上で以下を実行します。
age-keygen -o custodian.keyこのファイルは # public key: age1... という行で始まります。その公開部分がvaluesファイルに記述する内容です。IDファイル自体はカストディアンのマシンから外に出ることはありません。Secure Enclaveを搭載したMacでは、age-plugin-se keygen --access-control=any-biometry -o custodian.key によって使用時にTouch IDを必要とする鍵が作成され、その公開部分は age1se1 で始まります。
valuesファイルの作成
# harrow-pilot-values.yaml (Helm values)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
enterprise:
enabled: false
tls:
mode: existing
existingSecret: harrow-public-tls
keys:
installationName: harrow-pilot
custody:
recipients:
- "<custodian-age-recipient>"<custodian-age-recipient> は custodian.key 内の age1... の行です。カストディアンごとにリストのエントリを1つ追加してください。
keys.installationName は恒久的です。キーストアの初回起動時にその名前でインストール環境のIDが生成され、後から名前を変更することはできません。これは ^[a-z][a-z0-9-]{0,62}$ に一致する必要があります(小文字、英字で始まり、最大63文字)。チャートのサンプルファイルから nexus-example やサンプルの受取人(recipient)をコピーしないでください。チャートはこれらの名前を両方とも拒否し、プリフライトチェックでも同じコードが最初に報告されます。
3つのホストはインストール環境のIDとなります。これらがなければすべてのサービスが起動を拒否し、すべてのサインイン、Cookie、パスキーは hosts.console に紐付けられます。5年後も使い続けたい名前を選んでください。
3つの名前をサーバーに向ける
ユーザーは、サーバーのポート80および443にあるk3sの組み込みIngressコントローラー(Traefik)を通じて、コンソール、API(アプリケーション・プログラミング・インターフェース)、およびサインインサービスにアクセスします。console.harrow.example、api.harrow.example、auth.harrow.example の3つのDNS(ドメインネームシステム)レコードを追加し、それぞれがサーバーのアドレスを指すようにします。プリフライトチェックは各名前を確認し、レコードが存在しないものを通知します。
チャートのネットワークポリシーにより、3つの公開サービスにアクセスできるのは1つのネームスペースのみに制限されます。デフォルトの kube-system はk3sがTraefikを実行する場所であるため、シングルノードでは networkPolicy.ingressNamespace をそのままにしておきます。
プリフライトの実行とインストール
- シングルノードフラグを指定してプリフライトを実行します。マシンとvaluesファイルを読み取るだけで、変更は一切行いません。
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- 最後のサマリー行を確認します。警告(warning)がインストールを妨げることはありませんが、失敗(failure)はインストールをブロックし、失敗したすべての行には
fixの行が表示されます。
────────────────────────────────────────────────────────────
9 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
- インストールします。
--editionフラグはvaluesファイル内のeditionと一致している必要があります。
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- 実行の様子を見守ります。プリフライトを再実行し、k3s v1.33.6+k3s1をインストールし、cert-manager v1.21.3をインストールし、Nexusをインストールして、すべてのサービスがヘルスチェックに応答するのを待ちます。Tomásのサーバーでは10分弱かかりました。
done Preflight again 9 passed · 1 warning
done k3s v1.33.6+k3s1 node Ready
done cert-manager v1.21.3 ready
done Database and search ready
done Engines started
done Console https://console.harrow.example
Installed. Nobody can sign in yet.
Open https://console.harrow.example/claim
Code <code> works once, for 30 minutes
Fingerprint of this installation, to compare in the browser:
3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7
そのフィンガープリントを画面に表示したままにしておきます。コードを使ってインストール環境を要求(クレーム)する際、ブラウザでこれを照合します。使用する前にコードの有効期限が切れた場合は、nexusctl claim-code --administrator <email> で新しいコードを作成できます。ここからの手順は、初回実行に関する第2.12章で説明します。
証明書の配置
tls.mode: existing を使用すると、3つのIngressルートは tls.existingSecret で指定されたSecret内の証明書を提供します。この証明書は3つのホストすべてをカバーしている必要があります。プリフライトはそのSecretが存在する場合にそれを読み取り、証明書の有効期限が30日以内に切れる場合は警告を出します。Secretがまだ存在しない場合、該当の行はそれを作成するよう指示しますが、これは失敗ではなく警告として扱われます。
シングルノードでは、インストールによって作成されるまでクラスターが存在しないため、インストール直後にSecretを作成します。まずクラスターのkubeconfigを書き出し(本章の最後のセクションで説明します)、それを使ってSecretを作成します。
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt には証明書とそれに続く中間証明書が含まれ、harrow-public.key にはその秘密鍵が含まれます。証明書がプライベートCA(認証局)から発行されている場合、チェーンを確認できるように nexusctl preflight と nexusctl install は --ca-bundle <file> を受け取ります。TLS(トランスポート層セキュリティ)を処理するその他の方法については、外部ストア、TLS、およびIngressのバリエーションに関する第2.11章に記載されています。
これが失敗する場合
| 表示内容 | 意味 | 対処法 |
|---|---|---|
PREFLIGHT_FAILED (409) |
プリフライトで失敗が見つかったため、インストールは開始されませんでした。何もインストールされていません。 | 失敗した各行について、その fix 行を参考に修正し、再度インストールを実行してください。 |
INSTALLATION_NAME_MISSING |
keys.installationName が空です。 |
インストール環境固有の恒久的な名前を設定してください。 |
INSTALLATION_NAME_EXAMPLE |
この名前はチャートのサンプル値にあるものです。 | 独自の名前を選択してください。 |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients が空です。 |
各カストディアンの公開 age1... 受取人を追加してください。 |
KEYS_CUSTODIAN_EXAMPLE |
受取人がチャートのサンプルカストディアンになっており、そのIDは誰も保持していません。 | 実際のカストディアンの受取人に置き換えてください。 |
nexusctl は、続行可能な場合は0、チェックによりブロックされた場合は1、まったく実行できなかった場合(valuesファイルが読み取れない、フラグが間違っているなど)は2で終了します。スクリプトではこれら3つの値で分岐処理を行うことができます。
パート2:k3d を使用したノート PC での評価
k3dはDockerコンテナ内でk3sを実行するため、クラスター全体がノートPC上に構築され、コマンド1つで消去できます。すべてのNexusリリースをテストするリリースツールは、まさにこの方法でクラスターを構築しており、その設定をコピーすることで、すでに解決済みの問題に再び遭遇するのを避けることができます。
Docker、k3d 5.8.3、kubectl、Helm v4、およびChromeが必要です。Tomásは自分のMacを使用しました。
クラスターの作成
k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
--image rancher/k3s:v1.33.6-k3s1 \
--k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfig各フラグには理由があります。
--agents 0はサーバーノードを1つ作成し、ワーカーは作成しません。Nexusは1つのノードで問題なく動作し、2つ目のノードはメモリを消費するだけです。--image rancher/k3s:v1.33.6-k3s1は、すべてのリリースでテストされているk3sのバージョンを固定します。これがない場合、k3dのデフォルトのバージョンが使用されます。--disable=traefik@server:0はTraefikを除外します。ノートPCには公開するパブリックアドレスがないため、代わりに独自のHTTPSフロント(後述)を介してコンソールにアクセスします。--wait --timeout 300sは、クラスターが応答したときにのみ処理を戻すか、5分後に失敗します。
ノートPC上でリリースレジストリをミラーリングする場合は、イメージのプルをミラーに送るために --registry-config <registries.yaml> を追加し、アップストリームレジストリにフォールバックしないように --k3s-arg "--disable-default-registry-endpoint@server:0" を追加します。リリースツールはこの方法で実行され、すべてのイメージはミラーのみを経由して取得されます。
cert-managerのインストール
チャートはcert-managerの発行者(issuer)として独自のローカルCAである nexus-local-ca を作成し、すべてのサービスはそこから証明書を取得します。クラスター内にcert-managerのリソースがない場合、helm install は数秒以内にチャートを拒否します。まず、cert-managerプロジェクトが公開しているチャートからcert-manager v1.21.3をインストールします。
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10mNexusはcert-managerから他のものを必要とせず、特にtrust-managerは不要です。
Nexusのインストール
- ノートPC用のvaluesファイルを作成します。TLSは独自のフロントで終端するため、
tls.modeはnoneにします。
# harrow-eval-values.yaml (Helm values)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
tls:
mode: none
keys:
installationName: harrow-eval
custody:
recipients:
- "<custodian-age-recipient>"- レジストリからチャートをインストールし、
--waitは省略します(理由は下の警告に記載しています)。
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
-n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m- その後、自身でワークロードの待機処理を行います。
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
doneStatefulSetのループが存在するのは、その一部がリクエストに応じて1つずつPodを更新する仕様であり、kubectl rollout status がそれらを拒否するためです。readyReplicas での待機は、すべての更新戦略で機能します。
両方のコマンドが完了すると、すべてのDeploymentがAvailableになり、すべてのStatefulSetのPodがReadyになります。まだ誰もサインインできませんが、それで正常です。インストール環境はまだ要求(クレーム)されていない状態です。
ポートフォワードでは決してサインインできない理由
次に取るべき明白な行動は、kubectl port-forward svc/nexus-alpha 3000:3000 を実行してブラウザで http://127.0.0.1:3000 にアクセスすることと思われがちです。コンソールのページが読み込まれるため、動作しているように見えます。しかし実際には動作しておらず、どのような設定を行っても動作しません。意図的に設けられた3つの障壁が立ちはだかっています。
| 動作を妨げる要因 | 理由 |
|---|---|
| オリジン | コンソールのサインインは、オリジンが https://<hosts.console>(ここでは https://console.harrow.example)ではないリクエストを拒否します。http://127.0.0.1:3000 から提供されるページはオリジンが異なるため、サインインが開始されません。 |
| Cookie | セッションは Secure とマークされた __Host- Cookieです。ブラウザはそのようなCookieを、HTTPS経由でのみ、ドメイン属性なしで、それを設定したホストに対してのみ厳密に保存します。プレーンなHTTP経由では、ブラウザはそれを破棄します。 |
| パスキー | 最初の管理者はパスキーを使用してサインインしますが、パスキーには有効な証明書を備えたセキュアなコンテキストが必要です。Chromeは、たとえクリックして進んだとしても、証明書の警告が表示された状態ではパスキーの作成を拒否します。 |
したがって、ブラウザは信頼する証明書を使用して https://console.harrow.example と通信する必要があり、その名前はノートPCに到達しなければなりません。
ノート PC で HTTPS 経由でコンソールにアクセスする
以下の方法では、チャート独自のCAを使用して証明書を発行し、ポートフォワードを使用してコンソールに到達し、その1つのCAのみを信頼してコンソールの名前をノートPCにマッピングする個別のChromeプロファイルを使用します。システムのトラストストアと /etc/hosts はそのまま維持されます。
コンソール名に対する証明書の発行
- チャートの発行者によって署名された、コンソールホスト用の証明書をcert-managerに要求します。
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: nexus-console-front
namespace: nexus
spec:
secretName: nexus-console-front-tls
dnsNames: [console.harrow.example]
duration: 24h
usages: [server auth, digital signature, key encipherment]
privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120scert-managerはクラスター内でそれに署名します。CAの秘密鍵を読み取る必要はありません。
- 証明書、その鍵、およびCA証明書をSecretからコピーします。
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key- CAのピン(pin)を算出します。Chromeは、公開鍵のbase64 SHA-256によって信頼された鍵を識別します。
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64証明書の鍵ではなく、CAの鍵をピン留めしてください。証明書の有効期間は1日で、cert-managerが更新するたびに新しい鍵が生成されますが、CAは変わらないためです。
ポートフォワードの前面にHTTPSフロントを配置する
- コンソールのServiceをフォワードします。そのポートは
httpという名前のポートで、このリリースでは3000です。
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000127.0.0.1:3000に転送するHTTPSリスナーを127.0.0.1:28443で実行します。以下の4つの処理を行う限り、すでに信頼している任意のリバースプロキシを使用できます。tls.keyを使用して、tls.crtに続いてca.crtをチェーンとして提供する。Hostヘッダーをconsole.harrow.exampleとして維持する。X-Forwarded-Proto: httpsを設定する。- コンソールがWebSocketアップグレードを使用するため、それらを通過させる。
Serviceへのポートフォワードは、開始時に選択した1つのPodにバインドされます。アップグレードや再起動によってコンソールのPodが置き換わった後も、フォワード自体は維持されますが転送先がなくなるため、ブラウザにはBad Gatewayが表示されます。コンソールのPodが変更された場合は、その都度ポートフォワードを再起動してください。
ピンと名前マッピングを指定してChromeを開く
Macの場合:
open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
"--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
"--ignore-certificate-errors-spki-list=<ca-pin>" \
https://console.harrow.example/install<ca-pin> は openssl の行の出力です。Linuxでは、同じ3つのフラグを指定してChromeを起動します。
3つのフラグは連携して機能します。--host-resolver-rules は、このプロファイル内でのみ、ポート443の console.harrow.example をフロントに送信します。--ignore-certificate-errors-spki-list はその1つのCA鍵によって発行された証明書を信頼し、Chromeは --user-data-dir が指定されている場合にのみこれを受け入れます。個別のプロファイルを使用することで、日常のブラウジングからこの例外設定を隔離できます。これは「証明書エラーをすべて無視する」ような包括的なスイッチではないため、クラスターのCAによって署名されていないものは引き続き失敗します。
そのプロファイルを開いた状態で https://console.harrow.example/install にアクセスするとクレームページが表示され、パスキーを作成できるようになります。ここからの手順は、初回実行に関する第2.12章に続きます。
ノートPCが再起動したとき
キーストアは、キーストア自体と、そのロック解除鍵を保持する小さなアンシーラー(unsealer)の2つの部分で構成されています。ノードの再起動(Dockerの再起動、ノートPCの再起動、k3d cluster stop や start)の後、アンシーラーは封印(シール)された状態で起動します。キーストアはアンシーラーを通じて自身の封印を解除するため、カストディアンが自身のage IDを使用してアンシーラーの封印を解除するまで、鍵を必要とするものは何も動作しません。これは設計上の特性であり、本番クラスターでも同じです。封印解除の手順については、Day 2のNexus運用に関する第2.15章で説明しています。
評価が終了したら:
k3d cluster delete harrow-evalクラスターを削除すると、インストール環境とその中のすべてが削除されます。
nexusctl kubeconfig
nexusctl install --single-node が構築したクラスターは nexusctl に属します。kubectl、helm、またはその他のツールでそれにアクセスするには、そのkubeconfigを要求します。
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulsetこのファイルはクラスターへの完全な管理者アクセス権を付与します。インストール環境を運用する担当者のマシン上でのみ、モード600で保管し、他の場所には置かないでください。パート2以降の、--context を受け取るか KUBECONFIG を読み取るすべてのコマンドは、このファイルを介してシングルノードに対して機能します。アップグレードについても同様です。シングルノードでの nexusctl upgrade plan --bundle <file> および nexusctl upgrade apply --bundle <file> は、nexusctl が所有するk3sクラスターもアップグレードします。
nexusctl install --single-node が1台のLinuxサーバー上に配置するもの。クラスターに引き継がれるもの
1台のマシンで行ったことはすべて、クラスター上にも対応するものがあります。外部ストア、TLS、およびIngressのバリエーションに関する第2.11章が示すように、valuesファイルはレジストリ、TLSモード、またはストレージクラスが異なるだけで同じファイルです。初回実行の手順も同一です。引き継げないのはインストール環境そのものです。インストール名は恒久的に固定されており、インストール環境をノートPCからサーバーに移行することはできません。TomásがノートPCからパイロットサーバーに移行した際、彼は新しい名前 harrow-pilot で最初からやり直し、実験用に harrow-eval を残しておきました。
