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

第 2.15 章

Day 2:Nexus の運用

最初の1週間が経過した後の、インストール環境を運用する日常業務。再起動後のキーストアの封印解除から始まり、アンインストールで終わります。

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

読了時間 18 分

Harrow Port Authorityのサーバールームで初めて停電が起きたとき、キーを必要とする部分を除いてすべてが復旧しました。PodはRunning状態になり、コンソールも読み込まれました。しかし、誰もファイルを開くことができませんでした。Tomás Reillyはこのことについて読んだことがありましたが、それでも理由を思い出すのに20分かかりました。キーストアのアンシーラーは、そのノードが再起動するたびにシール(封印)された状態で起動し、カストディアン(鍵管理者)だけがそれを開くことができます。

この章では、最初の1週間が過ぎた後のオペレーターの日常業務について、キーストアとそのカストディアンからアンインストールまでを追っていきます。ここにあるすべてのnexusctlサブコマンドは--explainを受け入れます。これは、実行するはずのkubectlおよびhelm操作を実際には実行せずに表示します。本番クラスターで初めて何かを実行する際には、これを使用してください。

キーストアの管理

1つのインストール環境には、その名前空間内に2つのOpenBaoサーバーがあります。キーストアであるopenbaoは、Nexusが使用するすべてのキーを保持します。アンシーラーであるopenbao-unsealerは2つ目の小さなOpenBaoであり、その唯一の仕事はキーストアをアンシール(封印解除)することです。キーストアはアンシーラーのトランジットキーを通じて自動的にアンシールされます。アンシーラー自体はシャミアの秘密分散法(Shamir's scheme)でシールされており、5つのシェアのうち任意の3つでアンシールされます。

初回インストール時に、カストディJobがクラスター内の両方のサーバーを初期化します。このJobは、自身のメモリ内でアンシーラーのシェアとキーストアのリカバリキーを、keys.custody.recipientsで指定されたすべてのカストディアン宛てに暗号化し、暗号文(Secret openbao-unseal-shares-encryptedおよびopenbao-recovery-keys-encrypted)のみを保存します。また、同じJob内で両方のルートトークンを失効させます。各カストディアンのバンドルには単独でアンシールするのに十分なシェアが含まれているため、再起動後に必要なカストディアンは1人だけです。

ノード再起動後

アンシーラーが稼働しているノードが再起動(停電、マシンの再起動、コンテナランタイムの再起動など)すると、アンシーラーはシールされた状態で起動します。カストディアンがアンシールするまで、キーストアもシールされたままになり、キーを必要とするものは一切機能しません。コンソールは応答し、ユーザーはサインインできますが、暗号化されたコンテンツを開く、クレームを行う、コンパイル済みパーツをチェックするなど、キーストアからのキーを必要とする操作はすべて待機状態になります。

各Pod内のOpenBao自体に状態を問い合わせます。アンシーラーの場合は次のとおりです。

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

キーストアについては、-tls-server-name=openbaoを指定してopenbao-0に対して同じコマンドを実行します。bao statusは、サーバーがアンシールされている場合は0、シールされている場合は2、応答できなかった場合は1で終了します。終了コード1は何も結論付けません。Podがまだ起動していない可能性があるためです。1分待ってから再度問い合わせてください。アンシーラーがアンシールされており、キーストアがまだシールされている場合、キーストアは自己アンシール中であるため、何もする必要はありません。

左:「カストディアン(自身のage IDを保持)」とラベル付けされた人物アイコン。右に向かって矢印が伸び、「カストディアンのマシン上のunseal.sh(1回の復号)」というボックスに入っています。そこから「kubectl port-forward、アンシーラーの認証局(CA)に対してチェックされるTransport Layer Security(TLS)」とラベル付けされた矢印が、「openbao-unsealer(シャミアの5シェア、任意の3つ)」というボックスに入っています。アンシーラーからは、「トランジットキー、自動」とラベル付けされた2つ目の矢印が、「openbao、キーストア」というボックスに入っています。キーストアからは、小さなボックス「nexus-keys」、「nexus-auth」、「その他のサービス」へと矢印が扇状に広がっています。カストディアンの下には「IDはこのマシンから決して出ない」という注記があります。
ノード再起動後にカストディアンが行うこと。

アンシール

チャートには、files/custody/フォルダ内にunseal.shが同梱されており、どのリリースでもバイト単位でまったく同じ内容になっています。カストディアンはこれを自身のマシンで実行します。このスクリプトは暗号化されたSecretを読み取り、カストディアンのIDで1回復号し(Secure EnclaveのIDの場合はTouch IDを1回要求します)、シェアをアンシーラーに送信して、アンシールされたことを確認します。シェアがファイルに書き込まれたり、コマンドラインに置かれたりすることは一切ありません。

Harrowでは、ポートフォワードを介してダイレクトモードでこれを実行しています。

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity>はカストディアンのage IDファイルであり、keys.custody.recipients内の受取人(recipient)の1つの秘密鍵側です。UNSEAL_RESOLVEはアンシーラーの証明書が持つ名前です(<namespace>はNexusがインストールされている名前空間で、デフォルトはnexusです)。これにより、接続先が127.0.0.1であっても、アンシーラー自身のCAに対してTLSがチェックされます。このスクリプトが証明書チェックをオフにすることは決してありません。

終了コード 最後の行 意味
0 UNSEALED nexus/openbao-unsealer-0 アンシール完了。すでにアンシールされていた場合は、何も送信されません
1 STILL-SEALED … 依然としてシールされているか、アンシール呼び出しが失敗しました
2 UNSEAL-REFUSED … 前提条件が不足しています(メッセージ内に名前が示されます)
3 UNSEAL-REFUSED … このIDではシェアを復号できないため、このインストール環境のカストディアンではありません。何も送信されませんでした

1分以内にキーストアも自動的に追随します。kubectl -n nexus get deploy,statefulsetを使用して、すべての準備が再び整ったことを確認してください。

カストディアンはインストール前に選出され、各自が自身のマシン上で自分のキーを作成します。チャートが認識するのは公開鍵側のみです。

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

1つ目のコマンドは通常のage IDを作成します。その受取人(recipient)はファイル内の# public key: age1...の行です。2つ目のコマンドはMacのSecure Enclave内に保持されるIDを作成し、その受取人はage1se1で始まります。どちらの受取人もkeys.custody.recipientsに入力します。IDファイルはカストディアンの手元にオフラインで留まります。

バックアップと復元

「バックアップと復元(Back up and restore)」には、各ストアの最新のバックアップ日時と、その復元が実際にテストされた最新の日時が表示されます。バックアップは復元されて初めて証明されるため、このページでは両方を追跡します。6つのストアがバックアップされます。メインデータベースはユーザーと設定、ジョブと監査ログを保持します。その隣にはナレッジグラフと検索インデックスがあり、さらにファイルストアとメモリストアがあります。6つ目はキーであり、シールされた状態でデータとは別に保管されます。バックアップはお客さま自身のキーで暗号化されてお客さま自身のストレージに送られ、Adverantがそれらを読み取ることはできません。ルールで定められた期間内にストアのテスト復元が行われていない場合、ページには「今すぐテスト(Test it now)」ボタンが付いたプレートRESTORE_TEST_OVERDUEが表示されます。テスト復元は別の領域で実行されるため、誰にも気づかれません。

同じ2つの操作はコマンドラインからも利用できます。

nexusctl backup now
nexusctl backup verify

backup nowはすべてのストアのバックアップを一度に取得します。backup verifyは最新のバックアップをチェックします。不安のある変更を行う前には、両方を実行してください。

バックアップと復元
バックアップと復元
各ストアの最新のバックアップと最後にテストされた復元。検索インデックスのテスト期限が過ぎており、プレートで今すぐ実行するよう提案されています。

復元するには、バックアップを指定します。

nexusctl restore --from <backup-id>

<backup-id>は「バックアップと復元」のリストから取得します。復元には2人目の承認が必要であり、実行中は進行状況バーに開始時刻と承認者が表示されます。復元中は全員が読み取り専用になります。これはロックアウトとは異なり、ユーザーはサインインして閲覧することができます。ジョブは開始されず(スケジュールは待機し、後で追いつきます)、検索インデックスが戻ると検索が復帰します。バックアップ取得後に書き込まれたものはすべて失われるため、復元レポートにはやり直しができるよう所有者ごとにそれらがリストアップされます。

復元中
復元中
進行中の復元。ストアは順番に復旧し、最後のストアが戻るまでユーザーは読み取り専用となり、すべてのページの通知に復旧予定時刻が表示されます。

バックアップとあわせて、もう1つ保管しておくべきものがあります。nexus名前空間にあるSecret nexus-generatedです。チャートは初回インストール時にインストール環境の生成パスワードと暗号化キーを作成し、アップグレードのたびにそのSecretからそれらを読み戻します。EXTERNAL_KEY_ENCRYPTION_KEYの下でシールされたデータは、そのキーでしか開けません。このSecretを保持する者はそれらのキーを保持することになるため、最も機密性の高い情報を保管している場所にこのSecretのコピーを保管してください。

アップグレード

Tomásは2つのステップでアップグレードを行います。まず、何が変更されるかを問い合わせます。

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

プランには、そのリリースでの変更点、データベースの構造に対する変更、およびそれを元に戻せるかどうかがリストアップされます。次に、彼はそれを適用します。

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

適用(apply)では、まずバックアップを取得し、プリフライトを実行します。その後、エンジンをウェーブ(段階)ごとに移行し、各ウェーブは前のウェーブが10分間正常な状態を保つまで待機します。「アップグレード(Upgrade)」ページには、進行中の各ウェーブと、その間のインストール環境の健全性が表示されます。また、いつまで元に戻す道(ロールバック)が開かれているかも示されます。その日付を過ぎると、元に戻すには復元が必要になります。いずれかのステップが失敗した場合、Nexusはすべてのエンジンを前のリリースにロールバックし、それらをチェックします。その後、通知UPGRADE_ROLLED_BACKに失敗したステップの名前と、データが変更されなかったことが示されます。「再試行(Try again)」の前に修正方法が表示され、サポートバンドルもボタン1つで作成できます。

外部接続のないインストール環境の場合、バンドルはメディアで届きます。「メディアからインポート(Import from media)」は、インストール環境にインストールされているAdverantのリリースキーに対してリリースの署名をチェックし、バージョンが前進のみしていることを確認します。他の誰かによって署名されたファイルはMEDIA_SIGNATURE_INVALIDで拒否され、何も読み込まれず、稼働中のリリースがそのまま稼働し続けます。

アップグレード
アップグレード
進行中のアップグレード。最初にバックアップが取得され、3つのウェーブのうち2つ目が進行中であり、指定された日付まで元に戻す道が開かれています。
アップグレードが失敗しロールバックされました
アップグレードが失敗しロールバックされました
ボリュームの空き容量が不足したため、ウェーブが失敗しました。データはそのままの状態で、すべてのエンジンが前のリリースに戻っており、「再試行」の前に修正方法がリストアップされています。

内部で起きていること

nexusctl upgrade applyはチャートに対してhelm upgradeを実行します。ご自身でHelmを使用してアップグレードする場合も、同じルールが適用されます。

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

新しいPodがロールアウトされる前に、スキーマが移行します。チャートのマイグレーションは順番に実行されるプリアップグレードフックです。最初にデータベースのブートストラップ、次に各サービスのマイグレーション、そしてコンソールのBackend For Frontend(BFF)のマイグレーションが実行されます。カストディJobも実行されますが、すでに初期化されているインストール環境ではそのことを確認するだけで何も変更しません。各フックJobのバックオフ制限(backoff limit)は0であるため、マイグレーションが失敗するとアップグレードは停止し、サイレントに再試行されることは決してありません。再試行する前にkubectl -n nexus logs job/<hook-job>でログを確認してください。

各サービスのPodは、新しいリリースのイメージに対するマイグレーションが適用されたことがリリース台帳(release ledger)に示されるまで、初期化コンテナwait-for-schema内で待機します。ロールバック後、または値(values)のみを変更したアップグレードの後では、再起動されたPodは自身の行を見つけてすぐに起動します。

アップグレードの前に

リリースノートにある以下の3つの点については、事前に計画を立てておく価値があります。

  1. 閑散期にアップグレードしてください。以前のチャートから作成されたインストール環境の初回アップグレードでは、ブートストラップジョブが古いデフォルトのテーブル権限を剥奪し、各サービスは自身のマイグレーションから自身の権限を取り戻します。そのマイグレーションが実行されるまで、サービスは自身のテーブルを使用できません。この空白時間は数秒間続きます。数秒間であっても問題になる場合は、最初にサービスをゼロにスケールダウンし、マイグレーションジョブが完了してから再びスケールアップしてください。
  2. すべてのアプリケーションプログラミングインターフェース(API)キーに組織を割り当ててください。組織が割り当てられていないキーは、nexus-graphragを含む、nexus-authを通じてキーをチェックするすべてのサービスによって403 TOKEN_ORG_MISSINGで拒否されます。アップグレードする前に、そのような各キーに組織を割り当てるか、新しいキーを発行してください。古いbcryptキーは、強制失効日(hard-revoke date)まで引き続き機能します。
  3. アップグレード後にキャッシュされたAPIキーをフラッシュしてください。フラッシュするまで、最大1時間分のキャッシュされたキーエントリが誤ったアプリケーション名を保持し続けます。nexus-authのキャッシュであるインストール環境のValkey(nexus-valkey、パスワードはSecret nexus-generatedのVALKEY_PASSWORD下)に対して以下を実行してください。
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

上記はデフォルトのクラスター内ストアの場合です。dataTier.valkey.mode: externalを使用している場合はそのようなPodは存在しないため、dataTier.valkey.external.existingSecretで指定されたSecretのパスワードを使用して、ご自身のValkeyホストに対して同じスキャンと削除を実行してください。

ロールバック

「アップグレード」ページに表示される期間内であれば、「元に戻す(Go back)」によってすべてのエンジンが前のリリースに戻ります。この期間を過ぎると、元に戻すにはアップグレードが最初に取得したバックアップを復元する必要があります。

アップグレードやロールバックをまたいで決して変更してはならない値が2つあります。

keys.installationNameは永続的です。最初のキーストアのブートストラップ時にこの値の下でインストール環境のIDが生成され、そのIDがライセンスで指定されるものになります。このインストール環境に適用するすべてのvaluesファイルで、常にまったく同じ値を使用してください。

Secret nexus-generatedはそのまま維持されなければなりません。アップグレードのたびに、チャートはそこからEXTERNAL_KEY_ENCRYPTION_KEYを読み取り、その形式をチェックします。32バイトのbase64でも、古いインストールの生の32バイトキーでもない値である場合、EXTERNAL_KEY_ENCRYPTION_KEY_INVALIDでレンダリングを停止し、チャートがその値を出力することは決してありません。これは、誰かがSecretを編集または置換したことを意味します。このインストール環境のデータがシールされているキーを、32バイトのbase64(printf %s "$OLD" | base64)として元に戻し、再度アップグレードしてください。新しいランダムなキーを設定すると、古いキーの下でシールされたすべてのものが読み取り不能になります。

スケーリング

valuesファイルには、各コンポーネントのスイッチとサイズの設定があります。必須コンポーネントはオフにできません。スイッチの設定がどうであれ、チャートはそれらを実行します。その他のコンポーネントには、より多くのレプリカとより多くのリソースを割り当てることができます。

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

上記と同様にhelm upgradeで適用します。ボリュームのサイズはdataTier.<store>.sizeの下で設定されます。サイズを引き上げる前に、お使いのストレージクラスがボリュームを拡張できることを確認してください。「インストール環境の状況(How the installation is doing)」では、クラスターのプロセッサとメモリがどの程度使用されているか、およびそれぞれの残りの余裕がグラフで示されます。先に不足しそうな方から拡張してください。

サポートバンドル

HarrowがAdverantのサポートを必要とするとき、Tomásはサポートバンドルを作成します。

nexusctl support-bundle --out harrow-support-4471.tar.gz

コンソールの「サポートバンドル(Support bundle)」ページでも同じファイルが作成されます。これには、過去24時間のエンジンログと、健全性およびバージョンの詳細が収集されます。設定はシークレットを除いた状態で、プリフライトレポートおよびインストールレポートとともに含まれます。何かが書き込まれる前に、リダクション(墨消し)機能によって名前とシークレットがプレースホルダーに置き換えられ、外部に出る内容の正確なプレビューを確認できます。ユーザー自身のコンテンツが収集されることは決してありません。バンドルは、アカウントの「サポートとサポートバンドル(Support and support bundles)」ページへのアップロードとして、またはメディアで持ち出されるファイルとしてAdverantに送られます。リクエストに名前が記載されたサポートエンジニアだけがそれを開くことができ、30日後に消去されます。

サポートバンドル
サポートバンドル
サポートバンドルの作成。何かが外部に出る前に、リダクションプレビューで隠される内容が示され、指定されたエンジニアだけがそれを開くことができます。

証跡のエクスポート

監査人や社内のコンプライアンスチームは、プラットフォームが説明どおりに動作することの証明を求めることがよくあります。nexusctl evidence exportはそれを書き出します。

nexusctl evidence export --out harrow-evidence-2027-01

エクスポートする記録と並んで、このコマンドはプラットフォームの受け入れプローブを実行します。すなわち、人工知能(AI)ルーターに到達可能で応答があること、UNOジョブがディスパッチされて完了すること、および組織をまたぐ読み取りが拒否されることです。これらの結果は出力フォルダ内のprobes.jsonに保存されます。

一目でわかるステータス

nexusctl status --jsonは、インストール環境が健全かどうか、および各コンポーネントがどの状態にあるかを応答します。また、ライセンスの状態とその有効期限、エディション、稼働中のリリースも報告します。コンパイル済みパーツはそれぞれダイジェストと署名とともにリストアップされます。これは、ご自身の監視システムの背後に組み込むためのコマンドです。

アンインストール

nexusctl uninstall --profile <profile-file>

<profile-file>はクラスターのデプロイメントプロファイルであり、プラットフォームチームがクラスターを運営している場合にnexusctl handoff --profile <profile-file> --out <dir>に渡したものと同じファイルです。ハンドオフ(Handoff)は、そのチームのために、Nexusがクラスターに必要とするものの平易な言葉でのリストと、それを満たすためのマニフェストを書き出します。アンインストール(Uninstall)はNexusの名前空間のみを削除し、それ以外は何も削除せず、バックアップを保持します。インストール環境のIDはそれとともに消去されます。同じクラスターへの後のインストールは新しいIDを持つ新しいインストール環境となるため、そのクレームは新しいクレームとなり、そのライセンスは新しいライセンスとなります。

This installation ページ

インストール環境のオペレーターには、メニュー内に独自のグループ「このインストール環境(This installation)」があり、この章の大部分はコンソール内のそのページ群で行われます。一般メンバーがそれらのページの1つを開くと、操作可能な人物の名前が記された「管理者ではありません(Not an administrator)」ページが表示されます。

ページ 用途
ライセンスと解放される機能 ライセンスとその機能グループ(第2.13章、ライセンス)
ライセンスが期限切れになった場合 このライセンスの日付を用いた、文章による有効期限ラダー
コンパイル済みパーツ ライセンスされた各モジュールとその毎夜の署名チェック
Adverantへの使用状況明細 送信前に確認可能な年間カウンター
バージョンとアップグレード インストールされたすべてのバージョン、およびそのインストール実施者と日時
アップグレード 段階的なアップグレードと元に戻す方法
バックアップと復元 各ストア、その最新のバックアップ、および最後にテストされた復元
インストール環境の稼働状況 ノード、キャパシティ、ランニングコスト、および警告
キーと消去 各組織のキー、および理由と2人目の承認を伴う消去(Erase)
インシデント 未解決および解決済みの問題と、行われた対処
まもなく廃止 オフにされる予定の機能、その日程、エクスポート、および代替機能
ステータス 現在および過去30日間のNexusの各パーツの状態(誰でも読める平易な表現)
サポートバンドル Adverantに送信される内容とその方法

これらのページのうち2つについては少し補足が必要です。「コンパイル済みパーツ(Compiled parts)」は、ライセンスされたすべてのモジュールを毎夜Adverantの署名に対してチェックします。変更されたモジュールのコピーは拒否されて決して読み込まれず、署名済みのコピーが稼働し続けます。また、改ざんされたコピーが見過ごされないよう、ページには月ごとの拒否回数がカウントされます。「ステータス(Status)」は、組織内の誰もが読めるように書かれています。現在および過去30日間のNexusの各パーツの状態が日ごとのバーとして表示され、予定されているメンテナンスや最近のインシデントも示されます。オペレーターは同じページからインシデントやメンテナンス期間を追加できます。

Communityインストール環境には、「このインストール環境(Community)」という1つのページがあり、そのバージョン、健全性、およびアップデートが表示されます。Enterprise向けのページは、誰がそれらを有効にできるかを示すティザーとしてそこに表示されます。