メインコンテンツへスキップ
このセクションでは、構成準備、認証設定、デプロイメントの検証を通じて SambaStack をインストールし、インスタンスを効果的に管理できるようにする手順を説明します。

​
前提条件

SambaStack をインストールする前に、以下を準備してください:

​
sambastack.yaml のサンプル

次のサンプル sambastack.yaml ファイルを使用して、サービス階層 (service tier)、認証、オプション設定など、インスタンス構成を準備します。 このファイルでは、デプロイ後に使用するモデル (bundleDeploymentSpecs)、ユーザーグループごとのモデルアクセスおよびレート制限 (serviceTiers)、管理者設定 (db-admin) などを定義しています。 
apiVersion: v1
kind: ConfigMap
metadata:
  annotations:
    serial: "1"
  name: sambastack
  labels:
    sambastack-installer: "true"         # [REQUIRED] Tells the installer to use this config
data:
  sambastack.yaml: |                     # [REQUIRED] Installer looks for the file 'sambastack.yaml' 
    version: 0.3.263                     # [REQUIRED] Version of sambastack to install
    bundles:                             # [OPTIONAL] Static inference configuration
      bundleSpecs:                       #            The Bundles to allow. This will install both a BundleTemplate and
                                         #            a matching Bundle with the same that provides default checkpoints
                                         #            to the BundleTemplate. You can manually add additional Bundles
                                         #            for an installed BundleTemplate here to BYOC. The BYOC APIs will
                                         #            only be able to BYOC a BundleTemplate enabled here, so you can
                                         #            use this list to limit which model architectures are available.
                                         #
      - name: llama-4-medium             #            This serves Llama-4-Maverick-17B-128E-Instruct.
                                         #
      bundleDeploymentSpecs:             #            BundleDeployments to create (putting the model on a machine).
      - name: llama-4-medium             #            Name of the Bundle to deploy.
        groups:                          #            The deployments to create for this bundle.
        - name: "default"                #            Unique name for this deployment.
          minReplicas: 1                 #            Number of machines this BundleDeployment should run on.
          qosList:                       #            Different QOS levels to allow access to the BundleDeployment.
          - "web"
          - "free"
    db-admin:                            # Defining user id as admins with their email IDs
      admins:
        - abc@example.com
    serviceTiers:                        # [Optional] Configure serviceTiers
      <Tier1>:                           #     Name a custom service tier
      - models:                          #     List models allowed in the service tier
        - Llama-4-Maverick-17B-128E-Instruct
        queueDepth: 100                  #     Queries to queue before returning busy
        qos: "example"                   #     Quality-of-service, usually same as service tier name
        rates:                           #     Rate limit list
        - allowedRequests: 0
          periodSeconds: 30
      <Tier2>:                           #     Name a custom service tier that inherits another tier
        inherits: <Tier1>
        overrides:
        - models:
          - Llama-4-Maverick-17B-128E-Instruct
          queueDepth: 100
          qos: "example"
          rates:
          - allowedRequests: 2
            periodSeconds: 30

​
ステップ1: sambastack.yaml のインストール

SambaStack のインストールは SambaStack Installer により管理されます。Hosted デプロイメントでは既にクラスタ内で有効化されています。 インストーラーは ConfigMap として保存された sambastack.yaml を読み取り、設定を適用してインスタンスをセットアップします。

​
ファイルの準備

インスタンスの構成 (サービス階層、認証、オプション機能など) を定義します。 上記サンプルファイルを参考に、環境に合わせて作成してください。

​
設定の適用

kubectl apply -f <path-to-sambastack.yaml>
成功すると、以下のように表示されます: 
configmap/sambastack configured

​
動作確認 (Sanity Check)

  • インストーラーログを確認し、UI / API のドメイン名を取得します: 
    kubectl -n sambastack-installer logs -l sambanova.ai/app=sambastack-installer -f
    成功時の出力例: 
    NAME: sambastack
