> ## Documentation Index
> Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading SambaStack

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.

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

<Tabs>
  <Tab title="SambaStack on-prem">
    On-prem installs use `helm upgrade` with the chart version and your existing values file.

    ## Prerequisites

    <CardGroup cols={2}>
      <Card title="GCP service account" icon="key">
        A valid key file with access to the SambaNova OCI registry.
      </Card>

      <Card title="gcloud CLI" icon="terminal">
        `gcloud` installed and configured on your local machine.
      </Card>

      <Card title="Helm CLI" icon="cube">
        `helm` installed and configured on your local machine.
      </Card>

      <Card title="Values file" icon="file-code">
        Your `sambastack.yaml` updated for the target version.
      </Card>
    </CardGroup>

    <Note icon="lock">
      For OCI registry path and credentials, see KB article **SambaStack OCI Registry Access Guide** at [support.sambanova.ai](https://support.sambanova.ai) or email [help@sambanova.ai](mailto:help@sambanova.ai).
    </Note>

    ***

    ## Upgrade steps

    <Steps>
      <Step title="Check current version and cluster health">
        Verify the currently installed chart version and confirm all pods are healthy before proceeding.

        ```bash theme={null}
        helm list -n sambastack
        ```

        Expected output:

        ```bash theme={null}
        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:

        ```bash theme={null}
        kubectl get pods -n sambastack
        ```

        <Warning>
          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.
        </Warning>

        <Note>
          Record the current version – you will need it if a rollback is required.
        </Note>
      </Step>

      <Step title="Authenticate with GCP">
        Activate your service account using its key file.

        ```bash theme={null}
        gcloud auth activate-service-account --key-file=<SERVICE_ACCOUNT_PATH>
        ```

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

      <Step title="List available versions (optional)">
        Browse available versions in the SambaNova OCI registry.

        ```bash theme={null}
        gcloud artifacts docker tags list <REGISTRY_PATH>
        ```

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

        <Tip>
          Skip this step if SambaNova has already provided the exact target version.
        </Tip>
      </Step>

      <Step title="Set the target version">
        Export the target version as an environment variable.

        ```bash theme={null}
        NEW_VERSION="<NEW_VERSION>"
        ```

        <Note>
          Replace `<NEW_VERSION>` with the actual version string, e.g. `1.5.2`.
        </Note>
      </Step>

      <Step title="Authenticate Helm with the OCI registry">
        Log in using your GCP access token.

        ```bash theme={null}
        gcloud auth print-access-token | helm registry login \
          -u oauth2accesstoken \
          --password-stdin <REGISTRY_HOST>
        ```

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

      <Step title="Upgrade sambastack-base">
        Upgrade the base Helm chart to the target version.

        ```bash theme={null}
        helm upgrade \
          --install \
          --create-namespace \
          --version $NEW_VERSION \
          --namespace sambastack \
          sambastack-base \
          oci://<REGISTRY_PATH>/sambastack-base
        ```

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

      <Step title="Update sambastack.yaml for the new version">
        Review the [SambaStack release notes](/en/release-notes/sambastack) for `<NEW_VERSION>` and apply any required configuration changes to `sambastack.yaml` before running the upgrade. New versions may add, rename, or remove fields.

        <Tip>
          Diff your current `sambastack.yaml` against the sample configuration in the release notes to identify any new required fields.
        </Tip>
      </Step>

      <Step title="Upgrade sambastack">
        Upgrade the main chart with your updated values file.

        ```bash theme={null}
        helm upgrade \
          --install \
          --create-namespace \
          --values sambastack.yaml \
          --version $NEW_VERSION \
          --namespace sambastack \
          sambastack \
          oci://<REGISTRY_PATH>/sambastack
        ```

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

      <Step title="Validate the upgrade">
        Confirm the release status and verify all pods are running.

        ```bash theme={null}
        helm status sambastack -n sambastack
        ```

        ```bash theme={null}
        kubectl get pods -n sambastack
        ```

        All pods should reach `Running` status within a few minutes.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SambaStack hosted">
    Hosted installs use an installer that watches a ConfigMap (typically named `sambastack`) containing your `sambastack.yaml` configuration.

    ## Prerequisites

    <CardGroup cols={3}>
      <Card title="Cluster access" icon="server">
        Kubernetes cluster access with appropriate permissions.
      </Card>

      <Card title="Target version" icon="tag">
        `<NEW_VERSION>` confirmed with your SambaNova representative.
      </Card>

      <Card title="Config backup" icon="floppy-disk">
        A backup of your current `sambastack.yaml` (recommended).
      </Card>
    </CardGroup>

    ***

    ## Upgrade steps

    <Steps>
      <Step title="Check current version">
        Verify the version currently running before making any changes.

        ```bash theme={null}
        kubectl describe configmap sambastack -n sambastack | grep version
        ```

        <Note>
          Record the current version – you will need it if a rollback is required.
        </Note>
      </Step>

      <Step title="Update the version in the ConfigMap">
        Set **only** the new version initially – avoid changing other sections until the upgrade completes.

        ```yaml sambastack-configmap.yaml theme={null}
        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: sambastack
          labels:
            sambastack-installer: "true"
        data:
          sambastack.yaml: |
            version: <NEW_VERSION>
        ```

        Apply the updated ConfigMap:

        ```bash theme={null}
        kubectl apply -f sambastack-configmap.yaml
        ```

        <Tip>
          Monitor installer logs in real time:

          ```bash theme={null}
          kubectl logs -n sambastack-installer -l sambanova.ai/app=sambastack-installer -f
          ```
        </Tip>
      </Step>

      <Step title="Validate the upgrade">
        Verify all pods are running in the target namespace.

        ```bash theme={null}
        kubectl get pods -n sambastack
        ```

        All pods should reach `Running` status within a few minutes.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Rollback

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

<Tabs>
  <Tab title="SambaStack on-prem">
    Re-run both `helm upgrade` commands using the previous version:

    ```bash theme={null}
    helm upgrade \
      --install \
      --create-namespace \
      --version <PREVIOUS_VERSION> \
      --namespace sambastack \
      sambastack-base \
      oci://<REGISTRY_PATH>/sambastack-base
    ```

    ```bash theme={null}
    helm upgrade \
      --install \
      --create-namespace \
      --values sambastack.yaml \
      --version <PREVIOUS_VERSION> \
      --namespace sambastack \
      sambastack \
      oci://<REGISTRY_PATH>/sambastack
    ```

    <Note>
      Ensure `sambastack.yaml` matches the configuration expected by `<PREVIOUS_VERSION>` before running.
    </Note>
  </Tab>

  <Tab title="SambaStack hosted">
    Edit your ConfigMap to set the previous version and reapply:

    ```yaml theme={null}
    data:
      sambastack.yaml: |
        version: <PREVIOUS_VERSION>
    ```

    ```bash theme={null}
    kubectl apply -f sambastack-configmap.yaml
    ```
  </Tab>
</Tabs>

<Warning>
  If rollback does not restore expected behavior, stop and contact SambaNova support before making further changes. See [Support](#support) below.
</Warning>

***

## Support

<CardGroup cols={2}>
  <Card title="Support portal" icon="desktop" href="https://support.sambanova.ai">
    Access KB articles and raise support tickets at support.sambanova.ai.
  </Card>

  <Card title="Email support" icon="envelope" href="mailto:help@sambanova.ai">
    Contact [help@sambanova.ai](mailto:help@sambanova.ai) for registry access or upgrade issues.
  </Card>
</CardGroup>