> ## 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 のアップグレード

本ガイドでは、以下の 2 種類のデプロイメントタイプについて、SambaStack を安全にアップグレードする手順を解説します。

* **Hosted (ホステッド)**: `kubectl` / ConfigMap 駆動のインストール。インストーラーが `sambastack` ConfigMap を監視し、指定されたバージョンへ自動的に調整 (reconcile) します。
* **On-Prem (オンプレミス)**: Helm 駆動のインストール。独自の values ファイルを使用して、SambaNova の OCI レジストリに対して `helm upgrade` を直接実行します。

デプロイメントタイプごとに、前提条件、アップグレード手順、検証手順が異なります。お使いの環境に対応するタブのみに従ってください。

<Warning>
  アップグレードの前に: バージョンによっては、アップグレードに伴い推論エンドポイントの再起動やダウンタイムが必要になる場合があります。作業を進める前に、SambaNova の担当者にお問い合わせください。
</Warning>

<Tabs>
  <Tab title="SambaStack オンプレミス">
    オンプレミスのインストールでは、チャートバージョンと既存の values ファイルを指定して `helm upgrade` を使用します。

    ## 前提条件

    <CardGroup cols={2}>
      <Card title="GCP サービスアカウント" icon="key">
        SambaNova OCI レジストリへのアクセス権を持つ有効なキーファイル。
      </Card>

      <Card title="gcloud CLI" icon="terminal">
        ローカルマシンに `gcloud` がインストールおよび設定済みであること。
      </Card>

      <Card title="Helm CLI" icon="cube">
        ローカルマシンに `helm` がインストールおよび設定済みであること。
      </Card>

      <Card title="values ファイル" icon="file-code">
        ターゲットバージョンに合わせて更新した `sambastack.yaml` と モデルチャートの values ファイル。
      </Card>
    </CardGroup>

    <Note icon="lock">
      OCI レジストリのパスと認証情報については、[support.sambanova.ai](https://support.sambanova.ai) の KB 記事 **SambaStack OCI Registry Access Guide** を参照するか、[help@sambanova.ai](mailto:help@sambanova.ai) までメールでお問い合わせください。
    </Note>

    ***

    ## アップグレード手順

    <Steps>
      <Step title="現在のバージョンとクラスターの状態の確認">
        作業を進める前に、現在インストールされているチャートバージョンを確認し、すべての Pod が正常であることを確認します。

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

        期待される出力:

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

        次に、すべての Pod が実行中であることを確認します。

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

        <Warning>
          `Running` 以外の状態の Pod がある場合は、先に進まないでください。劣化した状態のクラスターをアップグレードすると、復旧が難しくなる可能性があります。まず既存の問題を解決してください。
        </Warning>

        <Note>
          現在のバージョンを記録しておいてください。ロールバックが必要になった場合に使用します。
        </Note>
      </Step>

      <Step title="GCP での認証">
        キーファイルを使用してサービスアカウントを有効化します。

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

        <Note>
          `<SERVICE_ACCOUNT_PATH>` は、JSON キーファイルのフルパスに置き換えてください (例: `/home/user/sa-key.json`)。
        </Note>
      </Step>

      <Step title="利用可能なバージョンの一覧表示 (任意)">
        SambaNova OCI レジストリで利用可能なバージョンを確認します。

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

        <Note>
          `<REGISTRY_PATH>` は、お使いの OCI レジストリパスに置き換えてください (例: `us-docker.pkg.dev/sambanova-registry/sambastack`)。
        </Note>

        <Tip>
          SambaNova からターゲットバージョンが正確に伝えられている場合は、このステップをスキップしてください。
        </Tip>
      </Step>

      <Step title="ターゲットバージョンの設定">
        ターゲットバージョンを環境変数としてエクスポートします。

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

        <Note>
          `<NEW_VERSION>` は、実際のバージョン文字列に置き換えてください (例: `1.5.2`)。
        </Note>
      </Step>

      <Step title="OCI レジストリでの Helm の認証">
        GCP のアクセストークンを使用してログインします。

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

        <Note>
          `<REGISTRY_HOST>` は、お使いのレジストリドメインに置き換えてください (例: `us-docker.pkg.dev`)。
        </Note>
      </Step>

      <Step title="sambastack-base のアップグレード">
        base の Helm チャートをターゲットバージョンにアップグレードします。

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

        <Note>
          `<REGISTRY_PATH>` は、お使いの OCI レジストリパスに置き換えてください (例: `us-docker.pkg.dev/sambanova-registry/sambastack`)。
        </Note>
      </Step>

      <Step title="新バージョンに合わせた values ファイルの更新">
        `<NEW_VERSION>` の [SambaStack リリースノート](/docs/ja/release-notes/sambastack) を確認し、アップグレードを実行する前に、必要な設定変更を適用してください。新しいバージョンでは、どちらの values ファイルでも、フィールドの追加・名称変更・削除が行われる場合があります。

        * `sambastack` チャート用の `sambastack.yaml`
        * `sambastack-models` 用の モデルチャートの values ファイル

        <Tip>
          両方のファイルをリリースノートのサンプル設定と比較 (diff) して、新たに必要になったフィールドがないか確認してください。どのキーがどちらのファイルに属するかは、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml#モデル構成) をご覧ください。
        </Tip>
      </Step>

      <Step title="sambastack のアップグレード">
        更新した values ファイルを使用して、メインのチャートをアップグレードします。

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

        <Note>
          `<REGISTRY_PATH>` は、お使いの OCI レジストリパスに置き換えてください (例: `us-docker.pkg.dev/sambanova-registry/sambastack`)。
        </Note>
      </Step>

      <Step title="sambastack-models のアップグレード">
        `Model`・バンドル・`Pef` リソースをデプロイする [モデルチャート](/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/models-chart) をアップグレードします。これはメインのチャートの**後に**実行してください。

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

        <Note>
          `<REGISTRY_PATH>` はお使いの OCI レジストリパスに置き換え、`--values` には モデルチャートの values ファイルを指定してください。
        </Note>
      </Step>

      <Step title="アップグレードの検証">
        リリースのステータスを確認し、すべての Pod が実行中であることを確認します。

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

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

        数分以内に、すべての Pod が `Running` 状態になるはずです。
      </Step>
    </Steps>
  </Tab>

  <Tab title="SambaStack Hosted">
    Hosted のインストールでは、`sambastack.yaml` 設定を含む ConfigMap (通常は `sambastack` という名前) を監視するインストーラーを使用します。

    ## 前提条件

    <CardGroup cols={3}>
      <Card title="クラスターアクセス" icon="server">
        適切な権限を持つ Kubernetes クラスターへのアクセス。
      </Card>

      <Card title="ターゲットバージョン" icon="tag">
        SambaNova の担当者に確認済みの `<NEW_VERSION>`。
      </Card>

      <Card title="設定のバックアップ" icon="floppy-disk">
        現在の `sambastack.yaml` のバックアップ (推奨)。
      </Card>
    </CardGroup>

    ***

    ## アップグレード手順

    <Steps>
      <Step title="現在のバージョンの確認">
        変更を加える前に、現在実行中のバージョンを確認します。

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

        <Note>
          現在のバージョンを記録しておいてください。ロールバックが必要になった場合に使用します。
        </Note>
      </Step>

      <Step title="ConfigMap のバージョンの更新">
        最初は新しいバージョン**のみ**を設定し、アップグレードが完了するまで他のセクションは変更しないでください。

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

        <Tip>
          モデルチャートを `sambastack.yaml` とは異なるバージョンに固定するには、`models.yaml` セクションに `version` キーを追加します。未設定の場合は、`sambastack.yaml` のバージョンが使用されます。
        </Tip>

        <Warning>
          固定するモデルチャートのバージョンが、お使いのインフラチャートのバージョンと互換であることを確認してください。互換性のあるバージョンの組み合わせは SambaNova が公開しています。
        </Warning>

        更新した ConfigMap を適用します。

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

        <Tip>
          インストーラーログをリアルタイムで監視します。

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

      <Step title="アップグレードの検証">
        対象の名前空間で、すべての Pod が実行中であることを確認します。

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

        数分以内に、すべての Pod が `Running` 状態になるはずです。
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## ロールバック

以前のバージョンに戻す必要がある場合は、ステップ 1 で記録したバージョンを使用して、以下のコマンドを実行します。

<Tabs>
  <Tab title="SambaStack オンプレミス">
    以前のバージョンを指定して、`helm upgrade` コマンドを同じ順序で再実行します。

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

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

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

    <Note>
      実行前に、`sambastack.yaml` と モデルチャートの values ファイルの両方が、`<PREVIOUS_VERSION>` の想定する設定と一致していることを確認してください。
    </Note>
  </Tab>

  <Tab title="SambaStack Hosted">
    ConfigMap を編集して以前のバージョンを設定し、再適用します。

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

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

<Warning>
  ロールバックしても期待どおりの動作に戻らない場合は、それ以上の変更を行わず、SambaNova のサポート窓口にお問い合わせください。下記の [サポート](#サポート) をご覧ください。
</Warning>

***

## サポート

<CardGroup cols={2}>
  <Card title="サポートポータル" icon="desktop" href="https://support.sambanova.ai">
    support.sambanova.ai で、KB 記事の閲覧やサポートチケットの発行ができます。
  </Card>

  <Card title="メールサポート" icon="envelope" href="mailto:help@sambanova.ai">
    レジストリアクセスやアップグレードに関する問題は、[help@sambanova.ai](mailto:help@sambanova.ai) までお問い合わせください。
  </Card>
</CardGroup>