バージョンアップガイド
AGENTIC STAR マーケットプレイス版の Kubernetes アプリケーションをアップデートする手順を解説します。
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 を直接操作して個別チャートをアップグレード。 | サポートから案内された場合(方法A で失敗したサービスのリカバリなど) |
方法A: 管理画面からのセルフアップデート(推奨)
管理画面の「バージョン管理」ページから、利用可能な次バージョンへ自動でアップグレードを実行できます。各サービスは事前に定義された依存関係順に順次アップグレードされ、進捗・結果が画面で確認できます。
A-1. 前提条件
- 管理画面(
https://admin.<your-domain>等)に管理者権限でログイン可能であること - アンブレラチャート (
agentic-star-platform) が公式 Helm リポジトリで配信済みであること - アップグレードコントローラー (
upgrade-controller) がクラスター上で稼働中であること
A-2. バージョン管理画面を開く
管理画面にログイン後、左サイドバーの 「バージョン管理」 メニューをクリックします。

画面では以下が確認できます。
- 現在のバージョン: 現在デプロイされているプラットフォームのバージョン(例:
v3.3.0)とdeployedステータス - 利用可能なバージョン: アップグレード可能な次バージョン(「次のバージョン」ラベル)と、各バージョンのリリースノートへのリンク
- デプロイ済みチャート一覧: 各サブチャートの現在のバージョンと状態
利用可能なバージョン一覧は順次アップグレード方式です。複数バージョン先までジャンプはできず、必ず「次のバージョン」を順番に適用していく必要があります。
A-3. アップグレード対象を選択
「利用可能なバージョン」セクションで、アップグレードしたい次バージョン(v3.4.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 があるときは、最初に upgrade-controller 自身が更新され、新しい upgrade-controller が残りのサービスの更新を続けます。このとき進捗の表示が一時的に途切れることがありますが、ページはそのまま開いておいてください。
完了後、「バージョン管理に戻る」 ボタンをクリックしてバージョン管理画面に戻ります。
A-8. アップデート後の確認
バージョン管理画面で、「現在のバージョン」が新バージョンに更新されていることを確認します。

- 現在のバージョン: 新バージョンが
deployed最新で表示されること - デプロイ済みチャート一覧: 各サブチャートが新しいバージョンで
deployed状態であること
A-9. トラブルシューティング
| 状況 | 対応 |
|---|---|
| ロック状態が解除されず再実行できない | 別のアップグレードが進行中でないか確認。進行中でなければ kubectl rollout restart deploy/upgrade-controller -n upgrade-controller で upgrade-controller を再起動すると、起動時にロックが解除されます。その後、画面から再実行する |
| 失敗したチャートがある | 完了画面の失敗チャートのエラーメッセージを確認。Pod 状態 (kubectl get pods -A) と該当 Pod のログで原因を確認して直してから、バージョン管理画面で同じ版へのアップデートをもう一度実行する(失敗したチャートもやり直しの対象になる) |
| 進捗画面が長時間動かない | upgrade-controller の Pod ログを確認 (kubectl logs -n upgrade-controller deploy/upgrade-controller) |
| 「Helm 管理外の変更が検出されています」警告が出た | アップグレード後に手動で適用していた設定が上書きされる可能性がある。完了後にカスタム設定を再適用する |
A-10. v3.4.0 へのアップデートでの入口の切り替え
v3.4.0 から、AGENTIC STAR の入口(ブラウザーや API からの要求を受ける部分)は NGINX Gateway Fabric になります。v3.3.x から方法A で v3.4.0 にアップデートすると、各サービスの更新の後に、アップグレードコントローラーが入口を NGINX Gateway Fabric に切り替えます。
- 入口の住所(IP アドレス・ホスト名)と URL は変わりません
- 製品の自前の証明書・接続元の IP 制限などの入口の設定は、今の入口(ingress-nginx)から引き継ぎます(独自のドメインの証明書などは引き継ぎません。下の注意を参照)
- KC(認証サーバー)の外の入口を開けている環境は、その入口も切り替えます
- 切り替えて応答を確かめた後、これまでの入口(ingress-nginx)は停止します(Pod の数を 0 にし、自動で増やす設定も止めます)
切り替えの直後の数十秒は、一部の要求が失敗することがあります。利用の少ない時間帯にアップデートしてください。
ドメイン設定ガイドの手順で設定した証明書や、CDN・ロードバランサーを前に置くための設定は、これまでの入口(ingress-nginx)が使う Ingress に入っているため、切り替えた直後から効かなくなります(DNS の向き先と入口の住所は変わりません)。そのままでは、証明書のエラーになるか、つながらなくなります。
独自のドメインを設定している環境は、利用の少ない時間帯にアップデートし、アップデートの直後に、ドメイン設定ガイド(v3.4.0 以降)の手順で入口(NGINX Gateway Fabric)に証明書などを設定してください。アップグレード分析の画面にも、同じ内容が警告として表示されます。
切り替わったことは、次のコマンドで確かめられます。
kubectl get svc -n ingress-nginx -l app.kubernetes.io/purpose \
-o custom-columns='NAME:.metadata.name,ENTRY:.spec.selector.gateway\.networking\.k8s\.io/gateway-name'
kubectl get deploy ingress-nginx-controller -n ingress-nginx
- 1 つ目: すべての行の
ENTRYにfront・adminなどの名前が表示されれば、NGINX Gateway Fabric に切り替わっています(<none>の行は ingress-nginx のままです) - 2 つ目:
READYが0/0なら、ingress-nginx は停止しています
| 状況 | 対応 |
|---|---|
完了画面で entry が失敗になった | NGINX Gateway Fabric の準備が整わなかったため、入口は ingress-nginx のまま動いています。エラーメッセージで原因を確かめて直してから、バージョン管理画面で同じ版へのアップデートをもう一度実行してください(更新済みのサービスはスキップされ、切り替えがやり直されます) |
| 入口を ingress-nginx に戻したい | v3.4.0 から AGENTIC STAR の入口は NGINX Gateway Fabric だけで、ingress-nginx に戻すことはおすすめしません(ingress-nginx はコミュニティでの開発が終了していて、修正版が提供されません)。戻す必要がある場合は、サポートに相談してください |
お知らせ の手順で HTTP/2 を無効にした環境も、そのままアップデートできます。切り替えた後は、その設定は使われません。
方法B(手動アップデート)では入口は切り替わりません。v3.4.0 へは方法A でアップデートしてください。
方法B: 手動アップデート(CLI操作)
kubectl / helm で各チャートを個別にアップグレードする手順です。
方法B は、版ごとに必要な設定値の追加・変更(方法A が自動で反映するもの)を行いません。新しい版で必須になった値が入らず、サービスが起動しないことがあります。通常は方法A を使い、方法B はサポートから案内されたとき(方法A で失敗したサービスのリカバリなど)に使ってください。
B-1. 前提条件
- クラスターに
kubectlで接続済み - Helm v3 がインストール済み
- 対象クラスタの管理者権限
マーケットプレイス環境では Helm のストレージドライバが configmap のため、すべての helm コマンドに HELM_DRIVER=configmap を付与する必要があります。
B-2. アップデートの流れ
- 新バージョンのアンブレラ Helm チャートをダウンロード
- 展開して Chart.yaml から各サービスのバージョンを確認
- 個別チャートをダウンロード
- 各サービスを
helm upgrade --reuse-valuesでアップデート - アップデート後の動作確認
B-3. アンブレラ Helm チャートのダウンロード
公開リポジトリから最新のアンブレラチャートをダウンロードします。
# アンブレラチャートをダウンロード(バージョンは適宜変更)
curl -O https://agtstrmarketplacecharts.blob.core.windows.net/charts/agentic-star-platform-3.3.0.tgz
# 展開
tar xzf agentic-star-platform-3.3.0.tgz
B-4. バージョンの確認
展開した Chart.yaml に各サービスの個別バージョンが定義されています。
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 3.3.0)
helm pull agenticai-prod/agenticai-admin --version 3.3.0 -d charts/
B-6. サービス一覧
以下がマーケットプレイス版に含まれるサービスの一覧です。
アプリケーションコンポーネント
| リリース名 | Namespace | 備考 |
|---|---|---|
librechat | agentic-star-front | メインアプリケーション |
librechat-auth | librechat-auth | 認証サービス |
keycloak-extensions | librechat-auth | 認証基盤(Keycloak) |
agenticai-admin | agentic-star-admin | 管理画面 |
agent-executor | agent-executor | エージェント実行基盤 |
agenticai-extapi | agenticai-extapi-service | 外部 API |
gate-services | gate-services | ゲートウェイ・ルーティング |
db-migration | db-migration | データベースマイグレーション |
agent-sandbox-controller | agent-sandbox-system | エージェントの実行環境(サンドボックス)の管理 |
mail-ingress | mail-ingress | メール受信 |
セキュリティ・インフラ
| リリース名 | Namespace | 備考 |
|---|---|---|
extauth-service | proxy-system | ゼロトラスト認可サービス |
ingress-nginx | ingress-nginx | Ingress コントローラー |
cert-manager | cert-manager | 証明書 |
qdrant | qdrant | ベクトル DB |
cluster-autoscaler | kube-system | ノードの自動増減(AWS のみ) |
監視・運用
| リリース名 | Namespace | 備考 |
|---|---|---|
prometheus-operator | monitoring | Prometheus 監視スタック |
prometheus-adapter | monitoring | 監視基盤 |
loki | observability | ログストレージ |
alloy-logs | observability | ログコレクター |
alloy-metrics | observability | メトリクスコレクター |
k8s-monitoring | observability | Kubernetes モニタリング |
agenticai-observability | observability | Grafana / Jaeger |
agenticai-datadog | agenticai-datadog | Datadog 連携(オプション) |
pvc-lifecycle-manager | pvc-lifecycle-manager | PVC ライフサイクル管理 |
プラットフォーム初期化
| リリース名 | Namespace | 備考 |
|---|---|---|
init-platform | librechat-auth | 初期化ジョブ(通常アップデート不要) |
upgrade-controller | upgrade-controller | バージョン管理 |
B-7. アップデートコマンド
基本パターン
ほとんどのサービスは以下のパターンでアップデートできます。--reuse-values により既存の設定値はすべて保持され、--set-string "image.tag=..." で指定したイメージタグのみが更新されます。
export HELM_DRIVER=configmap
HELM_DRIVER=configmap helm upgrade <リリース名> <チャートパス> \
--namespace <namespace> \
--reuse-values \
--set-string "image.tag=<バージョン>" \
--wait \
--timeout 10m
アプリケーションコンポーネント
librechat(メインアプリケーション):
HELM_DRIVER=configmap helm upgrade librechat ./charts/agentic-star-front-3.3.0.tgz \
--namespace agentic-star-front \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 20m
librechat-auth(認証サービス):
HELM_DRIVER=configmap helm upgrade librechat-auth ./charts/agentic-star-auth-3.3.0.tgz \
--namespace librechat-auth \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 20m
keycloak-extensions(認証基盤):
HELM_DRIVER=configmap helm upgrade keycloak-extensions ./charts/keycloak-extensions-3.3.0.tgz \
--namespace librechat-auth \
--reuse-values \
--set-string "keycloakx.image.tag=3.3.0" \
--wait \
--timeout 15m
keycloak-extensions の keycloakx.image.tag は、librechat-auth(agentic-star-auth)と同じバージョンにしてください。
agenticai-admin(管理画面):
HELM_DRIVER=configmap helm upgrade agenticai-admin ./charts/agenticai-admin-3.3.0.tgz \
--namespace agentic-star-admin \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m
agent-executor(エージェント実行基盤):
HELM_DRIVER=configmap helm upgrade agent-executor ./charts/agent-executor-3.3.0.tgz \
--namespace agent-executor \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 20m
agenticai-extapi(外部 API):
HELM_DRIVER=configmap helm upgrade agenticai-extapi ./charts/agenticai-extapi-3.3.0.tgz \
--namespace agenticai-extapi-service \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m
gate-services(ゲートウェイ):
HELM_DRIVER=configmap helm upgrade gate-services ./charts/gate-services-3.3.0.tgz \
--namespace gate-services \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m
db-migration(データベースマイグレーション):
HELM_DRIVER=configmap helm upgrade db-migration ./charts/db-migration-3.3.0.tgz \
--namespace db-migration \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m
agent-sandbox-controller(エージェントの実行環境の管理):
HELM_DRIVER=configmap helm upgrade agent-sandbox-controller ./charts/agent-sandbox-controller-3.3.0.tgz \
--namespace agent-sandbox-system \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 5m
mail-ingress(メール受信):
HELM_DRIVER=configmap helm upgrade mail-ingress ./charts/mail-ingress-3.3.0.tgz \
--namespace mail-ingress \
--reuse-values \
--set-string "haraka.image.tag=3.3.0" \
--wait \
--timeout 15m
セキュリティ・インフラ
extauth-service(ゼロトラスト認可サービス):
HELM_DRIVER=configmap helm upgrade extauth-service ./charts/extauth-service-3.3.0.tgz \
--namespace proxy-system \
--reuse-values \
--set-string "image.tag=3.3.0" \
--set-string "webhook.image.tag=3.3.0" \
--set cert-manager.enabled=false \
--wait \
--timeout 20m
extauth-service は webhook.image.tag も合わせて指定してください。また cert-manager.enabled=false を必ず付与してください(cert-manager は別途インストール済みのため)。
ingress-nginx(Ingress コントローラー):
HELM_DRIVER=configmap helm upgrade ingress-nginx ./charts/ingress-nginx-4.14.0.tgz \
--namespace ingress-nginx \
--reuse-values \
--wait \
--timeout 10m
qdrant(ベクトル DB):
HELM_DRIVER=configmap helm upgrade qdrant ./charts/qdrant-3.3.0.tgz \
--namespace qdrant \
--reuse-values \
--wait \
--timeout 20m
監視・運用
prometheus-operator(Prometheus 監視スタック):
HELM_DRIVER=configmap helm upgrade prometheus-operator ./charts/kube-prometheus-stack-79.5.0.tgz \
--namespace monitoring \
--reuse-values \
--wait \
--timeout 15m
チャート名は kube-prometheus-stack ですが、リリース名は prometheus-operator です。
loki(ログストレージ):
HELM_DRIVER=configmap helm upgrade loki ./charts/loki-6.37.0.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 20m
alloy-logs(ログコレクター):
HELM_DRIVER=configmap helm upgrade alloy-logs ./charts/alloy-1.1.2.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 20m
alloy-metrics(メトリクスコレクター):
HELM_DRIVER=configmap helm upgrade alloy-metrics ./charts/alloy-1.1.2.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 20m
alloy-logs と alloy-metrics は同じチャート(alloy-1.1.2.tgz)を使用しますが、リリース名と values が異なります。
k8s-monitoring(Kubernetes モニタリング):
HELM_DRIVER=configmap helm upgrade k8s-monitoring ./charts/k8s-monitoring-3.1.2.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 15m
agenticai-observability(Grafana / Jaeger):
HELM_DRIVER=configmap helm upgrade agenticai-observability ./charts/agenticai-observability-3.3.0.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 15m
agenticai-datadog(Datadog 連携):
HELM_DRIVER=configmap helm upgrade agenticai-datadog ./charts/agenticai-datadog-3.3.0.tgz \
--namespace agenticai-datadog \
--reuse-values \
--wait \
--timeout 10m
pvc-lifecycle-manager(PVC ライフサイクル管理):
HELM_DRIVER=configmap helm upgrade pvc-lifecycle-manager ./charts/pvc-lifecycle-manager-3.3.0.tgz \
--namespace pvc-lifecycle-manager \
--reuse-values \
--wait \
--timeout 10m
upgrade-controller(バージョン管理):
HELM_DRIVER=configmap helm upgrade upgrade-controller ./charts/upgrade-controller-3.3.0.tgz \
--namespace upgrade-controller \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m
次の外部チャートは、方法B の対象にしていません: prometheus-adapter・cert-manager・cluster-autoscaler(AWS のみ)。prometheus-adapter は方法A で更新されます。cert-manager と cluster-autoscaler はインストール時に入れたものを使い続けます。
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'