# バージョンアップガイド

AGENTIC STAR マーケットプレイス版の Kubernetes アプリケーションをアップデートする手順を解説します。

> **注意**
>
> 本機能（管理画面からのセルフアップデート）は **v2.3.0 以降** でご利用ください。v2.3.0 より前のバージョンからアップデートする場合は、手動アップデート（方法B）を実施してください。

> **注記**
>
> AGENTIC STAR Basic の環境は、v2.x の範囲で更新できます。v3.x へは更新できないため、v3.x を利用する場合は AGENTIC STAR Advanced(v3.3.0 以降)を購入して新しい環境として導入してください。方法B で v3.x の Helm チャートを適用するなど、ほかの方法で v3.x に更新した Basic の環境はサポートの対象外です。

アップデート方法は次の 2 通りから選択できます。通常は **方法A（セルフアップデート）** を推奨します。

| 方法                            | 概要                                                         | 推奨ケース                                  |
| ----------------------------- | ---------------------------------------------------------- | -------------------------------------- |
| **方法A: 管理画面からのセルフアップデート（推奨）** | 管理画面の「バージョン管理」ページから対象バージョンを選択して実行。各サービスのアップグレードを自動で順次実行する。 | 通常のアップデート全般                            |
| 方法B: 手動アップデート（CLI操作）          | `kubectl` / `helm` を直接操作して個別チャートをアップグレード。                  | 個別の細かい制御が必要な場合、CI/CD への組み込み、トラブル時のリカバリ |

---

## 方法A: 管理画面からのセルフアップデート（推奨）

管理画面の「バージョン管理」ページから、利用可能な次バージョンへ自動でアップグレードを実行できます。各サービスは事前に定義された依存関係順に順次アップグレードされ、進捗・結果が画面で確認できます。

### A-1. 前提条件

- 管理画面（`https://admin.<your-domain>` 等）に**管理者権限**でログイン可能であること
- アンブレラチャート (`agentic-star-platform`) が公式 Helm リポジトリで配信済みであること
- アップグレードコントローラー (`upgrade-controller`) が AKS 上で稼働中であること

### A-2. バージョン管理画面を開く

管理画面にログイン後、左サイドバーの **「バージョン管理」** メニューをクリックします。

