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 file

Your sambastack.yaml 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

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 sambastack.yaml for the new version

Review the SambaStack release notes for <NEW_VERSION> and apply any required configuration changes to sambastack.yaml before running the upgrade. New versions may add, rename, or remove fields.

Diff your current sambastack.yaml against the sample configuration in the release notes to identify any new required fields.

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.

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>

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 both helm upgrade commands using the previous version:

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

Ensure sambastack.yaml matches 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 file

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 file

​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