バージョン 1.0.0-alpha.1最新
第 2.6 章
KubernetesへのCommunityのインストール
cert-managerからすべてのワークロードの準備完了まで、Helmを使用したCommunityエディションの手順に沿ったインストールについて説明します。valuesファイルのキーごとの解説、--waitを使用しない理由、チャートのフックが実行される順序、そして代替手段としてのnexusctl installの経路を取り上げます。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

インストール自体は1つのhelm installコマンドです。その前後にある作業はすべて、この1つのコマンドが最初から正しく動作するためにあります。事前のcert-managerの準備、1行ずつ確認したvaluesファイル、そして何を待つべきかを把握した事後の待機処理です。Harrow Port Authorityでは、6週間のパイロット運用として、計画ワークシートで設計した3ノードのk3sクラスターにまずCommunityをインストールしました。リリースは約20分で稼働し始め、私たちが申請(クレーム)を行うまでは誰もサインインできない状態になっていました。これはまさに意図通りの挙動です。
この章では、すでに次の3つの作業を終えていることを前提としています。計画ワークシートの作成(第2.3章「インストールの計画」)、リリースの取得と検証(第2.4章「リリースの取得と検証」)、そしてプリフライトの実行(第2.5章「nexusctlによるプリフライト」)です。未完了のものがある場合は、前の章に戻ってください。インストーラーはほとんどの設定ミスを具体的に指摘して拒否しますが、すでに鍵を紛失してしまったカストディアン(鍵管理者)を指定してしまうなど、一部のミスは検出できません。
ステップ1:ツールとコンテキストを確認する
Helmがバージョン4であることを確認します。
helm versionこのインストールは、Helm 4がデフォルトでチャートのフックJobの完了を待機する仕様に依存しています。私たちはv4.3.1を使用しました。
ワークシートに記載したクラスターを
kubectlの接続先に指定し、確認します。kubectl config use-context harrow-prod kubectl get nodesすべてのノードが
Readyと表示されるはずです。これはプリフライトですでに確認済みですが、プリフライトからインストールの間にノードが脱落する可能性もあるため、ここで確認しておく方が手っ取り早いでしょう。
ステップ2:最初にcert-managerをインストールする
このチャートはcert-managerを使用して独自のローカル認証局(CA)を作成し、各サービスはそれが発行する証明書を使って相互に通信します(自己署名Issuer、有効期間10年のローカルCA証明書、およびサービス用の短命な証明書)。そのため、Nexusよりも前にcert-managerが稼働している必要があります。リリースにはv1.21.3が必要ですが、trust-managerは不要です。
cert-managerを専用のチャートからカスタムリソースごとインストールします。
helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \ --set crds.enabled=true --wait --timeout 10m<cert-manager-chart>は、cert-managerプロジェクト自身のリリースから取得したcert-manager v1.21.3チャートです。ここでは完了を待機して問題ありません。これはcert-manager自体のインストールであり、他に依存するフックはないためです。すべての証明書リクエストが経由するwebhookの準備完了を待機します。
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "cert-manager-webhook" successfully rolled out
ステップ3:名前空間とTLS Secretを作成する
tls.mode: existingを指定する場合、チャートはインストール前に証明書がKubernetesのSecretとして対象ネームスペースに存在することを期待します。3つのアドレスすべてのトランスポート層セキュリティ(TLS)がこの1つのSecretから提供されるため、その証明書には3つのホスト名すべてが含まれている必要があります。
kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
--cert=harrow-public.crt --key=harrow-public.keyharrow-public.crtは証明書(チェーンを含む)、harrow-public.keyはその秘密鍵です。第2.3章「インストールの計画」でtls.mode: cert-managerまたはnoneを選択した場合は、Secretの作成をスキップしてください。ネームスペースは今作成しておくことも、ステップ6で--create-namespaceを指定してHelmに作成させることもできます。
ステップ4:valuesファイルを作成する
これは、Harrowがパイロット運用に使用したvaluesファイルです。ここに記載されているすべてのキーはチャートのスキーマが受け入れるものであり、スキーマはそれ以外のキーを拒否します。そのため、キーのスペルミスがあると無視されるのではなく、インストールが失敗します。
# harrow-values.yaml (Helm values, Community)
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
ingress:
className: traefik
storage:
className: local-path
networkPolicy:
ingressNamespace: kube-system
externalEgressCIDRs: ["10.20.9.25/32"]
keys:
installationName: harrow-port-authority
custody:
recipients:
- "<recipient-aoife>"
- "<recipient-tomas>"
- "<recipient-safe-laptop>"各<recipient-...>は、カストディアン1人分の公開age受取人(カストディアンから送られたage1...またはage1se1...の行)です。以下に、私たちが設定したすべてのキーとその理由を示します。
global.imageRegistryはノードがプルするレジストリです。チャートにはデフォルト値がなく、すべてのイメージを<this>/nexus/<service>@<digest>として組み立てます。インターネットに接続された環境でのインストールではregistry.adverant.aiになります。イメージを独自のレジストリにコピーした場合は、そのホスト名になります。
global.domainは、3つのアドレスが属するドメインです。
hosts.console、hosts.api、およびhosts.authはインストールのアイデンティティであり、人やプログラムが使用する3つの名前です。それぞれがドメインネームシステム(DNS)ですでに名前解決できる必要があり、これはプリフライトで確認済みです。
editionとenterprise.enabledは一致している必要があります。つまり、communityにはfalse、またはenterpriseにはtrueの組み合わせです。チャートはそれ以外の組み合わせを拒否し、イメージロックの対象外のエディションも拒否します。
tls.modeとtls.existingSecretは、パブリックエッジが証明書を取得する方法を選択します。cert-managerの場合は代わりにtls.clusterIssuerを設定し、noneの場合はどちらも設定しません。
ingress.classNameはIngressクラスを指定します。クラスターのデフォルトクラスを使用する場合は未設定のままにします。
storage.classNameはすべてのデータボリュームのストレージクラスを指定します。デフォルトを使用する場合は未設定のままにします。
networkPolicy.ingressNamespaceはIngressコントローラーが稼働しているネームスペースです。デフォルトのkube-systemはk3sのTraefikに適していますが、ファイル上で明示されるようにあえて設定しています。
networkPolicy.externalEgressCIDRsには、DNSやKubernetesのアプリケーション・プログラミング・インターフェース(API)サーバー以外に、サービスがネームスペース外で通信を許可されるアドレス範囲をクラスレスドメイン間ルーティング(CIDR)表記で列挙します。私たちの設定ではメールリレーの単一アドレスを指定しています。リストを空にすると、ネームスペース外のどこにも到達できなくなります。
keys.installationNameは、キーストアがインストールのアイデンティティを発行する際に使用する永続的な名前です。
keys.custody.recipientsには、カストディアンの公開age受取人を列挙します。カストディJobは、すべてのアンシールシェアとリカバリキーをそれぞれの受取人向けに暗号化します。
必要になる可能性のあるキーと、変更すべきでないキー
| キー | 設定するタイミング |
|---|---|
networkPolicy.apiServerCIDRs |
チャートがkubernetes EndpointsからAPIサーバーのアドレスを読み取れない場合。/32の範囲として指定します |
proxy.trustedCIDRs |
IngressコントローラーのPodがk3sの10.42.0.0/16上にない場合 |
ai.localProvider.baseUrl |
組織が独自のOpenAI互換の人工知能(AI)モデルサーバーを運用している場合(第2.14章「AIプロバイダーとモデル」) |
ai.installationHosts |
そのモデルサーバーがインストール環境内のプライベート名で稼働している場合 |
dataTier.<store>.size |
ストアがデフォルトのボリュームサイズ以上の容量を必要とする場合 |
dataTier.<store>.mode |
自身で運用するストアに対するexternal(第2.11章「バリエーション:外部ストア、TLS、およびIngress」) |
components.<service>.replicas, components.<service>.resources |
サービスのサイズをスケールアップする場合 |
auth.rateLimitPerMinute |
高度な自動化により、1人あたり毎分5,000リクエストを超える処理が必要な場合 |
schemaWait.timeoutSeconds |
ディスクが低速なために初回のマイグレーションに30分以上かかる場合 |
istio.enabledはfalseのままにしてください。Nexusにサービスメッシュは不要です。telemetry.enabledはfalseのままにしてください。スキーマは他の値を受け付けません。orchestrator.platformServiceUserIdとprobitas.flagsはチャートが設定したままにしておきます。
認証情報をチャートの値として設定することは一切ありません。モデルプロバイダーのAPIキー、メールのパスワード、プルトークン用のキーは存在しません。各サービスはインストール時に独自の内部シークレットを生成し、アップグレード時もそれを維持します。また、各組織のモデルキーは、初回実行後にコンソールからそれぞれのキープールに登録します。
ステップ5:最終的なファイルに対してプリフライトを実行する
nexusctl preflight --context harrow-prod --values harrow-values.yaml実行は0 failedで終了する必要があります。各行の説明については、第2.5章「nexusctlによるプリフライト」を参照してください。前回の実行以降にサイズ1つでも何か変更した場合は、再度実行してください。
ステップ6:--waitなしでインストールする
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
--namespace nexus -f harrow-values.yaml --timeout 45mステップ3でネームスペースを作成しなかった場合は、--create-namespaceを追加します。ダウンロードして検証したチャートファイルからインストールする場合は、oci://の参照の代わりにそのパスを指定します。
--waitは追加しないでください。チャートのデータベースブートストラップは、リリース自体のリソースが作成された後にpost-installフックとして実行され、そのフックが各サービスにデータベースロールとパスワードを付与します。--waitを指定すると、すべてのDeploymentがAvailableになるまでインストールが待機状態になりますが、待機対象のフックが実行される前にDeploymentがAvailableになることはありません。サービスはデータベースへのログインを拒否され続け、Helmはタイムアウトするまでそれらを待ち続けてしまいます。--waitを指定しなくても、Helm 4はすべてのフックJobを順番に待機するため、それこそが望ましい待機動作です。
最後のフックが完了すると、Helmはサマリーを出力します。
NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1
STATUS: deployedは、すべてのフックが成功したことを意味します。ただし、すべてのサービスがリクエストを処理できる状態になったという意味ではありません。それについてはステップ7で待機します。
何がどの順序で実行されるか
Helmは重み(weight)の小さい順にフックを実行し、各フックの完了を待ってから次に進みます。すべてのマイグレーションJobにはbackoffLimit: 0が設定されており、マイグレーションが失敗するとインストール自体が失敗し、裏で勝手に再試行されることはありません。成功したJobは削除されますが、失敗したJobは確認できるようにログとともに残されます。
| ウェイト | フック | 行うこと |
|---|---|---|
| -30 | 前提条件 | フック用アカウントnexus-migrations、生成されたデータベース認証情報を持つフック専用Secret nexus-migrations-env、およびカストディJobのアカウント、ロール、設定、証明書 |
| -20 | nexus-db-bootstrap |
データベースとロールを作成します(いずれもスーパーユーザーではなく、行レベルセキュリティ(RLS)をバイパスできません)。PostGISやpgvectorなどの拡張機能を追加し、リリース台帳を作成します |
| -15 | nexus-openbao-custody-init |
キーストアとそのアンシーラーを初期化し、シェアとリカバリキーをカストディアン向けに暗号化し、両方のルートトークンを失効させ、keys.installationNameの下にインストールのアイデンティティを発行します |
| -12 | nexus-graphrag-migrations |
サインインサービスのスキーマがグラフサービスの所有するオブジェクトを参照するため、まずグラフサービスのスキーマを構築します |
| -10 | nexus-auth-migrations |
サインインサービスのスキーマと、その2つのランタイムロールを構築します |
| -5 | nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations |
各サービス独自のスキーマを構築します。probitasは最初にauthのテーブルを確認するため、authの後に実行されます |
| 0 | nexus-alpha-bff-migrations |
Backend for Frontend(BFF)のデータベースとそのロールをプロビジョニングし、マイグレーションを適用します |
各マイグレーションフックは、最後にリリース台帳であるnexus_release.schema_appliedへ1行(自身のチェーン名と、それを実行したイメージのダイジェスト)を書き込んで終了します。この行は、マイグレーションランナーがエラーなく完了した後にのみ書き込まれます。ブートストラップJobはdb-bootstrap: doneを出力し、SQLマイグレーションフックは最終行としてschema-ledger: recorded <chain> for this release's imageを出力します。コンソール独自のマイグレーションフックであるnexus-alpha-bff-migrationsも同様に行を記録し、その後bff-migrate: doneを出力します。
サービスがスキーマを待機する仕組み
Deploymentは、フックがまだ実行されている間に、Helmによって作成されるとすぐに起動します。ロールやパスワード、スキーマが存在しないデータベースに対してサービスが起動すると、フックが完了するまでクラッシュと再起動を繰り返してしまいます。そのため、データベースを使用するすべてのDeploymentには、代わりにPodの起動を保留させるinitコンテナwait-for-schemaが含まれています。
このコンテナは、その1つのテーブルしか読み取れないログインであるnexus_ledger_readerとしてリリース台帳を読み取り、このリリースのイメージダイジェストに対応するチェーンが台帳に表示されるまで待機します。schemaWait.intervalSeconds(デフォルトは3)ごとにポーリングを行い、状態が変化したときと20回目のポーリングごとに状態を出力し、schemaWait.timeoutSeconds(デフォルトは1,800)が経過するとサービス名を含む失敗メッセージを出して終了します。
| Deployment | 待機対象 |
|---|---|
nexus-auth |
nexus-auth-migrations |
nexus-orchestrator, nexus-workflows |
nexus-orchestrator-migrations |
nexus-gateway |
nexus-gateway-migrations |
nexus-graphrag |
nexus-graphrag-migrations |
nexus-probitas |
nexus-probitas-migrations |
nexus-skills-engine |
nexus-db-bootstrap |
nexus-alpha-bff |
nexus-alpha-bff-migrations |
あるサービスの待機状態をリアルタイムで確認するには、そのinitコンテナのログを読み取ります。
kubectl -n nexus logs deploy/nexus-auth -c wait-for-schemawait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations; gives up after 1800s
wait-for-schema: ready after 212s: the release ledger shows nexus-auth-migrations
待機処理はファイル数ではなくイメージダイジェストをキーとしているため、後のアップグレード時のPodは新しいリリースの行を待機し、valuesのみの変更後に再起動したPodは自身の行を即座に見つけます。
ステップ7:すべてのワークロードを待機する
期限を設けてDeploymentの完了を待機します。
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900sdeployment.apps/nexus-alpha condition met
deployment.apps/nexus-alpha-bff condition met
deployment.apps/nexus-auth condition met
deployment.apps/nexus-gateway condition met
deployment.apps/nexus-graphrag condition met
deployment.apps/nexus-keys condition met
deployment.apps/nexus-orchestrator condition met
deployment.apps/nexus-probitas condition met
deployment.apps/nexus-skills-engine condition met
deployment.apps/nexus-workflows condition met
次にStatefulSetを待機します。2つのキーストアサーバーはPodを削除したときにのみ更新され、kubectl rollout statusはその更新戦略を拒否するため、代わりにReadyの数で待機します。
for s in $(kubectl -n nexus get statefulset -o name); do
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
doneそれぞれがcondition metを出力します。私たちのクラスターでは、Helmの処理が戻ってから両方の待機が完了するまで5分もかかりませんでした。
準備完了の状態
kubectl -n nexus get deploy,statefulsetNAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/nexus-alpha 1/1 1 1 14m
deployment.apps/nexus-alpha-bff 1/1 1 1 14m
deployment.apps/nexus-auth 1/1 1 1 14m
deployment.apps/nexus-gateway 1/1 1 1 14m
deployment.apps/nexus-graphrag 1/1 1 1 14m
deployment.apps/nexus-keys 1/1 1 1 14m
deployment.apps/nexus-orchestrator 1/1 1 1 14m
deployment.apps/nexus-probitas 1/1 1 1 14m
deployment.apps/nexus-skills-engine 1/1 1 1 14m
deployment.apps/nexus-workflows 1/1 1 1 14m
NAME READY AGE
statefulset.apps/nexus-neo4j 1/1 14m
statefulset.apps/nexus-postgres 1/1 14m
statefulset.apps/nexus-qdrant 1/1 14m
statefulset.apps/nexus-seaweedfs 1/1 14m
statefulset.apps/nexus-valkey 1/1 14m
statefulset.apps/openbao 1/1 14m
statefulset.apps/openbao-unsealer 1/1 14m
10個のDeploymentと7個のStatefulSet、すべてがReady状態です。それらと並んで、キーサービスの夜間メンテナンス用である3つのCronJob(nexus-keys-rotate-epoch、nexus-keys-run-schedule、nexus-keys-export-receipts)があります。成功したフックJobは削除されるため、kubectl -n nexus get jobsにはフックJobは1つも表示されないはずです。
ターミナルを閉じる前に、2つやっておくべきことがあります。1つは、チームで設定を管理している場所にvaluesファイルをコミットしておくことです。今後のすべてのアップグレードはこのファイルから始まります。もう1つは、Secret nexus-generatedには触れないでおくことです。チャートはインストール時に内部パスワードと鍵を一度だけ生成してそこに保存し、毎回のアップグレード時にそれを読み戻します。そのため、これを削除するとサービスが自身のデータにアクセスできなくなります。
Readyとは、プラットフォームが稼働しており、まだ申請(クレーム)されていない状態を意味します。https://console.harrow.exampleを開くと、サインインページではなくインストーラーが表示されます。誰かがインストールの申請を行うまでは、誰もサインインできません。これが初回実行であり、第2.12章「初回実行」で説明します。
これが失敗する場合
ほとんどの失敗は、その原因を自ら示します。何かを変更する前にメッセージを読んでください。
| 表示内容 | 原因 | 対処法 |
|---|---|---|
INSTALLATION_NAME_MISSINGまたはINSTALLATION_NAME_EXAMPLE |
keys.installationNameが空であるか、サンプルのままになっている |
独自の永続的な名前を設定する |
KEYS_CUSTODIAN_MISSINGまたはKEYS_CUSTODIAN_EXAMPLE |
カストディアンが設定されていないか、サンプルのままになっている | カストディアン自身の受取人を設定する |
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ |
大文字、ドット、または先頭の数字が含まれている | 英字で始まり、小文字、数字、ハイフンのみを使用する |
keys.custody.recipients: ...と理由 |
受取人の入力ミス、秘密鍵の指定、またはカストディJobが暗号化できない形式である | カストディアンに受取人を再確認する |
hosts.console is required (the installation identity) |
ホストが未設定である | 3つのホストすべてを設定する |
tls.existingSecret is required when tls.mode is existing |
Secret名が指定されていない | 設定するか、tls.modeを変更する |
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read |
アカウントがAPIサーバーのアドレスを読み取れない | /32の範囲として指定する |
global.imageRegistry is required |
レジストリが未設定である | 設定する |
Helmがタイムアウトまで待機し続け、nexus-authがpassword authentication failedをログに出力する |
--waitが指定された |
アンインストールし、--waitなしで再度インストールする |
フック名を含むError: ... job failed |
マイグレーションが失敗した | kubectl -n nexus logs job/<hook-name>を実行し、最後の数行を読む |
PodがInitのまま止まっている |
そのwait-for-schemaがまだ待機中である |
ログを読む(不足しているチェーンが記載されている) |
wait-for-schema: FAILED |
チェーンのフックが行を書き込まなかった | まずそのフックの失敗原因を特定する |
ImagePullBackOff |
ノードがglobal.imageRegistryからプルできない |
ノードがレジストリに到達できること、およびEnterpriseの場合はプルトークンを持っていることを確認する |
PostgreSQLを待機するすべてのフックは一定の時間を上限として待機し、waiting for postgres (12/60)と出力するため、データベースがスタックしている場合は1分以内にフックのログに現れます。
nexusctl によるインストール経路
nexusctl installは、前後のチェックを自動的に実行しながら同じインストールを行います。使用するvaluesファイルも同じです。
nexusctl install --context harrow-prod --values harrow-values.yamlプリフライトを再度実行し、失敗し始めたチェックがあれば停止します。リリースキーに対してチャートバンドルの署名を検証します。その後、インストールを実行し、フックとワークロードの完了を待機し、各ステップとかかった時間を出力します。--edition communityは、ファイル内だけでなくコマンドラインでもエディションを明示します。--ca-bundle <file>は、プリフライトと同様に独自のCA証明書を追加します。実際には実行せずに、実行される予定のhelmとkubectlの操作を確認するには、--explainを追加します。
nexusctl install --context harrow-prod --values harrow-values.yaml --explain完了すると、申請(クレーム)用アドレス、ワンタイム申請コード、およびインストールのフィンガープリントが出力されます。
Installed in <time>. 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:
<eight groups of four>
コードは3つのグループで構成され、5回まで試行できます。フィンガープリントは4文字ずつ8つのグループで構成され、申請前に比較できるようブラウザにも同じ8つのグループが表示されます。
初回起動への引き継ぎ
Helmを使用してインストールした場合は、最初の管理者になる人物の名前を指定して、自身で申請コードを作成します。
nexusctl claim-code --administrator aoife.brennan@harrow.exampleクラスターへのアクセス権限を使用してnexus-keys Pod内でキーサービス独自のclaim-codeコマンドを実行し、上記と同様にアドレス、コード、フィンガープリントを出力します。コードの有効期限は30分です。新しいコードを取得するには再度実行してください。
ここからはブラウザでの作業に移ります。インストールの申請を行い、パスキーを使って最初の管理者を作成し、誰かがサインインする前に6つの項目を設定します。これについては第2.12章「初回実行」で説明します。直ちにEnterpriseのライセンスを適用する場合は、ライセンスがその6つの項目のうちの1つであるため、先に第2.7章「Enterpriseのインストールとライセンスの適用」をお読みください。

