Installation

This section guides you through installing SambaStack by preparing your configuration, setting up authentication options, and verifying successful deployment so you can start managing and using your instance effectively.

Prerequisites

Before proceeding with the installation:

Install Kubectl on your system. See Install Tools.
Configure valid Kubeconfig credentials. If not, see
Kubeconfig credentials

Sample sambastack.yaml

See the sample sambastack.yaml file to help you prepare your instance configuration, including service tiers, authentication, and optional settings. This file shows a model to use after deployment (bundleDeploymentSpecs), defines service tiers for rate limits and model access for user groups (serviceTiers), and configures admin settings (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.
                                         #            All options at: https://github.com/sambanova/fast-coe/blob/main/helm/values.yaml
                                         #
      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

Step 1: Install SambaStack.yaml

The SambaStack installation is managed through the SambaStack Installer, which is already enabled in the cluster for Hosted deployments. The Installer reads the sambastack.yaml configuration file stored as a ConfigMap and applies it to set up your instance.

Prepare your sambastack.yaml file

The file defines the configuration for your instance (e.g., service tiers, authentication, optional features). Use the sample file above as a reference when creating your own.

Apply the configuration

kubectl apply -f <path-to-sambastack.yaml>

If successful, you will see

configmap/sambastack configured

Sanity checks

Check installer logs and retrieve UI/API domain names with:

kubectl -n sambastack-installer logs -l sambanova.ai/app=sambastack-installer -f

If successful, you will see

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-sambastack-dev-4.sambanova.ai
[INFO] (configure_default_ingress) API Domain: api-sambastack-dev-4.sambanova.ai

Verify cluster pods
```
kubectl get pods
```

Step 2: Auth Setup and User Management

You have two options for authentication setup:

Option 1: Custom OIDC Configuration

To use your own OIDC provider:

Gather required values

Client ID
Client Secret
Issuer URL
Redirect URI
JWT Secret

These correspond to environment variables: OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_REDIRECT_URI, and JWT_SECRET_KEY.

Values will be base64-encoded during upload, even if provided as plain text.

Create Kubernetes Secret (`oidc_auth.yaml`)

See optional example for using custom OIDC provider.

cat << EOF | kubectl apply -f -
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"
EOF

Update `sambastack.yaml`

Add or update the following config data:

data:
  sambastack.yaml:
    auth:
      authSecretName: oidc_auth.yaml

Apply the secret:

kubectl apply -f sambastack.yaml

Verify secret applied:

kubectl get secret | grep oidc

Option 2: Sambanova Provided Keycloak Configuration (default)

For hosted SambaStack, Sambanova provides Keycloak by default for authentication workflows.

Key considerations and common issues

Email is required: Users without an email cannot log in.
Unique usernames: Duplicate usernames are disallowed; keep username and email aligned.
Permanent passwords: Initial passwords should not be temporary unless a user reset is desired.
Browser tip: Use Chrome for Keycloak admin UI when port-forwarding to avoid session cookie issues.

Retrieve admin credentials:

kubectl get secret keycloak-initial-admin -o go-template='username: {{.data.username | base64decode}} password: {{.data.password | base64decode}}'

Sample output

username: temp-admin  
password: aaa5b6776d484b82953423a5a75b53dd%

Port-forward Keycloak service
```
kubectl port-forward svc/keycloak-service 8080
```
- Access via Chrome at http://localhost:8080 and log in using the retrieved credentials.
Manage users by following the Keycloak Server Administration Guide.

Step 3: Logging into SambaStack UI and Making API Calls

Obtain the domain names from the installer logs (see Step 1)
Access the UI domain using Google Chrome to avoid compatibility issues.
Log in using your credentials via the authentication flow.
After login, navigate to the API Keys page to create and manage API keys.

Creating API Keys and Making API Calls

If your deployment does not include bundles, update your sambastack.yaml to deploy at least one model as shown in the sample file, specifying models in bundleSpecs and bundleDeploymentSpecs. Example snippet from sambastack.yaml:

data:
sambastack.yaml: |
version: 0.3.263
bundles:
bundleSpecs:
- name: llama-4-medium
bundleDeploymentSpecs:
- name: llama-4-medium
groups:
- name: default
minReplicas: 1
qosList:
- web
- free

How to create and manage API keys

Log in → API Keys page → Create API Key → Name it → Copy and save immediately (raw key visible only once).
Use the SambaNova Quickstart guide for API call examples.
To revoke or regenerate keys, manage them from the API Keys page.

Command Reference Table

Task	Sambastack Hosted / On Prem / Both	Example Command
Set kubeconfig	Both	`export KUBECONFIG= <Path for kubeconfig file>`
Check installer logs and Get domain names	Both	`kubectl -n sambastack-installer logs -l sambanova.ai/app=sambastack-installer -f`
Verify cluster pods	Both	`kubectl get pods`
List nodes	Both	`kubectl get nodes`
Identify RDU node and the internal cluster name	On Prem	`kubectl get nodes -L vlcuster`
Apply / Update manifest	Both	`kubectl apply -f <sambastack.yaml>`
View Applied manifest	Both	`kubectl get configmap sambastack -o yaml`
Retrieve Keycloak Admin credentials	Both	`kubectl get secret keycloak-initial-admin -o go-template='username: {{.data.username \| base64decode}} \n password: {{.data.password \| base64decode}}'`
Access keycloak as an Admin	Both	`kubectl port-forward svc/keycloak-service 8080`

Get started

Features

Model deployment

Prerequisites

Sample sambastack.yaml

Step 1: Install SambaStack.yaml

Prepare your sambastack.yaml file

Apply the configuration

Sanity checks

Step 2: Auth Setup and User Management

Option 1: Custom OIDC Configuration

Gather required values

Create Kubernetes Secret (`oidc_auth.yaml`)

Update `sambastack.yaml`

Option 2: Sambanova Provided Keycloak Configuration (default)

Key considerations and common issues

Step 3: Logging into SambaStack UI and Making API Calls

Creating API Keys and Making API Calls

How to create and manage API keys

Command Reference Table

Get started

Features

Model deployment

​Prerequisites

​Sample sambastack.yaml

​Step 1: Install SambaStack.yaml

​Prepare your sambastack.yaml file

​Apply the configuration

​Sanity checks

​Step 2: Auth Setup and User Management

​Option 1: Custom OIDC Configuration

​Gather required values

​Create Kubernetes Secret (oidc_auth.yaml)

​Update sambastack.yaml

​Option 2: Sambanova Provided Keycloak Configuration (default)

​Key considerations and common issues

​Steps to login to Keycloak:

​Step 3: Logging into SambaStack UI and Making API Calls

​Creating API Keys and Making API Calls

​How to create and manage API keys

​Command Reference Table

Prerequisites

Sample sambastack.yaml

Step 1: Install SambaStack.yaml

Prepare your sambastack.yaml file

Apply the configuration

Sanity checks

Step 2: Auth Setup and User Management

Option 1: Custom OIDC Configuration

Gather required values

Create Kubernetes Secret (`oidc_auth.yaml`)

Update `sambastack.yaml`

Option 2: Sambanova Provided Keycloak Configuration (default)

Key considerations and common issues

Steps to login to Keycloak:

Step 3: Logging into SambaStack UI and Making API Calls

Creating API Keys and Making API Calls

How to create and manage API keys

Command Reference Table