![バージョン管理画面（アップデート前）](https://developers.fd.agenticstar.tm.softbank.jp/assets/images/01_before_vup-f23eb1fc86e6f690396d91c6501fc201.png)

画面では以下が確認できます。

- **現在のバージョン**: 現在デプロイされているプラットフォームのバージョン（例: `v2.0.0`）と `deployed` ステータス
- **利用可能なバージョン**: アップグレード可能な次バージョン（「次のバージョン」ラベル）と、各バージョンのリリースノートへのリンク
- **デプロイ済みチャート一覧**: 各サブチャートの現在のバージョンと状態

> **注記**
>
> 利用可能なバージョン一覧は順次アップグレード方式です。複数バージョン先までジャンプはできず、必ず「次のバージョン」を順番に適用していく必要があります。

### A-3. アップグレード対象を選択

「利用可能なバージョン」セクションで、アップグレードしたい次バージョン（`v2.1.0` など）の右側にある **「選択」** ボタンをクリックします。

### A-4. リリースノート・変更内容を確認

「アップグレード分析」画面が表示されます。

![アップグレード分析画面](https://developers.fd.agenticstar.tm.softbank.jp/assets/images/02_analyze_result-998a18a7655dfb566d836beb5f1c3295.png)

ここでは以下を確認できます。

- リリースノート（新機能、変更点、セキュリティ修正など）
- 全 N チャート中、何チャートが更新対象か
- 各サービスで自動適用される値（`auto_set`）と、入力が必要な値（`user_input`）
- **`user_input` がある場合**: 入力フォームが表示されます。各項目のヒントを確認しながら値を入力してください

確認・入力が完了したら、画面右上の **「アップグレード実行」** ボタンをクリックします。

### A-5. 実行確認

実行確認モーダルが表示されます。

![アップグレード実行確認モーダル](https://developers.fd.agenticstar.tm.softbank.jp/assets/images/03_vup_conf-e60457f4c60818caf65e5898f698b800.png)

警告メッセージを確認します。

- アップグレード対象のチャート数
- Helm 管理外の変更が検出された場合の警告（再設定が必要な場合あり）
- アップグレード中の一時的なサービス影響について

問題なければ **「実行する」** をクリックします。中止したい場合は「キャンセル」を選択してください。

### A-6. 進捗確認

アップグレードが開始され、進捗画面が表示されます。

![アップグレード実行中画面](https://developers.fd.agenticstar.tm.softbank.jp/assets/images/04_updating-9fc090a52b11b7a491fe901351af5e65.png)

画面では以下が確認できます。

- 全体の進捗バー
- 現在処理中のチャート名（`<chart-name> をアップグレード中...`）
- 各チャートのステータス（`processing` / `completed` / `skipped` / `failed`）

> **注記**
>
> バージョン変更がない（既に target\_version でデプロイされている）チャートは `skipped` として表示され、helm upgrade はスキップされます。

このページは閉じても処理は継続しますが、進捗を見届けたい場合は開いたままにしてください。

### A-7. 完了確認

すべてのチャート処理が完了すると、完了画面が表示されます。

![アップグレード完了画面](https://developers.fd.agenticstar.tm.softbank.jp/assets/images/05_vup_complete-67ca0b89891cf24b9fa4b024554f9174.png)

完了画面では以下を確認します。

- ヘッダーに **「✓ アップグレード完了」** が表示されること
- サマリ: **成功 / スキップ / 失敗** の件数
  <!-- -->
  - **失敗が `0`** であることを必ず確認
- 各チャートのステータス一覧

最後に upgrade-controller 自身も自己アップグレードを実行します（`completed` 表示）。

完了後、**「バージョン管理に戻る」** ボタンをクリックしてバージョン管理画面に戻ります。

### A-8. アップデート後の確認

バージョン管理画面で、「現在のバージョン」が新バージョンに更新されていることを確認します。

![アップデート後のバージョン管理画面](https://developers.fd.agenticstar.tm.softbank.jp/assets/images/06_after_vup-f5ad587f25b1caddb7d32417ae2ee32b.png)

- **現在のバージョン**: 新バージョンが `deployed` `最新` で表示されること
- **デプロイ済みチャート一覧**: 各サブチャートが新しいバージョンで `deployed` 状態であること

### A-9. トラブルシューティング

| 状況                          | 対応                                                                                                        |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| ロック状態が解除されず再実行できない          | 別のアップグレードが進行中でないか確認。問題なければ管理者がロックを強制解除する                                                                  |
| 失敗したチャートがある                 | 完了画面の失敗チャートのエラーメッセージを確認。AKS 上の Pod 状態 (`kubectl get pods -A`) と該当 Pod のログを確認の上、必要に応じて方法B（手動アップデート）でリカバリする |
| 進捗画面が長時間動かない                | upgrade-controller の Pod ログを確認 (`kubectl logs -n upgrade-controller deploy/upgrade-controller`)           |
| 「Helm 管理外の変更が検出されています」警告が出た | アップグレード後に手動で適用していた設定が上書きされる可能性がある。完了後にカスタム設定を再適用する                                                        |

---

## 方法B: 手動アップデート（CLI操作）

`kubectl` / `helm` で各チャートを個別にアップグレードする手順です。方法A で失敗したサービスのリカバリ時などに利用します。以下の例は Basic の最新の版（2.10.0）へ上げる場合です。

> **注意**
>
> 方法A は、版ごとに必要な設定値（新しく追加された値や、既定値の変更）を自動で適用します。方法B ではこれらの値は自動では入りません。通常は方法A を使い、方法B は方法A で失敗したサービスのリカバリに使ってください。

### B-1. 前提条件

- Kubernetes クラスタに `kubectl` で接続済み
- Helm v3.14 以降がインストール済み（`--reset-then-reuse-values` を使うため）
- 対象クラスタの管理者権限

> **注記**
>
> マーケットプレイス環境では Helm のストレージドライバが configmap のため、すべての `helm` コマンドに `HELM_DRIVER=configmap` を付与する必要があります。

### B-2. アップデートの流れ

1. 新バージョンのアンブレラ Helm チャートをダウンロード
2. 展開して Chart.yaml から各サービスのバージョンを確認
3. 個別チャートをダウンロード
4. 各サービスを B-6 の順番で `helm upgrade --reset-then-reuse-values` でアップデート
5. アップデート後の動作確認

### B-3. アンブレラ Helm チャートのダウンロード

公開リポジトリからアンブレラチャートをダウンロードします（Basic の最新は 2.10.0）。

```bash
# アンブレラチャートをダウンロード
curl -O https://agtstrmarketplacecharts.blob.core.windows.net/charts/agentic-star-platform-2.10.0.tgz

# 展開
tar xzf agentic-star-platform-2.10.0.tgz
```

### B-4. バージョンの確認

展開した `Chart.yaml` に各サービスの個別バージョンが定義されています。B-6 の表の版は 2.10.0 のものです。

```bash
cat agentic-star-platform/Chart.yaml
```

### B-5. 個別チャートのダウンロード

Helm リポジトリを追加し、Chart.yaml に記載されたバージョンのチャートをダウンロードします。

```bash
# AGENTIC STAR リポジトリを追加
helm repo add agenticai-prod https://agtstrmarketplacecharts.blob.core.windows.net/charts
helm repo update

# 個別チャートをダウンロード（例: agenticai-admin 2.10.0）
helm pull agenticai-prod/agenticai-admin --version 2.10.0 -d charts/

# B-6 の表のチャートを、同じようにすべてダウンロードします
```

### B-6. サービス一覧（アップデートする順番）

上から順にアップデートします（方法A と同じ順番です）。チャート名とリリース名が違うものがあります（`agentic-star-front` のリリース名は `librechat`、`agentic-star-auth` のリリース名は `librechat-auth`）。

| 順番 | リリース名                      | チャート（2.10.0）                          | Namespace                  | 備考                                          |
| -- | -------------------------- | ------------------------------------- | -------------------------- | ------------------------------------------- |
| 1  | `prometheus-operator`      | `kube-prometheus-stack-79.5.0.tgz`    | `monitoring`               | Prometheus 監視スタック（CRD を含むため最初）              |
| 2  | `prometheus-adapter`       | `prometheus-adapter-4.14.2.tgz`       | `monitoring`               | カスタムメトリクス                                   |
| 3  | `ingress-nginx`            | `ingress-nginx-4.14.0.tgz`            | `ingress-nginx`            | Ingress コントローラー                             |
| 4  | `extauth-service`          | `extauth-service-2.10.1.tgz`          | `proxy-system`             | ゼロトラスト認可サービス                                |
| 5  | `qdrant`                   | `qdrant-2.10.0.tgz`                   | `qdrant`                   | ベクトル DB                                     |
| 6  | `db-migration`             | `db-migration-2.10.2.tgz`             | `db-migration`             | データベースマイグレーション（Job の完了まで待つ）                 |
| 7  | `gate-services`            | `gate-services-2.9.1.tgz`             | `gate-services`            | ゲートウェイ                                      |
| 8  | `mail-ingress`             | `mail-ingress-2.10.0.tgz`             | `mail-ingress`             | メール受信（2.9.0 から）                             |
| 9  | `agent-sandbox-controller` | `agent-sandbox-controller-2.10.0.tgz` | `agent-sandbox-system`     | Sandbox のコントローラー                            |
| 10 | `agent-executor`           | `agent-executor-2.10.0.tgz`           | `agent-executor`           | エージェント実行基盤                                  |
| 11 | `agenticai-extapi`         | `agenticai-extapi-2.10.0.tgz`         | `agenticai-extapi-service` | 外部 API                                      |
| 12 | `agenticai-datadog`        | `agenticai-datadog-2.10.0.tgz`        | `agenticai-datadog`        | Datadog 連携（オプション）                           |
| 13 | `pvc-lifecycle-manager`    | `pvc-lifecycle-manager-2.10.0.tgz`    | `pvc-lifecycle-manager`    | PVC ライフサイクル管理                               |
| 14 | `keycloak-extensions`      | `keycloak-extensions-2.10.0.tgz`      | `librechat-auth`           | Keycloak（認証サービスより先に）                        |
| 15 | `librechat-auth`           | `agentic-star-auth-2.10.0.tgz`        | `librechat-auth`           | 認証サービス                                      |
| 16 | `librechat`                | `agentic-star-front-2.10.0.tgz`       | `agentic-star-front`       | メインアプリケーション                                 |
| 17 | `agenticai-admin`          | `agenticai-admin-2.10.0.tgz`          | `agentic-star-admin`       | 管理画面                                        |
| 18 | `loki`                     | `loki-6.37.0.tgz`                     | `observability`            | ログストレージ                                     |
| 19 | `alloy-logs`               | `alloy-1.1.2.tgz`                     | `observability`            | ログコレクター                                     |
| 20 | `alloy-metrics`            | `alloy-1.1.2.tgz`                     | `observability`            | メトリクスコレクター                                  |
| 21 | `k8s-monitoring`           | `k8s-monitoring-3.1.2.tgz`            | `observability`            | Kubernetes モニタリング                           |
| 22 | `agenticai-observability`  | `agenticai-observability-2.10.0.tgz`  | `observability`            | Grafana / Jaeger                            |
| 23 | `init-platform`            | `init-platform-2.10.0.tgz`            | `librechat-auth`           | 初期化 Job                                     |
| 24 | `upgrade-controller`       | `upgrade-controller-2.10.0.tgz`       | `upgrade-controller`       | アップデート機能（最後。`platformVersion` は管理画面に表示される版） |

### B-7. アップデートコマンド

#### 基本パターン

`--reset-then-reuse-values` により、新しいチャートの既定値の上に、既存の設定値（これまでに設定した値）が重ねられます。自社のチャート（第三者のチャート以外）は、イメージタグをチャートのバージョンに合わせて指定します。

```bash
HELM_DRIVER=configmap helm upgrade <リリース名> <チャートパス> \
  --namespace <namespace> \
  --reset-then-reuse-values \
  --set-string "image.tag=<バージョン>" \
  --wait \
  --timeout 10m
```

#### サービスごとのコマンド

**1. prometheus-operator（Prometheus 監視スタック）:**

```bash
HELM_DRIVER=configmap helm upgrade prometheus-operator ./charts/kube-prometheus-stack-79.5.0.tgz \
  --namespace monitoring \
  --reset-then-reuse-values \
  --wait \
  --timeout 15m
```

> **注記**
>
> チャート名は `kube-prometheus-stack` ですが、リリース名は `prometheus-operator` です。

**2. prometheus-adapter（カスタムメトリクス）:**

```bash
HELM_DRIVER=configmap helm upgrade prometheus-adapter ./charts/prometheus-adapter-4.14.2.tgz \
  --namespace monitoring \
  --reset-then-reuse-values \
  --wait \
  --timeout 10m
```

**3. ingress-nginx（Ingress コントローラー）:**

```bash
HELM_DRIVER=configmap helm upgrade ingress-nginx ./charts/ingress-nginx-4.14.0.tgz \
  --namespace ingress-nginx \
  --reset-then-reuse-values \
  --wait \
  --timeout 10m
```

**4. extauth-service（ゼロトラスト認可サービス）:**

```bash
HELM_DRIVER=configmap helm upgrade extauth-service ./charts/extauth-service-2.10.1.tgz \
  --namespace proxy-system \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.1" \
  --set-string "webhook.image.tag=2.10.1" \
  --set cert-manager.enabled=false \
  --wait \
  --timeout 20m
```

> **注意**
>
> extauth-service は `webhook.image.tag` も合わせて指定してください。また `cert-manager.enabled=false` を必ず付与してください（cert-manager は別途インストール済みのため）。

**5. qdrant（ベクトル DB）:**

```bash
HELM_DRIVER=configmap helm upgrade qdrant ./charts/qdrant-2.10.0.tgz \
  --namespace qdrant \
  --reset-then-reuse-values \
  --wait \
  --timeout 20m
```

**6. db-migration（データベースマイグレーション）:**

```bash
HELM_DRIVER=configmap helm upgrade db-migration ./charts/db-migration-2.10.2.tgz \
  --namespace db-migration \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.2" \
  --wait \
  --wait-for-jobs \
  --timeout 60m
```

**7. gate-services（ゲートウェイ）:**

```bash
HELM_DRIVER=configmap helm upgrade gate-services ./charts/gate-services-2.9.1.tgz \
  --namespace gate-services \
  --reset-then-reuse-values \
  --set-string "image.tag=2.9.1" \
  --wait \
  --timeout 10m
```

**8. mail-ingress（メール受信）:**

```bash
HELM_DRIVER=configmap helm upgrade mail-ingress ./charts/mail-ingress-2.10.0.tgz \
  --namespace mail-ingress \
  --reset-then-reuse-values \
  --set-string "haraka.image.tag=2.10.0" \
  --wait \
  --timeout 10m
```

> **注記**
>
> mail-ingress は 2.9.0 で追加されました。2.9.0 より前の版から上げる場合、mail-ingress は新規のインストールになり、必要な設定値が入らないため、方法A を使ってください。

**9. agent-sandbox-controller（Sandbox のコントローラー）:**

```bash
HELM_DRIVER=configmap helm upgrade agent-sandbox-controller ./charts/agent-sandbox-controller-2.10.0.tgz \
  --namespace agent-sandbox-system \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --timeout 10m
```

**10. agent-executor（エージェント実行基盤）:**

```bash
HELM_DRIVER=configmap helm upgrade agent-executor ./charts/agent-executor-2.10.0.tgz \
  --namespace agent-executor \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --timeout 20m
```

**11. agenticai-extapi（外部 API）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-extapi ./charts/agenticai-extapi-2.10.0.tgz \
  --namespace agenticai-extapi-service \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --timeout 10m
```

**12. agenticai-datadog（Datadog 連携）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-datadog ./charts/agenticai-datadog-2.10.0.tgz \
  --namespace agenticai-datadog \
  --reset-then-reuse-values \
  --wait \
  --timeout 10m
```

**13. pvc-lifecycle-manager（PVC ライフサイクル管理）:**

```bash
HELM_DRIVER=configmap helm upgrade pvc-lifecycle-manager ./charts/pvc-lifecycle-manager-2.10.0.tgz \
  --namespace pvc-lifecycle-manager \
  --reset-then-reuse-values \
  --wait \
  --timeout 10m
```

**14. keycloak-extensions（Keycloak）:**

```bash
HELM_DRIVER=configmap helm upgrade keycloak-extensions ./charts/keycloak-extensions-2.10.0.tgz \
  --namespace librechat-auth \
  --reset-then-reuse-values \
  --set-string "keycloakx.image.tag=2.10.0" \
  --wait \
  --timeout 20m
```

**15. librechat-auth（認証サービス）:**

```bash
HELM_DRIVER=configmap helm upgrade librechat-auth ./charts/agentic-star-auth-2.10.0.tgz \
  --namespace librechat-auth \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --timeout 20m
```

**16. librechat（メインアプリケーション）:**

```bash
HELM_DRIVER=configmap helm upgrade librechat ./charts/agentic-star-front-2.10.0.tgz \
  --namespace agentic-star-front \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --timeout 20m
```

**17. agenticai-admin（管理画面）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-admin ./charts/agenticai-admin-2.10.0.tgz \
  --namespace agentic-star-admin \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --timeout 10m
```

**18. loki（ログストレージ）:**

```bash
HELM_DRIVER=configmap helm upgrade loki ./charts/loki-6.37.0.tgz \
  --namespace observability \
  --reset-then-reuse-values \
  --wait \
  --timeout 20m
```

**19. alloy-logs（ログコレクター）:**

```bash
HELM_DRIVER=configmap helm upgrade alloy-logs ./charts/alloy-1.1.2.tgz \
  --namespace observability \
  --reset-then-reuse-values \
  --wait \
  --timeout 20m
```

**20. alloy-metrics（メトリクスコレクター）:**

```bash
HELM_DRIVER=configmap helm upgrade alloy-metrics ./charts/alloy-1.1.2.tgz \
  --namespace observability \
  --reset-then-reuse-values \
  --wait \
  --timeout 20m
```

> **注記**
>
> alloy-logs と alloy-metrics は同じチャート（`alloy-1.1.2.tgz`）を使用しますが、リリース名と values が異なります。

**21. k8s-monitoring（Kubernetes モニタリング）:**

```bash
HELM_DRIVER=configmap helm upgrade k8s-monitoring ./charts/k8s-monitoring-3.1.2.tgz \
  --namespace observability \
  --reset-then-reuse-values \
  --wait \
  --timeout 15m
```

**22. agenticai-observability（Grafana / Jaeger）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-observability ./charts/agenticai-observability-2.10.0.tgz \
  --namespace observability \
  --reset-then-reuse-values \
  --wait \
  --timeout 15m
```

**23. init-platform（初期化 Job）:**

```bash
HELM_DRIVER=configmap helm upgrade init-platform ./charts/init-platform-2.10.0.tgz \
  --namespace librechat-auth \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --wait \
  --wait-for-jobs \
  --timeout 10m
```

**24. upgrade-controller（アップデート機能）:**

```bash
HELM_DRIVER=configmap helm upgrade upgrade-controller ./charts/upgrade-controller-2.10.0.tgz \
  --namespace upgrade-controller \
  --reset-then-reuse-values \
  --set-string "image.tag=2.10.0" \
  --set-string "platformVersion=2.10.0" \
  --wait \
  --timeout 10m
```

### B-8. アップデート後の確認

#### Pod の状態確認

```bash
# 全 Namespace の Pod 状態を一括確認
HELM_DRIVER=configmap helm list -A

# 特定 Namespace の Pod 確認
kubectl get pods -n <namespace>
```

#### ログの確認

アップデート後にエラーが発生していないか確認します。

```bash
# 特定 Pod のログ確認
kubectl logs -n <namespace> <pod-name>

# 直近のイベント確認
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
```

---

## 注意事項

- アップデートは**サービス単位**で実行してください。全サービスを一度にアップデートするのではなく、1つずつ確認しながら進めることを推奨します（方法A は内部で順次実行されます）。
- `--reset-then-reuse-values` を使用するため、[ドメイン設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/guide/domain-guide.md)や[セキュリティガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/guide/security-guide.md)で変更した設定値はそのまま保持されます。
- アップデート前にバックアップを取得することを推奨します。
- 問題が発生した場合は、前バージョンのチャートで同じコマンド（イメージタグも前のバージョン）を実行することでロールバックできます（方法B）。
