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