LAST DEPLOYED: Thu Sep 11 10:18:54 2025
NAMESPACE: default
STATUS: deployed
REVISION: 7
TEST SUITE: None
[INFO] (helm_upgrade_install) Upgraded/installed sambastack release
[INFO] (configure_default_ingress) UI Domain: ui-domain-example.sambanova.ai
[INFO] (configure_default_ingress) API Domain: api-domain-example.sambanova.ai
  • クラスタの Pod を確認します: 
    kubectl get pods

​
ステップ2: 認証設定とユーザー管理

認証の設定方法は2種類あります。

​
オプション1: SambaNova 提供の Keycloak 構成 (デフォルト)

SambaStack Hosted環境では、認証のために、SambaNova によりデフォルトの Keycloak インスタンスが提供されます。

​
重要事項とよくある問題

  • メールアドレス必須: メールアドレスのないユーザーはログインできません。
  • ユーザー名の一意性: ユーザー名の重複は許可されません。ユーザー名とメールアドレスを整合させてください。
  • パスワードの永続性: 初期パスワードは、一時的なものではなく恒久的な値を設定してください (再設定が必要な場合を除く)。
  • ブラウザに関する注意事項: Keycloak 管理 UI にポートフォワーディングでアクセスする際は、Chrome の使用を推奨します (セッション Cookie 関連の問題を回避するため)。

​
Keycloakへのログイン手順

  1. 管理者認証情報を取得します。
kubectl get secret keycloak-initial-admin -o go-template='username: {{.data.username | base64decode}} password: {{.data.password | base64decode}}'
出力例: 
username: admin  
password: <random-password>
  1. Keycloakサービスをポートフォワードします。
kubectl port-forward svc/keycloak-service 8080
  1. Chrome で http://localhost:8080 にアクセスし、取得した認証情報でログインします。
  2. ユーザー管理の詳細は Keycloak Server Administration Guide を参照してください。

​
オプション2: カスタム OIDC 設定の使用

独自の OIDC プロバイダーを使用する場合は、以下の手順に従って設定します。

​
必要な値の準備

取得元値
OIDCプロバイダーが提供する情報OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_REDIRECT_URI
任意に生成するランダム文字列JWT_SECRET_KEY
これらは環境変数として使用されます: OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_REDIRECT_URI, JWT_SECRET_KEY.
これらの値はプレーンテキストで指定した場合でも、アップロード時に自動的にbase64エンコードされます。

​
Kubernetes Secret の作成 (oidc_auth.yaml)

以下はカスタム OIDC プロバイダーを利用する例です。 
apiVersion: v1
kind: Secret
metadata:
  name: oidc-auth
stringData:
  OIDC_CLIENT_ID: "example"
  OIDC_CLIENT_SECRET: "example"
  OIDC_ISSUER_URL: "https://auth.example.com/""
  OIDC_REDIRECT_URI: "https://ui.example.com/web/auth/callback"
  JWT_SECRET_KEY: "example"

​
Secret オブジェクトの作成

このコマンドは指定した YAML ファイルを基に、Kubernetes 内に oidc-auth という名前の Secret オブジェクトを作成します。 
kubectl apply -f oidc_auth.yaml
#### sambastack.yaml の更新 以下の設定を sambastack.yaml に追加または更新します。 
data:
  sambastack.yaml:
    auth:
      authSecretName: oidc_auth

​
Secret の適用と確認

kubectl apply -f sambastack.yaml

kubectl get secret | grep oidc
出力例: 
oidc-auth                      Opaque           5          10s
sambastack-oidc-auth           Opaque           5          7m53s

​
ステップ3: SambaStack UIへのログインとAPI利用

  • インストーラーログからドメイン名を取得します (ステップ1を参照)。
  • 互換性の問題を回避するため、Google Chrome を使用して UI ドメインにアクセスします。
  • 認証フローに従い、発行済みの認証情報でログインします。
  • ログイン後、 API Keys ページに移動し、API キーの作成および管理を行います。

