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

第 2.3 章

インストールの計画

NexusのKubernetesインストールにおいて、コマンドを入力する前に必要なもの、その規模、そして後から変更できない2つの決定事項(インストール名とキー管理者)について説明します。最後に、Harrow Port Authorityの記入済み計画ワークシートを示します。

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

読了時間 16 分

Harrow Port AuthorityにNexusをインストールした際、コマンドの実行には半日しかかかりませんでした。しかし計画には1週間を要し、その大半はKubernetesとは無関係な2つの問いに費やされました。それは、このインストール環境を何と呼ぶか、そして誰がそのリカバリキーを保持するかという点です。どちらの決定も後から変更することはできません。この章で扱うその他の項目はすべて、後からvaluesファイルとhelm upgradeを使って変更可能です。

私はHarrowのプラットフォームエンジニア、Tomás Reillyです。Harrowでは2つのインストール環境を運用しています。この章では、最初にCommunityエディションを試験導入した社内ネットワーク上のインターネット接続環境について計画を立てます。インターネットへの経路を持たない港湾の業務ネットワークには、後から独自の環境を構築しました。これについては第2.10章「エアギャップ環境へのインストール」で解説します。この章には、私が初日の朝に知っておきたかったことをまとめました。すなわち、Nexusが前提とするクラスタ要件、応答に使用するホスト名、ノードに求められるリソース量、そしてインストール前にIT部門の責任者と合意しておくべき決定事項です。章の最後には、作業開始前に当社のIT部門責任者であるAoife Brennanが承認したワークシートを掲載しています。リリースの取得と検証については第2.4章「リリースの取得と検証」で扱い、第2.5章「nexusctlによるプリフライト」では、ここで挙げるすべての項目に対してクラスタの事前チェックを行います。

クラスタに必須の要素

Nexusは単一のHelmチャート(nexus、バージョン1.0.0-alpha.1)としてインストールされます。このチャートにはプラットフォームサービスとそのデータ層が含まれており、以下の要素が欠けているクラスタへのインストールは拒否されます。

要件 Nexusが求める条件 理由
Kubernetes 1.33以降。k3s v1.33.6+k3s1でテスト済み チャートのkubeVersionが>=1.33.0-0であり、helm installがこれを強制するため
cert-manager v1.21.3(Nexusより前にインストールされていること) チャートが独自のローカル認証局(CA)と、サービス間通信に使用する証明書を作成するため
Helm v4(当社ではv4.3.1を使用) インストール処理が依存しているチャートのフックJobを、Helm 4がデフォルトで待機するため
ストレージクラス デフォルト指定されたもの、またはstorage.classNameで名前を指定したもの すべてのデータストアが永続ボリュームを要求するため
Ingressクラス デフォルト指定されたもの、またはingress.classNameで名前を指定したもの 3つの公開アドレスは標準的なnetworking.k8s.io/v1のIngressであるため
ポート80および443 LoadBalancerまたはNodePort Serviceとして、Ingressコントローラ上で開放されていること ユーザーがIngressコントローラ経由でNexusにアクセスするため
アーキテクチャ linux/amd64またはlinux/arm64ノード すべてのイメージが両方のアーキテクチャ向けにビルドされているため

上の表からは意図的に2つのものを省いています。まず、Nexusにサービスメッシュは不要です。サービス間の相互TLS(mTLS:双方向のTransport Layer Security)は、cert-managerを介してチャートのローカルCAから提供されます。チャートにはデフォルトでfalseとなるistio.enabledキーがありますが、そのまま変更しないでください。また、Nexus独自のアドミッションポリシーエンジンも必要ありません。

作業用ワークステーションには、kubectl、Helm v4、署名検証用のcosign v3、カストディアンキー作成用のage、そしてNexus運用者向けのコマンドラインインターフェース(CLI)であるnexusctlが必要です。Nexusの各ダウンロードファイルの入手先については、第2.4章「リリースの取得と検証」に記載されています。

3つのアドレス

すべてのインストール環境は3つのホスト名で応答します。チャートはこれらを「インストール環境のID(installation identity)」と呼び、これらが設定されていない場合、すべてのサービスは起動を拒否します。

