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

第 2.6 章

KubernetesへのCommunityのインストール

cert-managerからすべてのワークロードの準備完了まで、Helmを使用したCommunityエディションの手順に沿ったインストールについて説明します。valuesファイルのキーごとの解説、--waitを使用しない理由、チャートのフックが実行される順序、そして代替手段としてのnexusctl installの経路を取り上げます。

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

読了時間 18 分

インストール自体は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:ツールとコンテキストを確認する

  1. Helmがバージョン4であることを確認します。

    helm version

    このインストールは、Helm 4がデフォルトでチャートのフックJobの完了を待機する仕様に依存しています。私たちはv4.3.1を使用しました。

  2. ワークシートに記載したクラスターを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は不要です。

  1. 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自体のインストールであり、他に依存するフックはないためです。

  2. すべての証明書リクエストが経由するwebhookの準備完了を待機します。

    kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300s
    deployment "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.key

harrow-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を出力します。

「helm install」とラベル付けされた、左から右へ進む水平のタイムライン。上段のトラックには7つのフックのボックスが順番に並んでいる:「-30 prerequisites」、「-20 db-bootstrap」、「-15 custody init」、「-12 graphrag migrations」、「-10 auth migrations」、「-5 orchestrator, gateway, probitas migrations」、「0 BFF migrations」。各マイグレーションボックスからは、中段のトラックにある「release ledger: nexus_release.schema_applied」とラベル付けされた円筒へ向かって小さな下向き矢印が伸びている。下段のトラックには、左端から始まる「Deployments start, wait-for-schema holds each pod」とラベル付けされた長いバーがあり、そこから台帳へ向かって短い上向き矢印が伸び、各Deploymentのバーは対応する台帳の行が現れた時点で塗りつぶしに変わる。
新規インストールの実行順序(フックとワークロードの並行推移)。

サービスがスキーマを待機する仕組み

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-schema
wait-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=900s
deployment.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,statefulset
NAME                                  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章「初回実行」で説明します。

このインストレーション(Community)
このインストール環境(Community)
申請が完了した後のCommunityインストールの専用ページ。稼働中のバージョン、エンジンの健全性、ディスク使用量、バックアップ、セキュリティ修正の保証が表示され、Enterpriseの機能は有効化できる担当者名とともにティザー表示されます。

これが失敗する場合

ほとんどの失敗は、その原因を自ら示します。何かを変更する前にメッセージを読んでください。

表示内容 原因 対処法
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のインストールとライセンスの適用」をお読みください。