​
API呼び出しの作成と管理

デプロイメントにバンドルが含まれていない場合は、少なくとも 1 つのモデルをデプロイするように bundleSpecs および bundleDeploymentSpecs を指定して、 sambastack.yaml を更新してください。 以下はその設定例です。 sambastack.yaml の例 (抜粋) 
data:
  sambastack.yaml: |                     # [REQUIRED] Installer looks for the file 'sambastack.yaml' 
    version: 0.3.263                     # [REQUIRED] Version of sambastack to install
    bundles:                             # [OPTIONAL] Static inference configuration
      bundleSpecs:                       #            The Bundles to allow. This will install both a BundleTemplate and
                                         #            a matching Bundle with the same that provides default checkpoints
                                         #            to the BundleTemplate. You can manually add additional Bundles
                                         #            for an installed BundleTemplate here to BYOC. The BYOC APIs will
                                         #            only be able to BYOC a BundleTemplate enabled here, so you can
                                         #            use this list to limit which model architectures are available.
                                         #
      - name: llama-4-medium             #            This serves Llama-4-Maverick-17B-128E-Instruct.
                                         #
      bundleDeploymentSpecs:             #            BundleDeployments to create (putting the model on a machine).
      - name: llama-4-medium             #            Name of the Bundle to deploy.
        groups:                          #            The deployments to create for this bundle.
        - name: "default"                #            Unique name for this deployment.
          minReplicas: 1                 #            Number of machines this BundleDeployment should run on.
          qosList:                       #            Different QOS levels to allow access to the BundleDeployment.
          - "web"
          - "free"
sambastack.yaml において複数のバンドルを有効化する例: 複数のモデルをデプロイする場合は、bundleSpecs に複数の項目を追加し、各エントリに対して個別に bundleDeploymentSpecs を定義します。 以下の例では、llama-4-medium と qwen3-32b-whisper の2つのバンドルを同時にデプロイします。 
data:
  sambastack.yaml: |
    version: 0.3.263
    bundles:
      bundleSpecs:
        - name: llama-4-medium
        - name: qwen3-32b-whisper
      bundleDeploymentSpecs:
        - name: llama-4-medium
          groups:
            - name: "default"
              minReplicas: 1
              qosList:
                - "web"
                - "free"
        - name: qwen3-32b-whisper
          groups:
            - name: "default"
              minReplicas: 1
              qosList:
                - "web"
                - "free"
この設定により、複数のバンドルを同時に利用・デプロイでき、異なるモデルやワークロードを柔軟に処理することが可能になります。

​
API キーの作成と管理

  1. SambaStackのUIにログインします。
  2. API Keys ページに移動します。
  3. Create API Key をクリックします。
  4. 新しい API キーの名前を入力します。
  5. 生成されたキーを その場でコピーし、安全な場所に保管してください。生のキー値は一度しか表示されず、後から再取得することはできません。
API呼び出しの例については、SambaNovaの クイックスタートガイド を参照してください。
API キーの無効化や再発行を行う場合は、API Keysページから管理できます。

​
コマンドリファレンス表

タスクコマンド例
kubeconfig の設定export KUBECONFIG=<Path for kubeconfig file>
インストーラーログの確認とドメイン名取得kubectl -n sambastack-installer logs -l sambanova.ai/app=sambastack-installer -f
クラスタの Pod 確認kubectl get pods
ノード一覧の表示kubectl get nodes
マニフェストの適用・更新kubectl apply -f <sambastack.yaml>
適用済みマニフェストの確認kubectl get configmap sambastack -o yaml
Keycloak 管理者認証情報の取得kubectl get secret keycloak-initial-admin -o go-template='username: {{.data.username | base64decode}} \n password: {{.data.password | base64decode}}'
Keycloak への管理者アクセスkubectl port-forward svc/keycloak-service 8080