vCluster、vCluster Platform、ingress-nginx はサードパーティ製品です。SambaNova はこれらの保守・推奨・監査を行っていません。本リファレンスアーキテクチャは情報提供を目的としており、これらの製品の変更に伴い内容が古くなる可能性があります。
- CPU ノード (x86_64、RDU なし) は、SambaStack のプラットフォームサービス (API ゲートウェイ、UI、認証、Postgres、Redis)、ingress コントローラー、テナントの DNS を実行します。
- RDU ノード は、モデルバンドルの Pod のみを実行します。
検証済みの構成: SambaStack 2.3.2、RKE2 v1.35.5 ホスト、vCluster CLI および
vcluster-pro 0.36.4、vCluster Platform 4.12.4 (無料プラン)、テナント Kubernetes v1.35.10、RHEL 8.10 プライベートノード、containerd v2.1.6 (静的ビルド)、ingress-nginx チャート 4.15.1。vCluster Platform の無料プランには、インスタンス全体で 64 CPU または 32 GPU までの上限があります。これを超える規模のデプロイメントには有料プランが必要です。vCluster の料金ページ をご参照ください。Kubernetes 1.35 用の vCluster 標準ノードバンドルは、RHEL 8.10 では動作しません。ステップ 4 では、代わりに containerd の静的ビルドを使用する RHEL 8 用バンドルをビルドします。本番投入前に、テストノードでバンドルを検証してください。
アーキテクチャ
各要素は次のように連携します。- 参加。
vcluster token createがブートストラップトークンを発行します。各ノードは、RHEL 8 バンドルを指定して join スクリプトを実行します。このスクリプトが kubelet と containerd をインストールし、NodePort 経由でノードをテナントの API サーバーに参加させます。 - 制御トラフィック。 すべての接続はノード側から始まり、外向きにテナントの API サーバーへ向かいます。コントロールプレーンからノードに接続することはありません。
- ログと exec。 ノード上の konnectivity エージェントが、コントロールプレーン Pod 内の konnectivity サーバーへのトンネルを常時維持します。API サーバーは、このトンネルを逆向きにたどって kubelet に到達します。
- Pod ネットワーク。 Flannel は、テナント専用の Pod CIDR と Service CIDR 上で動作します。これらがホストのネットワークに触れることはありません。
- アプリケーショントラフィック。 DNS は、テナントの SambaStack ホスト名を CPU ノードに向けます。CPU ノード上では、ホストネットワークで動作する ingress-nginx が TLS を終端し、SambaStack にルーティングします。SambaStack は、推論リクエストを RDU ノード上のモデル Pod へ送ります。
- 配置。 ノードラベルによって 2 種類のノードを分離します。SambaStack 自身のサービス、Postgres、Redis は
sambanova.ai/role=control-planeを選択するため、CPU ノードだけで動作します。SambaStack の推論オペレーターはsnRduArchに基づいてモデルバンドルの Pod を配置するため、これらは RDU ノードだけで動作します。 - ライセンス。 コントロールプレーン Pod は、プライベートノードのエンタイトルメントを、ホストクラスター上の vCluster Platform から取得します。
前提条件
ホストクラスター側 (セットアップは 1 回のみ):- SambaStack の オンプレミス要件 を満たすホストクラスター。
- テナントのコントロールプレーン用に、
control-plane=sharedのラベルを付けた CPU ノードプール。 - テナントのコントロールプレーンの状態を保存するストレージクラス。本リファレンスでは
openebs-hostpathを使用します。 - vCluster Platform 用の ingress コントローラーとホスト名、およびホストクラスターから
admin.loft.shへの外向き (egress) 通信。 - 各テナント API を公開する手段:
LoadBalancerService、または本リファレンスのようにホストノード上の NodePort。
- CPU ノード: SambaStack プラットフォーム用の、RDU を搭載しない x86_64 (Intel または AMD) サーバー。1 台を失ってもプラットフォームが存続できるよう少なくとも 2 台を用意し、SambaStack のオンプレミス要件に従ってサイジングしてください。
- RDU ノード: モデルバンドル専用の、テナントの RDU サーバー。
- RHEL 8.10 で動作し、ホストクラスターのメンバーではないこと。ノードが参加できるクラスターは 1 つだけです。
- cgroup v2 が有効であること。 Kubernetes 1.35 の kubelet と kubeadm は、RHEL 8 のデフォルトである cgroup v1 上では起動を拒否します。
stat -fc %T /sys/fs/cgroup/の出力がcgroup2fsである必要があります。 - 他の kubelet、Docker、containerd が動作していないこと。
- ホストノードの IP に対する、テナントの NodePort への外向き TCP 接続 (API サーバーおよび konnectivity 用)。
- Kubernetes バンドルと containerd をダウンロードするための
github.comへのアクセス、または両ファイルがノード上に事前配置されていること。 - SELinux が
Enforcingの場合:rpm.vcluster.comへのアクセス。join スクリプトは、ここからvcluster-selinuxポリシーパッケージをインストールします。
- テナントの SambaStack API と UI 用の、一意のホスト名と TLS 証明書 (オンプレミス要件と同様)。これらのホスト名の DNS は、テナントの CPU ノード、またはその前段の VIP (仮想 IP) に向けます。
- SambaStack 2.1.1 以上。プラットフォームを CPU ノードに固定するために使用する
global.nodeSelector設定は、このバージョンで追加されました。
kubectl、helm v3.19 以上、および vCluster CLI。
コンポーネント
テナントのセットアップ
特に記載がない限り、コマンドはオペレーターのマシンから実行します。tenant1、vcluster-tenant1、<host-node-ip>、<platform-hostname>、<node-name> は環境に合わせて置き換えてください。
vCluster Platform のインストール (ホストごとに 1 回)
プライベートノードはオープンソース版 vCluster には含まれず、vCluster Platform が必要です。無料プランにはプライベートノード機能が含まれますが、インスタンス全体で 64 CPU または 32 GPU までの上限があります。ノードのサイズと照らして vCluster の料金ページ をご確認ください。インストールでは、次に、
config.loftHost に、オペレーターのマシン・ホストノード・Pod のいずれからも名前解決できるホスト名を設定する必要があります。platform-values.yaml
https://<platform-hostname> の Platform UI に admin としてログインし、無料プランを有効化します。管理者パスワードは vcluster platform start が出力します。後から確認するには、ホストに対して helm get values loft -n vcluster-platform を実行してください。インスタンスを有効化するまで、vcluster create は失敗します。テナントのコントロールプレーンが vCluster Platform に到達できるよう、CLI からのログインには、ローカルのポートフォワードではなく外部 URL を使用します。--insecure は、Platform の証明書が自己署名の場合に指定します。ホスト名に信頼された証明書が設定されている場合は外してください。テナントコントロールプレーンの作成
この設計の要となる設定は次のとおりです。ホストの CPU ノードプールに taint が設定されている場合は、対応する
vcluster.yaml
controlPlane.statefulSet.scheduling.tolerations を追加してください。追加しないと、コントロールプレーンの Pod は Pending のままになります。CoreDNS は、ステップ 6 で最初のテナント CPU ノードが参加してラベル付けされるまで Pending のままですが、これは想定どおりの動作です。RHEL 8.10 ノードの準備
すべての CPU ノードとすべての RDU ノード上で、root として実行します。まず cgroup v2 を確認します。出力が 既存のコンテナランタイムを停止し、スワップを無効化し、カーネルモジュールと sysctl を読み込みます。
tmpfs の場合は、ここで作業を中止してください。/etc 配下のファイルにより、これらの設定は再起動後も維持されます。RHEL 8 ノードバンドルのビルド
バンドルのビルドは、RHEL 8.10 ノードのうち任意の 1 台で、root として 1 回だけ行います。バンドル内の containerd バイナリを、同一バージョンの containerd 静的ビルドで置き換えます。
/root/kubernetes-v1.35.10-amd64-el8.tar.gz を、他のすべての CPU ノードと RDU ノードの /root にコピーします。バンドルのバージョンは、テナントの Kubernetes バージョン (controlPlane.distro.k8s.image.tag) と一致している必要があります。テナントをアップグレードする際は、新しいバンドルをビルドしてください。ノードの参加
CPU ノードを先に、RDU ノードを後に参加させます。参加の手順はどのノードでも同じです。オペレーターのマシンから、テナントの kubeconfig を使って join トークンを発行します。このコマンドは、参加が完了すると、最後に
curl ... | sh - 形式の join コマンドを出力します。vCluster はこれを curl -k 付きで出力しますが、-k はテナント API サーバーの証明書の検証をスキップします。各ノード上で root として、--node-name と --bundle-path を追加して実行します。This node has joined the cluster と表示されます。1 つのトークンで、有効期限が切れるまで複数のノードを参加させられます。SELinux が Enforcing の場合、join の過程で rpm.vcluster.com から vcluster-selinux パッケージがインストールされます。この URL にアクセスできないノードでは、先にパッケージをインストールしたうえで、join コマンドに --skip-selinux-rpm を追加してください。ノードへのラベル付与
どのノードで何が動くかは、このラベルで決まります。CPU ノードにはプラットフォーム用のラベルを、RDU ノードには SambaStack の推論オペレーターが選択する RDU ラベルを付与します。1 つのノードに両方のラベルを付けないでください。
Pending だった CoreDNS は、CPU ノードにラベルが付くと、そのノード上で起動します。テナントへの ingress コントローラーのインストール
プライベートノードではホストの ingress コントローラーを利用できないため、テナント専用の ingress コントローラーが必要です。このインストールでは、ingress-nginx を CPU ノードだけで実行し、CPU ノードのホストネットワークのポート 80 と 443 にバインドします。これにより、テナントの SambaStack ホスト名の DNS を CPU ノードの IP に向けられるようになります。
ノードのポート 80 と 443 で待ち受け、標準の
Ingress オブジェクトを処理できる ingress コントローラーであれば、ingress-nginx の代わりに使用できます。動作確認
テナント側から:kubectl logs と kubectl exec が動作することを確認します。
テナントへの SambaStack のインストール
テナントの kubeconfig を使い (export KUBECONFIG=tenant1.kubeconfig)、標準の オンプレミスクイックスタート に従って SambaStack をインストールします。レジストリ URL、サービスアカウントキー、チャートバージョンは SambaNova から提供されます。通常のインストールと異なるのは、次の設定だけです。
ノードセレクタ。 ステップ 6 で付与したノードラベルによって、各 Pod の稼働場所が決まります。
global.nodeSelectorは、SambaStack のすべてのサービス (ゲートウェイ、UI、認証、推論オペレーターなど) を、sambanova.ai/role=control-planeのラベルが付いた CPU ノードに配置します。- Postgres、Redis、OpenEBS は同梱チャートから提供され、このグローバル設定を読まないため、それぞれのセクションに同じセレクタを設定します。
- モデルバンドルの Pod は影響を受けません。SambaStack の推論オペレーターが、
snRduArch=sn40-16のラベルが付いた RDU ノードに配置します。
sambastack.yaml に追加します。SambaStack 2.1.1 以上が必要です。サービスごとのオーバーライド、toleration、その他のスケジューリング設定については、SambaStack の Helm values ファイルと SambaStack v2.1.1 リリースノート をご参照ください。
sambastack.yaml (tenant additions)
openebs-hostpath クラスの /scratch/openebs 配下に保存します。上記のセレクタを設定すると、このパスは CPU ノード上になります。そこに十分なディスクを確保するか、openebs.localpv-provisioner.hostpathClass.basePath を設定してください。
Ingress と DNS。 ステップ 7 でインストールした ingress-nginx コントローラーを使用します。これはテナントのデフォルトの ingress クラスです。SambaStack の API と UI のホスト名の DNS レコードは、CPU ノードの IP か、その前段の VIP に向けてください。RDU ノードには決して向けないでください。クイックスタートの要件どおり、これらのホスト名はテナントの内側からも名前解決できる必要があり、TLS 証明書は信頼された認証局 (CA) が発行したものである必要があります。
インストール後、プラットフォームの Pod が CPU ノード上に、モデルの Pod が RDU ノード上にあることを確認します。
KUBECONFIG 未設定) は変わりません。kubectl -n vcluster-tenant1 get pods には、引き続きコントロールプレーンの Pod だけが表示されます。
RDU ノードのメンテナンス
プラットフォームは CPU ノード上で動作しているため、RDU のメンテナンスが影響するのは、そのノード上のモデルレプリカだけです。メンテナンス中もモデルがサービングを続ける必要がある場合は、モデルごとに少なくとも 2 台の RDU ノードを計画してください。Ready の間だけ行ってください。
制限事項
- 本リファレンスは、RHEL 8.10 のプライベートノードでのみ検証しています。RHEL 10 ノードでは検証していません。
- RHEL 8.10 ノードには、ステップ 4 の RHEL 8 バンドルが必要です。テナントの Kubernetes をアップグレードするたびにバンドルを再ビルドし、先にテストノードで検証してください。
- vCluster のノード間 VPN は、RHEL 8.10 ノードでは利用できません。本リファレンスでは使用していません。
- join トークンには有効期限があります。ノードを追加するたびに、新しいトークンを発行してください。
- テナント API は、ホストノードの 1 つの NodePort 上にあります。本番環境では、
LoadBalancerService または VIP を使用してください。 - vCluster Platform は、無料プランの検証のために
admin.loft.shに到達できる必要があり、無料プランの CPU・GPU の上限が適用されます。 - テナントコントロールプレーンの状態は、1 つのボリューム上にあります。本番環境ではバックアップを取るか、vCluster の高可用性構成を実行してください。
クリーンアップ
helm uninstall loft -n vcluster-platform を実行してください。

