SambaStack Upgrade - SambaNova Documentation

This guide covers how to safely upgrade SambaStack in both deployment types:

Hosted – kubectl / ConfigMap-driven installs where an installer watches a sambastack ConfigMap and reconciles the desired version automatically.
On-Prem – Helm-driven installs where you run helm upgrade directly against the SambaNova OCI registry using your own values file.

Each deployment type has its own prerequisites, upgrade steps, and validation procedure. Follow only the tab that matches your environment.

Before you upgrade – some version upgrades may require inference endpoints to restart or cause downtime. Contact your SambaNova representative before proceeding.

SambaStack on-prem
SambaStack hosted

On-prem installs use helm upgrade with the chart version and your existing values file.

Prerequisites

GCP service account

A valid key file with access to the SambaNova OCI registry.

gcloud CLI

gcloud installed and configured on your local machine.

Helm CLI

helm installed and configured on your local machine.

Values files

Your sambastack.yaml and models chart values file, updated for the target version.

For OCI registry path and credentials, see KB article SambaStack OCI Registry Access Guide at support.sambanova.ai or email help@sambanova.ai.

Upgrade steps

Check current version and cluster health

Verify the currently installed chart version and confirm all pods are healthy before proceeding.

helm list -n sambastack

Expected output:

NAME               NAMESPACE    REVISION  STATUS    CHART                   APP VERSION
sambastack         sambastack   1         deployed  sambastack-1.4.0        1.4.0
sambastack-base    sambastack   1         deployed  sambastack-base-1.4.0   1.4.0
sambastack-models  sambastack   1         deployed  sambastack-models-1.4.0 1.4.0

Then verify all pods are running:

kubectl get pods -n sambastack

Do not proceed if any pods are in a non-Running state. Upgrading a degraded cluster can make recovery harder. Resolve any existing issues first.

Record the current version – you will need it if a rollback is required.

Authenticate with GCP

Activate your service account using its key file.

gcloud auth activate-service-account --key-file=<SERVICE_ACCOUNT_PATH>

Replace <SERVICE_ACCOUNT_PATH> with the full path to your JSON key file, e.g. /home/user/sa-key.json.

List available versions (optional)

Browse available versions in the SambaNova OCI registry.

gcloud artifacts docker tags list <REGISTRY_PATH>

Replace <REGISTRY_PATH> with your OCI registry path, e.g. us-docker.pkg.dev/sambanova-registry/sambastack.

Skip this step if SambaNova has already provided the exact target version.

Set the target version

Export the target version as an environment variable.

NEW_VERSION="<NEW_VERSION>"

Replace <NEW_VERSION> with the actual version string, e.g. 1.5.2.

Authenticate Helm with the OCI registry

gcloud auth print-access-token | helm registry login \
  -u oauth2accesstoken \
  --password-stdin <REGISTRY_HOST>

Replace <REGISTRY_HOST> with your registry domain, e.g. us-docker.pkg.dev.

Upgrade sambastack-base

Upgrade the base Helm chart to the target version.

helm upgrade \
  --install \
  --create-namespace \
  --version $NEW_VERSION \
  --namespace sambastack \
  sambastack-base \
  oci://<REGISTRY_PATH>/sambastack-base

Replace <REGISTRY_PATH> with your OCI registry path, e.g. us-docker.pkg.dev/sambanova-registry/sambastack.

Update your values files for the new version

Review the SambaStack release notes for <NEW_VERSION> and apply any required configuration changes before running the upgrade. New versions may add, rename, or remove fields in either values file:

sambastack.yaml for the sambastack chart
the models chart values file for sambastack-models

Diff both files against the sample configuration in the release notes to identify any new required fields. See the SambaStack.yaml reference for which keys belong in which file.

Upgrade sambastack

Upgrade the main chart with your updated values file.

helm upgrade \
  --install \
  --create-namespace \
  --values sambastack.yaml \
  --version $NEW_VERSION \
  --namespace sambastack \
  sambastack \
  oci://<REGISTRY_PATH>/sambastack