Valuesキー Harrowでの設定名 応答するコンポーネント
hosts.console console.harrow.example コンソール(ユーザーがサインインするWebアプリケーション)
hosts.api api.harrow.example ゲートウェイ(アプリケーションプログラミングインターフェース(API)を提供し、すべての人工知能(AI)リクエストをルーティングする)
hosts.auth auth.harrow.example サインインサービス、nexus-auth

global.domainには、これら3つが属するドメイン(当社ではharrow.example)を指定します。各ホストはそれ自体が完全修飾ドメイン名であり、管理下の任意のドメイン配下に配置できます。当社では1つの証明書ですべてをカバーできるよう、3つとも同じドメイン配下に統一しました。

3つのホスト名それぞれについて、Ingressコントローラのアドレスを指すドメインネームシステム(DNS)レコードを作成してください。これはプリフライトの前に行う必要があります。名前解決できないホストにはユーザーがアクセスできないため、nexusctl preflightはワークステーションから各名前を検索し、レコードが存在しないものが1つでもあるとインストールを失敗させます。

左側に3つのDNS名(console.harrow.example、api.harrow.example、auth.harrow.example)があり、それぞれから「ingress controller, ports 80 and 443」とラベル付けされた1つのボックスへ矢印が伸びています。そのボックスから、さらに大きな「namespace nexus」とラベル付けされたボックス内の3つの要素へ矢印が繋がっています(consoleの矢印は「nexus-alpha :3000」へ、apiの矢印は「nexus-gateway :9092」へ、authの矢印は「nexus-auth :9101」へ)。ネームスペースを囲む破線の境界線には「default deny; only the ingress namespace may reach these three」とラベル付けされています。
3つの公開ホスト名から背後の各サービスへ到達する仕組み。

TLS終端方法の選択

チャートのtls.modeは、3つの公開アドレスに対する証明書を誰が管理するかを決定します。選択肢は3つあり、後からアップグレードによって切り替えることも可能です。

tls.mode 用意するもの チャートの動作
existing(デフォルト) nexusネームスペース内のKubernetes TLS Secret(名前はtls.existingSecretで指定) 3つのIngressすべてがその単一のSecretを使用します
cert-manager 運用中のClusterIssuer(名前はtls.clusterIssuerで指定) cert-managerがnexus-console-tls、nexus-api-tls、nexus-auth-tlsを発行するよう各Ingressにアノテーションを付与します
none 独自のロードバランサなど、クラスタの前段でTLSを終端する仕組み TLSセクションなしでIngressをレンダリングします

existingを使用する場合、1つの証明書で3つのホストすべてに対応するため、3つのサブジェクト代替名(SAN)として、またはドメインのワイルドカードとして、3つすべてが証明書に含まれている必要があります。当社ではHarrowの社内CAが発行した証明書を使用しました。プリフライトはインストール前にSecretを読み取り、証明書の有効期限が30日以内に迫っていると警告を出します。

cert-managerとAutomatic Certificate Management Environment(ACME)の発行者を使用する場合、チャートは独自のリダイレクトを追加しないため、ポート80への/.well-known/acme-challenge/リクエストはそのままソルバーに到達します。チャレンジパスの前に実行されるようなHTTPからHTTPSへのリダイレクトをIngressコントローラ側で追加しないでください。更新できなくなった証明書は、数週間後に前触れなく失効してしまいます。

公開エッジにどの方式を選択したとしても、ネームスペース内のサービス同士は常にチャートのローカルCAが発行したTLSで通信します。この部分は選択式ではなく、tls.modeがexistingやnoneであってもcert-managerが必須要件となっているのはこのためです。

クラスタ外に出るものと出ないもの

チャートはnexusネームスペースに対してデフォルト拒否(default-deny)のネットワークポリシーをレンダリングします。適用後は、以下の通信フローのみが許可されます。

  • ネームスペース内のNexus Pod間のトラフィック
  • クラスタのDNSサービスに対するDNSルックアップ
  • Kubernetes APIサーバーへの通信(ワークロードトークンを検証する一部のサービス用)
  • Ingressコントローラのネームスペースから3つの公開Serviceへの通信
  • networkPolicy.externalEgressCIDRsに列挙した任意のClassless Inter-Domain Routing(CIDR)範囲への通信

