> ## 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.

# SambaStack.yaml reference

> Configuration reference for the sambastack and sambastack-models Helm charts, covering ingress, TLS, high availability, service tiers, and model bundle configuration.

<Tabs>
  <Tab title="On-prem">
    ```yaml theme={}
    gateway:
      replicas: 3
      auth:
        enabled: true
        secretName: <oidc-auth secret name>
      ingress:
        hosts:
          - host: <api url>
            tlsSecretName: <k8s api secret name>
        annotations:
          nginx.ingress.kubernetes.io/backend-protocol: HTTP
          nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
          nginx.ingress.kubernetes.io/proxy-read-timeout: '600'
          nginx.ingress.kubernetes.io/proxy-body-size: 25m
          nginx.ingress.kubernetes.io/enable-cors: 'true'
          nginx.ingress.kubernetes.io/configuration-snippet: |
            proxy_set_header Authorization $http_authorization;
            limit_req zone=240_req_min_header burst=360 nodelay;
            limit_req_status 429;

    cloud-ui:
      ingress:
        hosts:
          - host: <ui url>
            tlsSecretName: <k8s api secret name>
        annotations:
          nginx.ingress.kubernetes.io/backend-protocol: HTTP
          nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
          nginx.ingress.kubernetes.io/proxy-body-size: 21m
          nginx.ingress.kubernetes.io/configuration-snippet: |
            proxy_set_header Authorization $http_authorization;
            limit_req zone=120_req_min_ip burst=240 nodelay;
            limit_req_status 429;

    auth-and-billing:
      admins:
      - temp-admin@cluster.local
      - example@example.com                # Email of lasting admin account
      pgSecretName: pg-credentials         # Only needed with a custom external postgres DB

    cloudnative-pg:
      enabled: false                       # Only needed with a custom external postgres DB

    serviceTiers:
      <Tier1>:                              # Custom service tier name
        - models:
            - gpt-oss-120b-8-32-64-128k
          queueDepth: 25                    # Queries to queue before returning busy
          qos: "free"                       # Usually matches service tier name
          maxNewTokens: 8192                # Fills in max_tokens when a request omits it
          maxNewTokensHard: 32768           # Ceiling no generation on this tier exceeds
          rates:
            - allowedRequests: 50
              periodSeconds: 60
      <Tier2>:                              # Tier that inherits from another
        inherits: <Tier1>
        overrides:
          - models:
              - gpt-oss-120b-8-32-64-128k
            queueDepth: 25
            qos: "free"
            contextGroups:                  # Per-context-length settings
              - contextLengths: ["32k"]     # Tighter bounds for 32k requests only
                queueDepth: 25
                maxNewTokens: 1024
                maxNewTokensHard: 4096
            rates:
              - allowedRequests: 100
                periodSeconds: 60

    global:
      extraEnv:								# This sets the node memory limit to 4TB
        - name: "DDR_PER_RDU_GB"
          value: "256"
    ```

    <Note>
      This reference uses `cd-dyt-gpt-oss-120b-8-32-64-128k` as the example model bundle. You can use any model bundle(s) you like in practice.
    </Note>

    Bundle and model configuration is not part of this file. It goes in a separate values file passed to the `sambastack-models` chart install:

    ```yaml models-values.yaml theme={}
    modelBundleSpecs:
      - name: cd-dyt-gpt-oss-120b-8-32-64-128k
    modelDeploymentSpecs:
      - name: cd-dyt-gpt-oss-120b-8-32-64-128k
        groups:
          - name: default
            minReplicas: 1
            qosList: [web, free]

    global:
      substitutions:                        # Only needed for NFS or air-gapped customers
        gs://<SAMBASTACK_ARTIFACTS_BUCKET>: nfs:///nfsdata
    ```

    See [Model configuration](#model-configuration) for the keys, [Quickstart - on-prem](/docs/en/v2.1.2/sambastack/getting-started/on-prem) for the corresponding `helm upgrade --install sambastack-models` step, and [Deploy a bundle](/docs/en/v2.1.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle) for the deployment workflow.
  </Tab>

  <Tab title="Hosted">
    ```yaml theme={}
    apiVersion: v1
    kind: ConfigMap
    metadata:
      annotations:
        serial: "1"
      name: sambastack
      labels:
        sambastack-installer: "true"
    data:
      sambastack.yaml: |
        version: <latest sambastack version>

    # API Configuration
        gateway:
          ingress:
            hosts:
              - host: api.example.com
                tlsSecretName: <name-for-tls>

    # UI Configuration
        cloud-ui:
          ingress:
            hosts:
            - host: ui.example.com
              tlsSecretName: <name-for-tls>

    # Auth and Billing Configuration
        auth-and-billing:
          admins:                             # Emails granted Admin UI access
          - example@example.com
          pgSecretName: pg-credentials        # Kubernetes secret with PostgreSQL credentials

    # Database Configuration
        cloudnative-pg:
          enabled: false                      # Disable in-cluster PostgreSQL

    # Model Bundle(s) Configuration
      models.yaml: |
        version: <models chart version>       # Optional; defaults to the sambastack.yaml version
        modelBundleSpecs:
        - name: cd-dyt-gpt-oss-120b-8-32-64-128k
        modelDeploymentSpecs:
        - name: cd-dyt-gpt-oss-120b-8-32-64-128k
          groups:
          - name: "default"
            minReplicas: 1
            qosList:
            - "web"
            - "free"
    ```

    <Note>
      Contact your SambaStack representative for the latest SambaStack version.
    </Note>

    The keys in the `models.yaml` section are passed verbatim to the `sambastack-models` release, which the installer deploys automatically. See [Models chart](/docs/en/v2.1.2/sambastack/service-administration/model-deployment/models-chart).
  </Tab>
</Tabs>

## **Configuration parameters**

### **gateway**

| **Parameter**                           | **Type** | **Description**                                                                          |
| :-------------------------------------- | :------- | :--------------------------------------------------------------------------------------- |
| `gateway.replicas`                      | integer  | API gateway replica count for high availability                                          |
| `gateway.auth.enabled`                  | boolean  | Enable built-in OIDC integration                                                         |
| `gateway.auth.secretName`               | string   | Name of Kubernetes Secret containing OIDC credentials. Leave empty for default auth mode |
| `gateway.ingress.hosts[].host`          | string   | Your API FQDN (e.g., `api.example.com`)                                                  |
| `gateway.ingress.hosts[].tlsSecretName` | string   | Kubernetes TLS secret name for the API host                                              |

### **cloud-ui (web UI)**

| **Parameter**                            | **Type** | **Description**                            |
| :--------------------------------------- | :------- | :----------------------------------------- |
| `cloud-ui.replicas`                      | integer  | UI replica count for high availability     |
| `cloud-ui.ingress.hosts[].host`          | string   | Your UI FQDN (e.g., `ui.example.com`)      |
| `cloud-ui.ingress.hosts[].tlsSecretName` | string   | Kubernetes TLS secret name for the UI host |

### **auth-and-billing**

| **Parameter**                   | **Type** | **Description**                                                                                                                                                                                       |
| :------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth-and-billing.admins`       | list     | Email addresses of users who can access the Admin UI                                                                                                                                                  |
| `auth-and-billing.replicas`     | integer  | Core control-plane service scaling                                                                                                                                                                    |
| `auth-and-billing.pgSecretName` | string   | Name of Kubernetes Secret containing external PostgreSQL connection details (`DB_HOST`, `DB_DATABASE`, `DB_USER`, `DB_PASSWD`) as base64-encoded data fields. Required when using external PostgreSQL |

<Warning>
  **`db-admin` was removed in v2.0.2.** Admin emails now belong under `auth-and-billing.admins`. A leftover top-level `db-admin:` block is **ignored without an error** — Helm renders and the upgrade succeeds, but nobody in that list gets Admin UI access. Move the list when you upgrade:

  ```yaml theme={}
  # Before (v1.x) — no longer has any effect
  db-admin:
    admins:
      - abc@example.com

  # After (v2.0.2+)
  auth-and-billing:
    admins:
      - abc@example.com
  ```
</Warning>

### **cloudnative-pg**

| **Parameter**            | **Type** | **Description**                                                                                              |
| :----------------------- | :------- | :----------------------------------------------------------------------------------------------------------- |
| `cloudnative-pg.enabled` | boolean  | `true` = deploy in-cluster PostgreSQL; `false` = use external PostgreSQL via `auth-and-billing.pgSecretName` |

### **serviceTiers**

Service tiers control which models a user can reach, their rate limits, and queue behavior. For the full field set and the inheritance model, see [Service tiers](/docs/en/v2.1.2/sambastack/service-administration/platform-admin/usergroup-management#service-tiers). The output token bounds are set here:

| **Parameter**                                            | **Type** | **Description**                                                                                                                 |
| :------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `serviceTiers.<tier>[].maxNewTokens`                     | integer  | Output tokens to use when a request on this tier omits `max_tokens`. Minimum `1`, unset by default                              |
| `serviceTiers.<tier>[].maxNewTokensHard`                 | integer  | Output tokens no generation on this tier may exceed, whether or not the client sent `max_tokens`. Minimum `1`, unset by default |
| `serviceTiers.<tier>[].contextGroups[].contextLengths`   | list     | Context lengths the group applies to, for example `["32k"]`. Required in a `contextGroups` entry                                |
| `serviceTiers.<tier>[].contextGroups[].queueDepth`       | integer  | Queue depth for this context group. Required in a `contextGroups` entry                                                         |
| `serviceTiers.<tier>[].contextGroups[].maxNewTokens`     | integer  | Overrides the tier's `maxNewTokens` for requests in this context group                                                          |
| `serviceTiers.<tier>[].contextGroups[].maxNewTokensHard` | integer  | Overrides the tier's `maxNewTokensHard` for requests in this context group                                                      |

Each field resolves independently from the narrowest level that sets it: the context group, then the tier, then [the model](/docs/en/v2.1.2/sambastack/service-administration/model-deployment/custom-resources/model). Left unset at every level, generation runs to a natural stop or the model's context window. See [Output token bounds](/docs/en/v2.1.2/sambastack/service-administration/platform-admin/usergroup-management#output-token-bounds) for how the two fields interact.

## **Model configuration**

Models, bundles, and PEFs are deployed by the [models chart](/docs/en/v2.1.2/sambastack/service-administration/model-deployment/models-chart) (`sambastack-models`), a separate Helm release from the `sambastack` chart. Its configuration reference lives on that page.

On hosted deployments, the models chart values live in a `models.yaml` section of the installer ConfigMap, alongside the `sambastack.yaml` section rather than inside it:

| **Parameter**             | **Type** | **Description**                                                                                                                                                                                                          |
| :------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models.yaml`             | string   | The models chart's values, passed verbatim by the sambastack-installer to the `sambastack-models` release. For the keys, see [Models chart](/docs/en/v2.1.2/sambastack/service-administration/model-deployment/models-chart). |
| `models.yaml` → `version` | string   | Pins the `sambastack-models` chart version independently of the `version` key in `sambastack.yaml`. Defaults to that version when unset.                                                                                 |

<Warning>
  When you pin the `version` key in `models.yaml`, make sure the models chart version you choose is compatible with your infra chart version. SambaNova publishes the compatible version pairs.
</Warning>

On-prem, the models chart values are a separate file passed to the `sambastack-models` install rather than a key in this file. See [Quickstart - on-prem](/docs/en/v2.1.2/sambastack/getting-started/on-prem).