メインコンテンツまでスキップ

Yabanin オンプレミス / エアギャップのインストールガイド

Docker/compose のみのオフライン経路(バンドルビルド、チェックサム/署名/SBOM の検証、docker load、ネットワークなしの最小 compose)については、offline-bundle.md を参照してください。

前提条件​

  • Kubernetes 1.28+(または互換: OpenShift 4.14+、Rancher)。
  • ワーカーノード 3 台。各 16GB RAM、各 4 vCPU。
  • GPU ノード(任意。ローカルモデル用: vLLM/Ollama)。NVIDIA operator を推奨します。
  • ReadWriteOnce をサポートする StorageClass。
  • ネットワークレベルで、外向き egress を遮断します(エアギャップ要件)。
  • エアギャップバンドルを持つジャンプホスト上の kubectl、helm 3.12+、docker(または ctr)。

手順 1 — エアギャップバンドルをコピーする​

yabanin-airgap-<tag>.tar.gz をジャンプホストへ転送します(USB、プライベートリンク経由の scp)。

手順 2 — オフラインレジストリへイメージをロードする​

scripts/airgap/load_bundle.sh yabanin-airgap-<tag>.tar.gz localhost:5000
# load_bundle.sh extracts the bundle, verifies manifest.sha256 (fails closed on
# any mismatch BEFORE docker load) and pushes every image to the registry.

手順 3 — インストール(シークレットは helm へ渡し、事前作成しない)​

チャート自身がすべての Secret をレンダリングします(<release>-secrets、-kek、-license)。同じ名前の Secret を事前作成すると、helm install はリソースの競合で失敗します。代わりに --set / -f で値を渡してください。

kubectl create namespace yabanin
helm install yabanin deploy/helm/yabanin-onprem \
-f deploy/helm/yabanin-onprem/values-airgap.yaml \
--set image.repository=localhost:5000/yabanin \
--set image.tag=<tag> \
--set secrets.pg_password=$(openssl rand -hex 16) \
--set secrets.cache_hmac_secret=$(openssl rand -hex 32) \
--set secrets.encryption_key=$(openssl rand -hex 32) \
--set secrets.session_key=$(openssl rand -hex 32) \
--set secrets.kek=$(openssl rand -hex 32) \
--set secrets.license=<vendor-issued-license-token>

注記(ライブ検証済み、R056-05):

  • secrets.pg_uri は空のままで構いません。migrate フックが、所有者 DSN を secrets.pg_password と同梱の postgres サービスから組み立てます。secrets.pg_uri を渡すのは、EXTERNAL の postgres(bundled.postgres=false)を使うときだけです。
  • Redis が設定されているときは、常に secrets.cache_hmac_secret が必須です(onprem チャートは常に同梱の Redis を設定します)。HEX である必要があります。16 進でない値は、ゲートウェイを invalid cache_hmac_secret: cache signer: invalid hex secret で終了させます。
  • post-install の migrate Job が自動で実行されます。postgres を待ち、IMP-88 の yabanin_app ロールをブートストラップし(冪等です。pg_dump はクラスタロールを運べないため、この SQL はマイグレーションに同梱できません)、YABANIN_REGION を設定してマイグレーションを適用します。同じジョブが post-upgrade としても実行されます。helm install がフック失敗を報告したら、Pod をデバッグする前に kubectl -n yabanin get jobs を確認してください。サービスは、マイグレーション済みのスキーマに対してのみ起動します。

手順 4 — 検証​

kubectl -n yabanin rollout status deploy/yabanin-gateway
kubectl -n yabanin port-forward svc/yabanin-gateway 18082:8082 &
curl -sf http://127.0.0.1:18082/healthz # expect {"redis":"up","status":"ok"}
curl -sf http://127.0.0.1:18082/healthz/license # licensed install: {"active":true,...}

(ゲートウェイの Service は ClusterIP です。port-forward を使うか、外部の入口が必要なら service.type を NodePort / LoadBalancer に設定してください。)

手順 5 — ローカルモデルを有効化する(任意)​

kubectl -n yabanin exec -it yabanin-postgres-0 -- \
psql -U yabanin -d yabanin -c \
"UPDATE models_registry SET enabled=true WHERE provider='vllm';"

ウェイトは、購入者が vLLM の PVC へ事前にロードする必要があります(エアギャップモードではダウンロードしません)。エアギャップ初回リクエスト を参照してください。

トラブルシューティング​

症状対処
license invalid signatureベンダー公開鍵の不一致。このビルド向けにトークンを再発行してください
ImagePullBackOffload_bundle.sh を実行してください。image.repository がオフラインレジストリを指しているか確認してください(image.registry はチャートの値ではありません)
invalid cache_hmac_secret ... invalid hexHEX の secrets.cache_hmac_secret を設定してください(openssl rand -hex 32)
role "yabanin_app" does not existpost-install のブートストラップフックが完了していません。migrate Job を確認してください。フックは冪等なので、helm upgrade を再実行してください
OOMKilledgateway.resources.limits.memory を上げてください。ホットループしているコンシューマがないか確認してください
connection refused :5432postgres の statefulset が準備できていません。PVC がバインドされているか確認してください
RLS の row-level security エラーマイグレーションがリージョンなしで実行されています。フックは YABANIN_REGION を設定します。手動での再実行: YABANIN_REGION=onprem yabanin-migrate(リージョンはフラグではなく環境変数です)