Replace <REGISTRY_PATH> with your OCI registry path, e.g. us-docker.pkg.dev/sambanova-registry/sambastack.

Upgrade sambastack-models

Upgrade the models chart, which deploys the Model, bundle, and Pef resources. Run this after the main chart.

helm upgrade \
  --install \
  --create-namespace \
  --values models-values.yaml \
  --version $NEW_VERSION \
  --namespace sambastack \
  sambastack-models \
  oci://<REGISTRY_PATH>/sambastack-models

Replace <REGISTRY_PATH> with your OCI registry path, and point --values at your models chart values file.

Validate the upgrade

Confirm the release status and verify all pods are running.

helm status sambastack -n sambastack

kubectl get pods -n sambastack

All pods should reach Running status within a few minutes.

Hosted installs use an installer that watches a ConfigMap (typically named sambastack) containing your sambastack.yaml configuration.

Prerequisites

Cluster access

Kubernetes cluster access with appropriate permissions.

Target version

<NEW_VERSION> confirmed with your SambaNova representative.

Config backup

A backup of your current sambastack.yaml (recommended).

Upgrade steps

Check current version

Verify the version currently running before making any changes.

kubectl describe configmap sambastack -n sambastack | grep version

Record the current version – you will need it if a rollback is required.

Update the version in the ConfigMap

Set only the new version initially – avoid changing other sections until the upgrade completes.

sambastack-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: sambastack
  labels:
    sambastack-installer: "true"
data:
  sambastack.yaml: |
    version: <NEW_VERSION>

To pin the models chart to a different version than the one in sambastack.yaml, add a version key to the models.yaml section. It falls back to the sambastack.yaml version when unset.

Make sure the models chart version you pin is compatible with your infra chart version. SambaNova publishes the compatible version pairs.

Apply the updated ConfigMap:

kubectl apply -f sambastack-configmap.yaml

Monitor installer logs in real time:

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

Validate the upgrade

Verify all pods are running in the target namespace.

kubectl get pods -n sambastack

All pods should reach Running status within a few minutes.

Rollback

If you need to revert to a previous version, use the commands below with the version you recorded in Step 1.

SambaStack on-prem
SambaStack hosted

Re-run the helm upgrade commands using the previous version, in the same order:

helm upgrade \
  --install \
  --create-namespace \
  --version <PREVIOUS_VERSION> \
  --namespace sambastack \
  sambastack-base \
  oci://<REGISTRY_PATH>/sambastack-base

helm upgrade \
  --install \
  --create-namespace \
  --values sambastack.yaml \
  --version <PREVIOUS_VERSION> \
  --namespace sambastack \
  sambastack \
  oci://<REGISTRY_PATH>/sambastack

helm upgrade \
  --install \
  --create-namespace \
  --values models-values.yaml \
  --version <PREVIOUS_VERSION> \
  --namespace sambastack \
  sambastack-models \
  oci://<REGISTRY_PATH>/sambastack-models

Ensure both sambastack.yaml and your models chart values file match the configuration expected by <PREVIOUS_VERSION> before running.

Edit your ConfigMap to set the previous version and reapply:

data:
  sambastack.yaml: |
    version: <PREVIOUS_VERSION>

kubectl apply -f sambastack-configmap.yaml

If rollback does not restore expected behavior, stop and contact SambaNova support before making further changes. See Support below.

Support

Support portal

Access KB articles and raise support tickets at support.sambanova.ai.

Email support

Contact help@sambanova.ai for registry access or upgrade issues.

Getting Started

Service Administration

Hardware Administration

Reference Architecture

Resources

Upgrading SambaStack

Prerequisites

GCP service account

gcloud CLI

Helm CLI

Values files

Upgrade steps

Prerequisites

Cluster access

Target version

Config backup

Upgrade steps

Rollback

Support

Support portal

Email support

​Prerequisites

GCP service account

gcloud CLI

Helm CLI

Values files

​Upgrade steps

​Prerequisites

Cluster access

Target version

Config backup

​Upgrade steps

​Rollback

​Support

Support portal

Email support

Prerequisites

Upgrade steps

Prerequisites

Upgrade steps

Rollback

Support