最後のリストはデフォルトでは空です。クラスタ外部のメールリレーやモデルサーバーを使用する場合は、そのアドレス範囲をここに追加します。テレメトリはオフになっており、常にオフのままです。スキーマはtelemetry.enabled: falseのみを受け入れ、データストア自体の使用状況レポート機能もオフに設定されています。

チャートはインストール時にクラスタからAPIサーバーのアドレスを読み取ります。使用するアカウントにdefaultネームスペース内のkubernetes Endpointsを読み取る権限がない場合は、networkPolicy.apiServerCIDRsに/32の範囲として直接指定してください。proxy.trustedCIDRsにはIngressコントローラが配置されているPodネットワークを指定します。これにより、nexus-authはどのX-Forwarded-Forヘッダーを信頼すべきかを判断します。デフォルトの10.42.0.0/16はk3sのPodネットワークです。

サイジング

チャートのデフォルトのリソース要求(requests)は、合計で約2.05中央処理装置(CPU)コアと6.7 GiBのメモリになります。これはスケジューラが予約する量であり、上限(limits)はさらに高く設定されています。ユーザーやファイルが増えるにつれて、データストアは上限までリソースを使用するようになります。

コンポーネント CPU要求量 メモリ要求量
9つのプラットフォームサービス(console、バックエンド・フォー・フロントエンド(BFF)、auth、orchestrator、workflows、gateway、graphrag、probitas、skills engine) 1.1コア 2.6 GiB
キーサービス、nexus-keys 0.05コア 64 MiB
PostgreSQL 0.25コア 1 GiB
Neo4j 0.25コア 2 GiB
Valkey、Qdrant、およびオブジェクトストアの合計 0.25コア 640 MiB
キーストアの2つのOpenBaoサーバー 0.15コア 384 MiB

デフォルトのボリュームサイズは合計で142 GiBになります。

