メインコンテンツへスキップ
vCluster、vCluster Platform、ingress-nginx はサードパーティ製品です。SambaNova はこれらの保守・推奨・監査を行っていません。本リファレンスアーキテクチャは情報提供を目的としており、これらの製品の変更に伴い内容が古くなる可能性があります。
プライベートノードモデルでは、テナントのワーカーノードはテナントのコントロールプレーンに直接参加します。ノードがホストクラスターのメンバーになることはなく、ノード上でホストのコンポーネントが動作することもありません。テナントのコントロールプレーンは、ホストの CPU ノードプール上の Pod として動作します。kubelet・CNI・DNS・スケジューラーはテナントが自前のものを持ち、いずれも vCluster がインストールします。 外部のテナント、容量を再販するテナント、規制対象のテナント、および cluster-admin アクセス権を取得するテナントには、このモデルを使用してください。信頼できる社内テナントであれば、共有ノード の方がセットアップが少なくて済みます。両モデルの比較は 概要 をご参照ください。 本ガイドでは、RHEL 8.10 のノードを Kubernetes 1.35 で動作するテナントに参加させます。各テナントには 2 種類のプライベートノードを用意します。
  • CPU ノード (x86_64、RDU なし) は、SambaStack のプラットフォームサービス (API ゲートウェイ、UI、認証、Postgres、Redis)、ingress コントローラー、テナントの DNS を実行します。
  • RDU ノード は、モデルバンドルの Pod のみを実行します。
プラットフォームが RDU ノード上で動作することはないため、テナントの API・UI・ログインを停止させることなく、RDU ノードのドレイン・再起動・アップグレードを行えます。移動または停止するのは、そのノード上のモデルレプリカだけです。
検証済みの構成: 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 用バンドルをビルドします。本番投入前に、テストノードでバンドルを検証してください。

アーキテクチャ

各要素は次のように連携します。
  1. 参加。 vcluster token create がブートストラップトークンを発行します。各ノードは、RHEL 8 バンドルを指定して join スクリプトを実行します。このスクリプトが kubelet と containerd をインストールし、NodePort 経由でノードをテナントの API サーバーに参加させます。
  2. 制御トラフィック。 すべての接続はノード側から始まり、外向きにテナントの API サーバーへ向かいます。コントロールプレーンからノードに接続することはありません。
  3. ログと exec。 ノード上の konnectivity エージェントが、コントロールプレーン Pod 内の konnectivity サーバーへのトンネルを常時維持します。API サーバーは、このトンネルを逆向きにたどって kubelet に到達します。
  4. Pod ネットワーク。 Flannel は、テナント専用の Pod CIDR と Service CIDR 上で動作します。これらがホストのネットワークに触れることはありません。
  5. アプリケーショントラフィック。 DNS は、テナントの SambaStack ホスト名を CPU ノードに向けます。CPU ノード上では、ホストネットワークで動作する ingress-nginx が TLS を終端し、SambaStack にルーティングします。SambaStack は、推論リクエストを RDU ノード上のモデル Pod へ送ります。
  6. 配置。 ノードラベルによって 2 種類のノードを分離します。SambaStack 自身のサービス、Postgres、Redis は sambanova.ai/role=control-plane を選択するため、CPU ノードだけで動作します。SambaStack の推論オペレーターは snRduArch に基づいてモデルバンドルの Pod を配置するため、これらは RDU ノードだけで動作します。
  7. ライセンス。 コントロールプレーン Pod は、プライベートノードのエンタイトルメントを、ホストクラスター上の vCluster Platform から取得します。

前提条件

ホストクラスター側 (セットアップは 1 回のみ):
  • SambaStack の オンプレミス要件 を満たすホストクラスター。
  • テナントのコントロールプレーン用に、control-plane=shared のラベルを付けた CPU ノードプール。
  • テナントのコントロールプレーンの状態を保存するストレージクラス。本リファレンスでは openebs-hostpath を使用します。
  • vCluster Platform 用の ingress コントローラーとホスト名、およびホストクラスターから admin.loft.sh への外向き (egress) 通信。
  • 各テナント API を公開する手段: LoadBalancer Service、または本リファレンスのようにホストノード上の NodePort。
