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.
Upgrade steps
Check current version and cluster health
Verify the currently installed chart version and confirm all pods are healthy before proceeding. 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_PAT H >
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
Log in using your GCP access token. gcloud auth print-access-token | helm registry login \ -u oauth2accesstoken \ --password-stdin < REGISTRY_HOS T >
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_PAT H > /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_PAT H > /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_VERSIO N > \ --namespace sambastack \ sambastack-base \ oci:// < REGISTRY_PAT H > /sambastack-base
helm upgrade \ --install \ --create-namespace \ --values sambastack.yaml \ --version < PREVIOUS_VERSIO N > \ --namespace sambastack \ sambastack \ oci:// < REGISTRY_PAT H > /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.
