バージョンアップガイド
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. バージョン管理画面を開く
管理画面にログイン後、左サイドバーの 「バージョン管理」 メニューをクリックします。

画面では以下が確認できます。
- 現在のバージョン: 現在デプロイされているプラットフォームのバージョン(例:
v2.0.0)とdeployedステータス - 利用可能なバージョン: アップグレード可能な次バージョン(「次のバージョン」ラベル)と、各バージョンのリリースノートへのリンク
- デプロイ済みチャート一覧: 各サブチャートの現在のバージョンと状態
利用可能なバージョン一覧は順次アップグレード方式です。複数バージョン先までジャンプはできず、必ず「次のバージョン」を順番に適用していく必要があります。
A-3. アップグレード対象を選択
「利用可能なバージョン」セクションで、アップグレードしたい次バージョン(v2.1.0 など)の右側にある 「選択」 ボタンをクリックします。
A-4. リリースノート・変更内容を確認
「アップグレード分析」画面が表示されます。

ここでは以下を確認できます。
- リリースノート(新機能、変更点、セキュリティ修正など)
- 全 N チャート中、何チャートが更新対象か
- 各サービスで自動適用される値(
auto_set)と、入力が必要な値(user_input) user_inputがある場合: 入力フォームが表示されます。各項目のヒントを確認しながら値を入力してください
確認・入力が完了したら、画面右上の 「アップグレード実行」 ボタンをクリックします。
A-5. 実行確認
実行確認モーダルが表示されます。

警告メッセージを確認します。
- アップグレード対象のチャート数
- Helm 管理外の変更が検出された場合の警告(再設定が必要な場合あり)
- アップグレード中の一時的なサービス影響について
問題なければ 「実行する」 をクリックします。中止したい場合は「キャンセル」を選択してください。
A-6. 進捗確認
アップグレードが開始され、進捗画面が表示されます。

画面では以下が確認できます。
- 全体の進捗バー
- 現在処理中のチャート名(
<chart-name> をアップグレード中...) - 各チャートのステータス(
processing/completed/skipped/failed)
バージョン変更がない(既に target_version でデプロイされている)チャートは skipped として表示され、helm upgrade はスキップされます。
このページは閉じても処理は継続しますが、進捗を見届けたい場合は開いたままにしてください。
A-7. 完了確認
すべてのチャート処理が完了すると、完了画面が表示されます。

完了画面では以下を確認します。
- ヘッダーに 「✓ アップグレード完了」 が表示されること
- サマリ: 成功 / スキップ / 失敗 の件数
- 失敗が
0であることを必ず確認
- 失敗が
- 各チャートのステータス一覧
最後に upgrade-controller 自身も自己アップグレードを実行します(completed 表示)。
完了後、「バージョン管理に戻る」 ボタンをクリックしてバージョン管理画面に戻ります。
A-8. アップデート後の確認
バージョン管理画面で、「現在のバージョン」が新バージョンに更新されていることを確認します。

- 現在のバージョン: 新バージョンが
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. アップデートの流れ
- 新バージョンのアンブレラ Helm チャートをダウンロード
- 展開して Chart.yaml から各サービスのバージョンを確認
- 個別チャートをダウンロード
- 各サービスを B-6 の順番で
helm upgrade --reset-then-reuse-valuesでアップデート - アップデート後の動作確認
B-3. アンブレラ Helm チャートのダウンロード
公開リポジトリからアンブレラチャートをダウンロードします(Basic の最新は 2.10.0)。
# アンブレラチャートをダウンロード
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 のものです。
cat agentic-star-platform/Chart.yaml
B-5. 個別チャートのダウンロード
Helm リポジトリを追加し、Chart.yaml に記載されたバージョンのチャートをダウンロードします。
# 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 により、新しいチャートの既定値の上に、既存の設定値(これまでに設定した値)が重ねられます。自社のチャート(第三者のチャート以外)は、イメージタグをチャートのバージョンに合わせて指定します。
HELM_DRIVER=configmap helm upgrade <リリース名> <チャートパス> \
--namespace <namespace> \
--reset-then-reuse-values \
--set-string "image.tag=<バージョン>" \
--wait \
--timeout 10m
サービスごとのコマンド
1. prometheus-operator(Prometheus 監視スタック):
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(カスタムメトリクス):
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 コントローラー):
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(ゼロトラスト認可サービス):
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):
HELM_DRIVER=configmap helm upgrade qdrant ./charts/qdrant-2.10.0.tgz \
--namespace qdrant \
--reset-then-reuse-values \
--wait \
--timeout 20m
6. db-migration(データベースマイグレーション):
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(ゲートウェイ):
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(メール受信):
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 のコントローラー):
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(エージェント実行基盤):
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):
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 連携):
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 ライフサイクル管理):
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):
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(認証サービス):
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(メインアプリケーション):
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(管理画面):
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(ログストレージ):
HELM_DRIVER=configmap helm upgrade loki ./charts/loki-6.37.0.tgz \
--namespace observability \
--reset-then-reuse-values \
--wait \
--timeout 20m
19. alloy-logs(ログコレクター):
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(メトリクスコレクター):
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 モニタリング):
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):
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):
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(アップデート機能):
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 の状態確認
# 全 Namespace の Pod 状態を一括確認
HELM_DRIVER=configmap helm list -A
# 特定 Namespace の Pod 確認
kubectl get pods -n <namespace>
ログの確認
アップデート後にエラーが発生していないか確認します。
# 特定 Pod のログ確認
kubectl logs -n <namespace> <pod-name>
# 直近のイベント確認
kubectl get events -n <namespace> --sort-by='.lastTimestamp'