ストア Valuesキー デフォルトサイズ
PostgreSQL 16(PostGIS 3およびpgvector 0.8を含む) dataTier.postgres.size 50Gi
オブジェクトストア(SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
キーストアとそのアンシーラー(unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Giおよび1Gi
キーサービスのレシート keys.receiptsStorage 1Gi

シングルノード構成の場合、8 vCPU、32 GiBのランダムアクセスメモリ(RAM)、および250 GBのソリッドステートドライブ(SSD)を見込んでください。評価目的であれば、4 vCPU、16 GiBメモリ、200 GBディスクで足ります。インストーラディスクイメージは16 GiB未満のメモリのマシンを拒否するため(第2.9章「インストーラディスクイメージ」を参照)、どの環境でもこれを最低ラインと考えるべきです。

グラフィックスノードは任意です。グラフィックス処理装置(GPU)を備えたノードがない場合、アシスタントは組織自身のキーを使用してホスト型モデル経由で応答します。プリフライトはこれを警告として報告し、エラーにはしません。両方の方式については、第2.14章「AIプロバイダーとモデル」で解説しています。

各データストアはクラスタの外部で実行することも可能です。その場合はdataTier.<store>.modeをexternalに設定し、ホスト名とSecretを指定します。外部のPostgreSQLを使用する場合、インストール時のブートストラップ用にスーパーユーザーアカウントと、Nexusが検証可能な証明書が必要です。これについては第2.11章「バリエーション:外部ストア、TLS、Ingress」で扱います。クラスタ内に配置する場合は、背後に実ディスクを持つストレージクラス上に配置してください。ノードのローカルディスクが故障した際、最も痛手となるのはデータベースの喪失です。

インストール名は恒久的

keys.installationNameは、運用者がこのインストール環境を識別するための名前です。^[a-z][a-z0-9-]{0,62}$の形式(英小文字で始まり、その後に最大62文字の英小文字、数字、またはハイフンが続く)に一致する必要があります。

キーストアは初回起動時にこの名前の下でインストール環境のIDを発行し、そのIDは恒久的に固定されます。AdverantからのライセンスはそのIDに対して発行されるため、あるインストール環境向けに作られたライセンスを別の環境で使用しようとするとLICENCE_OTHER_INSTALLATIONで拒否されます。名前を変更するということは、新しいインストール環境、新しいID、そして新しいライセンスが必要になることを意味します。

チャートにはこの名前のデフォルト値がありません。名前が未指定の場合(INSTALLATION_NAME_MISSING)や、サンプルvaluesファイル内のサンプル名(INSTALLATION_NAME_EXAMPLE)のままの場合はインストールを拒否します。プリフライトはインストールに進む前にその両方を検出して報告します。

Harrowでは、正直に言いづらいほど長い時間をこの命名に費やしました。最終的にharrow-port-authorityに落ち着きました。これは組織名を表しており、どのクラスタで動いているかには触れず、将来ハードウェアがリプレースされても通用する名前です。prod-k3s-2のように現在のマシン構成を表すような名前は避けてください。

キーの管理

Nexusはすべての組織のキーを、クラスタ内の独自のキーストアに保管します。日常的にこれを直接操作することはありませんが、再起動後に誰がそれを復旧できるかについてはインストール前に決定しておく必要があります。これは、判断を誤った場合に最も大きな代償を伴う決定事項です。

キーストアは2つのOpenBaoサーバーで構成されます。メインのopenbaoがキーを保持し、2つ目のより小さなサーバーであるopenbao-unsealerを介して自身のアンシール(封印解除)を行います。アンシーラーはシャミアの秘密分散法(Shamir's scheme)でシールされており、5つのシェアのうち任意の3つがあれば開くことができます。インストール時、カストディJobがクラスタ内の両方のサーバーを初期化します。そのJobのメモリ内で、アンシーラーのシェアとキーストアのリカバリキーが指定されたすべてのカストディアン(鍵管理者)向けに暗号化され、暗号文のみが(Secret openbao-unseal-shares-encryptedおよびopenbao-recovery-keys-encryptedに)保存され、完了前に両方のルートトークンが破棄されます。平文のシェアがディスクやログに出力されることは一切ありません。

アンシーラーのノードが再起動すると、アンシーラーはシールされた状態で起動します。キーストアはアンシーラーを待機するため、カストディアンがアンシールを行うまで、キーを必要とする機能は一切動作しません。アンシールには、カストディアン自身の秘密鍵を使った1回の復号操作が必要です。手順については第2.15章「Day 2:Nexusの運用」に記載されています。

カストディアンキーの作成

カストディアンは、ageキーの公開鍵側(レシピエントと呼ばれます)によって指定されます。各カストディアンは自身のマシン上でキーを作成し、レシピエントのみを提出します。

age-keygen -o custodian.key

ファイル内の# public key:の行がレシピエントであり、age1で始まります。Macを使用しているカストディアンは、代わりにMacのSecure Enclave内にキーを保持することができ、その場合は秘密鍵側がチップから外に出ることはなく、使用するたびに指紋認証が求められます。

age-plugin-se keygen --access-control=any-biometry -o custodian.key

そのレシピエントはage1se1で始まります。カストディJobは、age1(X25519)、age1tag1およびage1tagpq1(タグ)、age1pq1(ハイブリッド耐量子)、そしてage1se1(Secure Enclave)の5つの形式のレシピエントに対して暗号化を行います。age1yubikey1など、その他のプラグイン形式は拒否されるため、受け入れ可能な形式のいずれかでキーを指定してください。

チャートはレンダリング時に各レシピエントを検証します。入力ミスがあるとbech32チェックサムでエラーとなり拒否されるため、誰も保持していないキーに対してシールされてしまうことはありません。誤って秘密鍵をリストに貼り付けてしまった場合、チャートはそれをエコーバックすることなく拒否します。チャート自身のvaluesファイルにあるサンプルレシピエントも、誰もその秘密鍵側を保持していないため拒否されます(KEYS_CUSTODIAN_EXAMPLE)。

カストディアンの人数

すべてのシェアはすべてのカストディアンに対して暗号化されるため、どのカストディアンであっても1人でアンシールを行うことができます。カストディアンの数を増やすほど復旧手段が増え、単独で対応できる人員も増えます。Harrowでは、Aoife、私、そして港の金庫に保管されている予備ノートPC上のSecure Enclaveキーの3つを選択しました。最低でも2人は必要だと考えます。1人だけでは単一障害点となり、遅かれ早かれその担当者が休暇中にノードの再起動が発生することになります。

エディションの選択

editionにはcommunityまたはenterpriseを指定し、enterprise.enabledもそれと一致している必要があります。チャートは不一致を拒否し、またこの2つ以外のエディションも拒否します。

エディションによって、インストールされるイメージも決まります。各チャートパッケージには、1つのエディションに対応するすべてのイメージをダイジェストでリスト化したイメージロック(images lock)が含まれています。CommunityのインストールではCommunityイメージのみが使用されます。Enterpriseのインストールでは、CommunityイメージにEnterpriseビルドを加えたEnterpriseロックが使用され、Adverantアカウントのプルトークンを使ってプルされます。ロックの仕組みについては第2.4章「リリースの取得と検証」で、各エディションに含まれる内容については第2.2章「エディションの内部構造」で解説しています。

最初から最終決定を下す必要はありません。Community環境は、ユーザー、ファイル、履歴を保持したままインプレースでEnterpriseへ移行できます。その方法は第2.7章「Enterpriseのインストールとライセンスの適用」で示しています。Harrowでもパイロット運用ではCommunityを実行し、6週間後に移行しました。

ライセンスはこの計画段階には一切関与しません。チャートの値やマウントされるファイルではなく、インストール完了後にコンソール、nexusctl、またはAPIを介してインポートするためです。

提供形態の選択

形態 適しているケース 該当章
registry.adverant.aiからのHelmチャート レジストリへの通信経路がある独自のKubernetesクラスタ 2.6および2.7
nexusctl install 同じクラスタで、プリフライトと署名検証を自動実行したい場合 2.6
nexusctl install --single-node nexusctlがクラスタのセットアップも行う単一マシン構成 2.8
インストーラーディスクイメージ 手作業での準備を省きたいベアメタルサーバーまたは仮想マシン(VM) 2.9
オフラインバンドル 外部への通信経路が一切なく、イメージとチャートをディスクで持ち込む場合 2.10

どの形態であってもチャート自体は同じです。異なるのは、誰がクラスタを構築するか、そしてどこからイメージを取得するかという点だけです。

リリースの取得
リリースの取得
これはAdverantアカウント内のリリースページです。アルファ版リリースが保証する内容の明確な記述、各ファイルの横にあるサイズと署名、そしてダウンロードを検証するためのオフラインコマンドに注目してください。

計画ワークシート

以下はAoifeが承認したHarrowのワークシートです。左の2列をコピーし、右の列にご自身のインストール環境の設定を記入してください。

決定事項 Valuesキーまたはコマンド Harrow Port Authority
Kubernetesとバージョン (プリフライトが読み取る) k3s v1.33.6+k3s1、3ノード
インストール用のKubeコンテキスト --context harrow-prod
ネームスペース --namespace nexus
エディション edition, enterprise.enabled パイロット時はcommunity、その後enterprise
イメージレジストリ global.imageRegistry registry.adverant.ai
ドメイン global.domain harrow.example
コンソールのアドレス hosts.console console.harrow.example
APIのアドレス hosts.api api.harrow.example
サインインのアドレス hosts.auth auth.harrow.example
エッジでのTLS tls.mode, tls.existingSecret existing、Harrowの社内CAからのSecret harrow-public-tls
Ingressクラス ingress.className traefik
Ingressネームスペース networkPolicy.ingressNamespace kube-system
ストレージクラス storage.className local-path
データストア dataTier.<store>.mode すべてin-cluster、デフォルトサイズ
アウトバウンド範囲 networkPolicy.externalEgressCIDRs メールリレーの範囲のみ
インストール環境名(恒久) keys.installationName harrow-port-authority
カストディアン(実質的に恒久) keys.custody.recipients 3つ:Aoife Brennan、Tomás Reilly、金庫内のノートPC(age1se1)
グラフィックスノード (プリフライトが読み取る) 接続環境のパイロットではなし。Harrow独自のキーによるホスト型モデルを使用
最初の管理者 nexusctl claim-code --administrator aoife.brennan@harrow.example

このシートの中でやり直しがきかない項目が2行あります。インストール環境名と、すべて失うとキーストアも失われるという意味でのカストディアンです。この2つについては、承認権限を持つ責任者のサインをもらってください。それ以外の項目はすべてvaluesの変更で対応できます。

ワークシートが完成したら、第2.4章「リリースの取得と検証」へ進み、リリースを取得してください。