> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 共有ノード

> [!NOTE]
>
> vCluster と Envoy Gateway はサードパーティ製品です。SambaNova はこれらの保守・推奨・監査を行っていません。本リファレンスアーキテクチャは情報提供を目的としており、これらの製品の変更に伴い内容が古くなる可能性があります。

共有ノードモデルでは、テナントの RDU ノードはホストクラスターのメンバーのままです。各ノードを 1 つのテナント用にラベル付けすると、vCluster はテナントにそのノードだけを見せ、テナントの Pod をそこにだけ配置します。テナントのコントロールプレーンは、ホストの CPU ノードプール上の Pod として動作します。RDU ノードには何もインストールされません。

このモデルは、組織内の信頼できるテナントに使用してください。外部のテナントや信頼できないテナントには、[プライベートノード](https://docs.sambanova.ai/docs/ja/v2.3.2/sambastack/reference-architecture/multi-tenancy/private-nodes.md) を使用します。両モデルの比較は [概要](https://docs.sambanova.ai/docs/ja/v2.3.2/sambastack/reference-architecture/multi-tenancy/overview.md) をご参照ください。

> [!NOTE]
>
> **検証済みの構成:** SambaStack 2.3.2、RKE2 v1.35.5、vCluster Helm チャート 0.35.4 (オープンソース版イメージ)、テナント Kubernetes v1.35.0、Envoy Gateway v1.9.1。

## アーキテクチャ

```mermaid theme={}
graph TB
    accTitle: Shared-node tenant on a SambaStack host cluster
    accDescr: An operator reaches the tenant API through a TLS passthrough gateway on the host cluster. The tenant control plane runs as pods in a host namespace on the CPU node pool. The syncer copies tenant pods into that namespace and the host scheduler places them on the RDU node labeled for the tenant. Other RDU nodes are hidden from the tenant.

    OP["Operator<br/><small>kubectl · tenant1-api.example.com:30843</small>"]

    subgraph HOST["Host cluster"]
        GW["TLS passthrough gateway<br/><small>installed once · routes by SNI hostname</small>"]
        subgraph NS["Namespace vcluster-tenant1 · CPU node pool"]
            CP["Tenant control plane<br/><small>API server · syncer · controller manager · etcd</small>"]
        end
        subgraph RDU["RDU node · label vcluster=tenant1"]
            PODS["Tenant pods<br/><small>copied by the syncer · placed by the host scheduler</small>"]
        end
        OTHER["Other RDU nodes<br/><small>not visible to the tenant</small>"]
    end

    OP -->|"HTTPS"| GW
    GW -->|"TLSRoute for the tenant hostname"| CP
    CP -->|"pods synced to the host namespace"| PODS

    classDef host fill:#eef2f7,stroke:#8aa0bd,color:#1a2b45;
    classDef tenant fill:#cfe2f3,stroke:#2f6fb0,color:#0d2c4d,stroke-width:2px;
    class GW,OTHER,RDU,HOST host;
    class CP,PODS,NS tenant;
```

各要素は次のように連携します。

1. **確保。** ホストの RDU ノードに `vcluster=tenant1` のラベルを付与します。テナントのノード同期セレクタがこのラベルに一致するため、テナントには自分のノードだけが見えます。また syncer は、ホストへコピーするすべての Pod に同じノードセレクタを設定します。
2. **制御トラフィック。** `kubectl` は、ゲートウェイの NodePort 上のテナントホスト名に接続します。ゲートウェイは SNI のホスト名を読み取り、接続を暗号化されたままテナントの API サーバーの Service に引き渡します。テナントの API 証明書には、このホスト名が含まれています。
3. **Pod。** テナントは、自身の API サーバー内で Pod を作成します。syncer はそれらを、名前を書き換えたうえでホストの Namespace `vcluster-tenant1` にコピーします。テナント自身のスケジューラーは無効化されているため、配置はホストのスケジューラーが行います。
4. **ログと exec。** vCluster の syncer が、これらの要求を同期済み Pod に対するホスト API サーバーへの要求として転送します。ノード上のエージェントは不要です。
5. **Pod ネットワーク。** テナントの Pod は、ホストの CNI と、ホストの Pod CIDR・Service CIDR を使用します。
6. **アプリケーショントラフィック。** テナントの Ingress オブジェクトはホストに同期され、ホストの ingress コントローラーがそれらを処理します。

## 前提条件

ホストクラスター側 (セットアップは 1 回のみ):

* SambaStack の [オンプレミス要件](https://docs.sambanova.ai/docs/ja/v2.3.2/sambastack/getting-started/on-prem.md#前提条件) を満たすホストクラスター。RDU ノードには、同ガイドの説明どおり `snRduArch=sn40-16` のラベルが付与済みであること。
* テナントのコントロールプレーン用に、`control-plane=shared` のラベルを付けた CPU ノードプール。これがないと、テナントの API サーバーと etcd の Pod は `Pending` のままになります。
* テナントのコントロールプレーンの状態を保存するストレージクラス。本リファレンスでは `openebs-hostpath` を使用します。
* TLS を終端せずに、SNI のホスト名で TLS をルーティングできるゲートウェイまたはロードバランサー。本リファレンスでは Envoy Gateway を使用します。パススルーモードの NGINX や HAProxy でも構いません。
* ゲートウェイに解決される、テナントごとの DNS 名 (例: `tenant1-api.example.com`)。

テナントごと:

* `Ready` 状態で、他のテナント用にラベル付けされていない RDU ワーカーノード 1 台以上。
* テナントの SambaStack API と UI 用の、一意のホスト名と TLS 証明書 (オンプレミス要件と同様)。

オペレーターのマシン上: `kubectl`、`helm` v3.19 以上、および [vCluster CLI](https://www.vcluster.com/docs/vcluster/deploy/control-plane/kubernetes-pod/basics)。

## コンポーネント

| レイヤー | コンポーネント | 提供元 | 稼働場所 |
| :- | :- | :- | :- |
| kubelet、コンテナランタイム、CNI、kube-proxy | RKE2 | ホストクラスター | RDU ノード |
| テナント Pod のスケジューラー | kube-scheduler | ホストクラスター | ホストのコントロールプレーン |
| RDU ノードのソフトウェアとラベル | SambaStack のホストインストール | ホストクラスター | RDU ノード |
| テナントコントロールプレーン | API サーバー、コントローラーマネージャー、syncer、etcd | vCluster チャート | ホストの Namespace `vcluster-tenant1` (CPU ノードプール) |
| テナント DNS | CoreDNS | vCluster チャート | テナントの RDU ノード上の同期済み Pod |
| テナント API の入口 | Envoy Gateway、`Gateway`、`TLSRoute` | 利用者 (ホストごとに 1 回) | ホスト |
| テナントアプリの ingress | ホストの ingress コントローラー (Ingress 同期経由) | ホストクラスター | ホスト |
| SambaStack | `sambastack-base`、`sambastack`、`sambastack-models` | 利用者 (テナントごと) | テナント (RDU ノードに同期) |

## テナントのセットアップ

特に記載がない限り、コマンドはホストクラスターに対して実行します。`tenant1`、`vcluster-tenant1`、`tenant1-api.example.com`、`<rdu-node>` はテナントの値に置き換えてください。

> [!NOTE]
>
> Envoy Gateway は本リファレンスの検証に使用したゲートウェイであり、必須ではありません。TLS を終端せずに SNI のホスト名でルーティングできるゲートウェイまたはロードバランサーであれば、代わりに使用できます。ステップ 1 と 2 は Envoy Gateway に固有の手順で、ステップ 4 の `controlPlane.tlsRoute` は Gateway API の `TLSRoute` を作成します。Gateway API を実装していないゲートウェイを使う場合は、`tlsRoute` を省略し、そのゲートウェイ自身の設定で、テナントのホスト名を `tenant1` Service のポート 443 にルーティングしてください。

### 1. ゲートウェイのインストール (ホストごとに 1 回)

```shellscript theme={}
helm upgrade --install envoy-gateway oci://docker.io/envoyproxy/gateway-helm \
  --version v1.9.1 \
  --namespace envoy-gateway-system --create-namespace
kubectl wait -n envoy-gateway-system deploy/envoy-gateway --for=condition=Available --timeout=5m
```

### 2. TLS パススルーリスナーの作成 (ホストごとに 1 回)

パススルーモードのリスナーをポート 8443 に 1 つ作成し、NodePort 30843 として公開します。すべてのテナント API がこのリスナーを共有し、ホスト名でルーティングされます。

```yaml gateway.yaml theme={}
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: envoy-gateway
  namespace: envoy-gateway-system
spec:
  gatewayClassName: envoy
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: envoy-gateway-proxy-config
  listeners:
    - name: vcluster-api
      protocol: TLS
      port: 8443
      tls:
        mode: Passthrough
      allowedRoutes:
        namespaces:
          from: All
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: envoy-gateway-proxy-config
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: NodePort
        externalTrafficPolicy: Cluster
        patch:
          type: StrategicMerge
          value:
            spec:
              ports:
                - name: vcluster-api
                  port: 8443
                  targetPort: 8443
                  nodePort: 30843
                  protocol: TCP
```

```shellscript theme={}
kubectl apply -f gateway.yaml
```

### 3. テナントの RDU ノードへのラベル付与

```shellscript theme={}
# Confirm the node is Ready, a worker, and not labeled for another tenant
kubectl get node <rdu-node> --show-labels | tr ',' '\n' | grep -E 'node-role|vcluster|snRduArch'

# Claim it for the tenant
kubectl label node <rdu-node> vcluster=tenant1 --overwrite

# Verify the tenant's nodes and the control plane pool
kubectl get nodes -l vcluster=tenant1
kubectl get nodes -l control-plane=shared
```

### 4. テナントの vCluster values の作成

この設計の要となる設定は次のとおりです。

| 設定 | 値 | 理由 |
| :- | :- | :- |
| `controlPlane.proxy.extraSANs` | `tenant1-api.example.com` | API 証明書がテナントのホスト名に対して有効になります |
| `controlPlane.tlsRoute` | ホスト名 `tenant1-api.example.com`、親 `envoy-gateway` | ゲートウェイがこのホスト名をこのテナントにルーティングします |
| `controlPlane.statefulSet.scheduling.nodeSelector` | `control-plane: shared` | API サーバーと etcd は、RDU ノードではなく CPU プールで動作します |
| `controlPlane.distro.k8s.scheduler.enabled` | `false` | 同期済み Pod はホストのスケジューラーが配置します |
| `controlPlane.coredns.deployment.nodeSelector` | `vcluster: tenant1` | テナントの DNS はテナントのノードで動作します |
| `sync.fromHost.nodes.selector.labels` | `vcluster: tenant1` | テナントにはこのラベルを持つノードだけが見え、同期済み Pod にも同じノードセレクタが設定されます |
| `sync.fromHost.nodes.syncBackChanges` | `false` | テナントは、自身の `vcluster` ラベルを含め、ホストノードのラベルや taint を編集できません。下記の警告をご参照ください |
| `sync.toHost.ingresses` | `true` | テナントの Ingress はホストの ingress コントローラーが処理します |

```yaml vcluster.yaml theme={}
controlPlane:
  proxy:
    extraSANs:
      - tenant1-api.example.com
      - tenant1.vcluster-tenant1.svc.cluster.local
  tlsRoute:
    enabled: true
    host: tenant1-api.example.com
    parentRefs:
      - name: envoy-gateway
        namespace: envoy-gateway-system
  statefulSet:
    highAvailability:
      replicas: 1
    image:
      registry: ghcr.io
      repository: loft-sh/vcluster-oss
    persistence:
      volumeClaim:
        enabled: true
        retentionPolicy: Delete
        storageClass: openebs-hostpath
    scheduling:
      nodeSelector:
        control-plane: shared
      podManagementPolicy: Parallel
      tolerations:
        - operator: Exists
  backingStore:
    etcd:
      deploy:
        enabled: true
        statefulSet:
          highAvailability:
            replicas: 1
          persistence:
            volumeClaim:
              accessModes: [ReadWriteOnce]
              enabled: true
              retentionPolicy: Delete
              size: 10Gi
              storageClass: openebs-hostpath
          scheduling:
            nodeSelector:
              control-plane: shared
            podManagementPolicy: Parallel
            tolerations:
              - operator: Exists
  coredns:
    enabled: true
    deployment:
      nodeSelector:
        vcluster: tenant1
      replicas: 1
  distro:
    k8s:
      enabled: true
      image:
        registry: ghcr.io
        repository: loft-sh/kubernetes
        tag: v1.35.0
      apiServer:
        enabled: true
        extraArgs:
          - --enable-admission-plugins=PodNodeSelector,PodTolerationRestriction
      controllerManager:
        enabled: true
      scheduler:
        enabled: false
networking:
  advanced:
    fallbackHostCluster: true
sync:
  fromHost:
    csiDrivers: {enabled: auto}
    csiNodes: {enabled: auto}
    csiStorageCapacities: {enabled: auto}
    events: {enabled: true}
    ingressClasses: {enabled: false}
    storageClasses: {enabled: auto}
    nodes:
      enabled: true
      clearImageStatus: false
      syncBackChanges: false
      selector:
        all: false
        labels:
          vcluster: tenant1
  toHost:
    configMaps: {all: false, enabled: true}
    endpoints: {enabled: true}
    ingresses: {enabled: true}
    networkPolicies: {enabled: false}
    persistentVolumeClaims: {enabled: true}
    persistentVolumes: {enabled: false}
    podDisruptionBudgets: {enabled: false}
    priorityClasses: {enabled: false}
    secrets: {all: false, enabled: true}
    serviceAccounts: {enabled: false}
    services: {enabled: true}
    storageClasses: {enabled: true}
    pods:
      enabled: true
      rewriteHosts:
        enabled: true
```

> [!NOTE]
>
> `PodNodeSelector` と `PodTolerationRestriction` を使うと、Namespace のアノテーションを通じて、テナントの Namespace を特定のノードや toleration に固定できます。これらは任意です。ノード同期セレクタだけでも、テナントの Pod はラベル付きノードに限定されます。

> [!WARNING]
>
> テナントの内側からノードにラベルを付与するツール (たとえばランタイムのローリングアップグレードをノード単位で進めるもの) を使うには、`syncBackChanges: true` が必要です。ただしこの設定を有効にすると、テナントの管理者は、自身を閉じ込めている `vcluster` ラベルを含め、自身のホストノードの任意のラベルや taint を変更・削除できるようになります。自身のノードの管理を任せられる、信頼できるテナントに限って有効化し、テナントの cluster-admin 権限の kubeconfig はプラットフォームチームが保持してください。

### 5. テナントのインストール

```shellscript theme={}
helm repo add loft-sh https://charts.loft.sh && helm repo update

helm upgrade --install tenant1 loft-sh/vcluster \
  --version 0.35.4 \
  --namespace vcluster-tenant1 --create-namespace \
  -f vcluster.yaml

kubectl -n vcluster-tenant1 get pods -w
```

最初に `tenant1-etcd-0` が起動します。API サーバーと syncer を実行する `tenant1-0` は、インストールから 1 分ほどで `Running` になります。

### 6. DNS の作成と接続

`tenant1-api.example.com` を、ホストノードの IP またはその前段の VIP (仮想 IP) に解決する DNS レコードを作成します。次に、ゲートウェイの NodePort を指すテナント kubeconfig を書き出します。

```shellscript theme={}
vcluster connect tenant1 -n vcluster-tenant1 --print \
  --server https://tenant1-api.example.com:30843 > tenant1.kubeconfig

export KUBECONFIG=tenant1.kubeconfig
kubectl get nodes
```

`kubectl get nodes` は、`vcluster=tenant1` のラベルが付いたノードだけを返します。

> [!WARNING]
>
> この kubeconfig には、テナントの cluster-admin クライアント証明書が含まれています。パスワードと同様に厳重に扱ってください。ホストクラスターにアクセスできる人は誰でも、同じコマンドで kubeconfig を生成できます。

## 動作確認

テナント側から:

```shellscript theme={}
export KUBECONFIG=tenant1.kubeconfig
kubectl get nodes -o wide          # only the tenant's labeled nodes
kubectl -n kube-system get pods     # CoreDNS, scheduled on the tenant's node
```

ホスト側から:

```shellscript theme={}
unset KUBECONFIG
kubectl -n vcluster-tenant1 get pods -o wide
```

ホストの Namespace には、CPU プール上のコントロールプレーン Pod と、ラベル付き RDU ノード上の同期済みテナント Pod (名前は書き換え済み) が表示されます。

## テナントへの SambaStack のインストール

テナントの kubeconfig を使い (`export KUBECONFIG=tenant1.kubeconfig`)、標準の [オンプレミスクイックスタート](https://docs.sambanova.ai/docs/ja/v2.3.2/sambastack/getting-started/on-prem.md) に従って SambaStack をインストールします。通常のインストールと異なるのは、次の 2 点だけです。

* **クイックスタートのノードラベル付与の手順はスキップします。** `snRduArch=sn40-16` のラベルはホスト側で設定済みであり、ノード同期を通じてテナントに届きます。
* **Ingress と DNS。** テナントの Ingress オブジェクトはホストに同期され、ホストの ingress コントローラーが処理します。テナントの API と UI のホスト名はホストの ingress に向け、テナント間で一意に保ってください。クイックスタートの要件どおり、これらのホスト名はテナントの内側からも名前解決できる必要があり、TLS 証明書は信頼された認証局 (CA) が発行したものである必要があります。

ホスト側からは、テナントの Pod は名前が書き換えられた状態で `vcluster-tenant1` に表示され、すべてテナントのラベル付きノード上で動作しています (`kubectl -n vcluster-tenant1 get pods -o wide`)。

## 制限事項

* `vcluster=tenant1` ラベルはスケジューリングルールであり、セキュリティ境界ではありません。自身の仮想クラスターへの cluster-admin アクセス権を持つテナントは、ホストのカーネル・CNI・kubelet を共有します。そのようなテナントには、[プライベートノード](https://docs.sambanova.ai/docs/ja/v2.3.2/sambastack/reference-architecture/multi-tenancy/private-nodes.md) を使用してください。
* SambaStack のプラットフォームサービスはテナントの RDU ノード上で動作するため、それらのノードのメンテナンス中は、テナントの API・UI・ログインが中断されます。両者を分離するには、専用の CPU ノードを使う [プライベートノード](https://docs.sambanova.ai/docs/ja/v2.3.2/sambastack/reference-architecture/multi-tenancy/private-nodes.md) を使用してください。
* ホスト管理者からは、ホストの Namespace 内にテナントの Pod が見えます。また、監視エージェントなどのホストの DaemonSet は、テナントのノード上でも動作します。
* `syncBackChanges: true` にすると、テナントの管理者は、自身のホストノードのラベルと taint を編集できます。本リファレンスでは `false` に設定しています。values のステップにある警告をご参照ください。
* テナントの Pod は、ホストの Pod ネットワークを共有します。テナント間のトラフィックを制限するには、各テナントのホスト側 Namespace に `NetworkPolicy` リソースを適用するか、`sync.toHost.networkPolicies` を有効にしてテナント自身に管理させてください。
* 本リファレンスでは、API サーバーと etcd をそれぞれ 1 レプリカで、ホストパスのストレージ上で実行します。本番環境では、`highAvailability.replicas` を増やし、etcd のボリュームをバックアップしてください。
* テナント API には、1 つのホストノード IP 上の 1 つの NodePort を通じて到達します。本番環境では、ホストノードの前段に VIP またはロードバランサーを配置してください。

## クリーンアップ

```shellscript theme={}
# Tenant: remove SambaStack first
export KUBECONFIG=tenant1.kubeconfig
helm uninstall sambastack-models sambastack sambastack-base -n sambastack

# Host: remove the tenant and release the node
unset KUBECONFIG
helm uninstall tenant1 -n vcluster-tenant1
kubectl delete namespace vcluster-tenant1
kubectl label node <rdu-node> vcluster-
```

`retentionPolicy: Delete` を設定しているため、コントロールプレーンのボリュームとテナントのすべての状態は、Helm リリースと一緒に削除されます。ゲートウェイは他のテナントのために残ります。

## 参考情報

* [vCluster: ホストからのノード同期](https://www.vcluster.com/docs/vcluster/configure/vcluster-yaml/sync/from-host/nodes)（英語）
* [vCluster プロダクションガイド: ワーカーノードモデルの選択](https://www.vcluster.com/docs/vcluster/production-guide/choose-worker-node-model)（英語）
* [Envoy Gateway: TLS パススルー](https://gateway.envoyproxy.io/docs/tasks/security/tls-passthrough/)（英語）