テナントごとに、2 種類のプライベートノード:
  • CPU ノード: SambaStack プラットフォーム用の、RDU を搭載しない x86_64 (Intel または AMD) サーバー。1 台を失ってもプラットフォームが存続できるよう少なくとも 2 台を用意し、SambaStack のオンプレミス要件に従ってサイジングしてください。
  • RDU ノード: モデルバンドル専用の、テナントの RDU サーバー。
すべてのプライベートノード (CPU・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> は環境に合わせて置き換えてください。
1

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 の証明書が自己署名の場合に指定します。ホスト名に信頼された証明書が設定されている場合は外してください。
2

テナントコントロールプレーンの作成

この設計の要となる設定は次のとおりです。
vcluster.yaml
ホストの CPU ノードプールに taint が設定されている場合は、対応する controlPlane.statefulSet.scheduling.tolerations を追加してください。追加しないと、コントロールプレーンの Pod は Pending のままになります。CoreDNS は、ステップ 6 で最初のテナント CPU ノードが参加してラベル付けされるまで Pending のままですが、これは想定どおりの動作です。
この kubeconfig には、テナントの cluster-admin クライアント証明書が含まれています。パスワードと同様に厳重に扱ってください。
3

RHEL 8.10 ノードの準備

すべての CPU ノードとすべての RDU ノード上で、root として実行します。まず cgroup v2 を確認します。出力が tmpfs の場合は、ここで作業を中止してください。
既存のコンテナランタイムを停止し、スワップを無効化し、カーネルモジュールと sysctl を読み込みます。/etc 配下のファイルにより、これらの設定は再起動後も維持されます。
4

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) と一致している必要があります。テナントをアップグレードする際は、新しいバンドルをビルドしてください。
5

ノードの参加

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 を追加してください。
6

ノードへのラベル付与

どのノードで何が動くかは、このラベルで決まります。CPU ノードにはプラットフォーム用のラベルを、RDU ノードには SambaStack の推論オペレーターが選択する RDU ラベルを付与します。
1 つのノードに両方のラベルを付けないでください。Pending だった CoreDNS は、CPU ノードにラベルが付くと、そのノード上で起動します。
7

テナントへの 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)
クイックスタートのノードラベル付与の手順はスキップしてください。ノードにはステップ 6 でラベルを付与済みです。 ストレージクラス。 SambaStack は独自の OpenEBS プロビジョナーをインストールし、Postgres のデータを 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 ノードを計画してください。
この間も、ゲートウェイ、UI、ログイン、Postgres、Redis、DNS は動作し続けます。CPU ノードをドレインする場合は 1 台ずつ、かつ他の CPU ノードが Ready の間だけ行ってください。

制限事項

  • 本リファレンスは、RHEL 8.10 のプライベートノードでのみ検証しています。RHEL 10 ノードでは検証していません。
  • RHEL 8.10 ノードには、ステップ 4 の RHEL 8 バンドルが必要です。テナントの Kubernetes をアップグレードするたびにバンドルを再ビルドし、先にテストノードで検証してください。
  • vCluster のノード間 VPN は、RHEL 8.10 ノードでは利用できません。本リファレンスでは使用していません。
  • join トークンには有効期限があります。ノードを追加するたびに、新しいトークンを発行してください。
  • テナント API は、ホストノードの 1 つの NodePort 上にあります。本番環境では、LoadBalancer Service または VIP を使用してください。
  • vCluster Platform は、無料プランの検証のために admin.loft.sh に到達できる必要があり、無料プランの CPU・GPU の上限が適用されます。
  • テナントコントロールプレーンの状態は、1 つのボリューム上にあります。本番環境ではバックアップを取るか、vCluster の高可用性構成を実行してください。

クリーンアップ

vCluster Platform は、他のテナントのために残ります。Platform も削除する場合は、helm uninstall loft -n vcluster-platform を実行してください。

参考情報