メインコンテンツまでスキップ

バージョンアップガイド

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)に証明書などを設定してください。アップグレード分析の画面にも、同じ内容が警告として表示されます。

切り替わったことは、次のコマンドで確かめられます。

curl
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. アップデートの流れ​

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

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

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

curl
# アンブレラチャートをダウンロード(バージョンは適宜変更)
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 に各サービスの個別バージョンが定義されています。

curl
cat agentic-star-platform/Chart.yaml

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

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

curl
# 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備考
librechatagentic-star-frontメインアプリケーション
librechat-authlibrechat-auth認証サービス
keycloak-extensionslibrechat-auth認証基盤(Keycloak)
agenticai-adminagentic-star-admin管理画面
agent-executoragent-executorエージェント実行基盤
agenticai-extapiagenticai-extapi-service外部 API
gate-servicesgate-servicesゲートウェイ・ルーティング
db-migrationdb-migrationデータベースマイグレーション
agent-sandbox-controlleragent-sandbox-systemエージェントの実行環境(サンドボックス)の管理
mail-ingressmail-ingressメール受信

セキュリティ・インフラ​

リリース名Namespace備考
extauth-serviceproxy-systemゼロトラスト認可サービス
ingress-nginxingress-nginxIngress コントローラー
cert-managercert-manager証明書
qdrantqdrantベクトル DB
cluster-autoscalerkube-systemノードの自動増減(AWS のみ)

監視・運用​

リリース名Namespace備考
prometheus-operatormonitoringPrometheus 監視スタック
prometheus-adaptermonitoring監視基盤
lokiobservabilityログストレージ
alloy-logsobservabilityログコレクター
alloy-metricsobservabilityメトリクスコレクター
k8s-monitoringobservabilityKubernetes モニタリング
agenticai-observabilityobservabilityGrafana / Jaeger
agenticai-datadogagenticai-datadogDatadog 連携(オプション)
pvc-lifecycle-managerpvc-lifecycle-managerPVC ライフサイクル管理

プラットフォーム初期化​

リリース名Namespace備考
init-platformlibrechat-auth初期化ジョブ(通常アップデート不要)
upgrade-controllerupgrade-controllerバージョン管理

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

基本パターン​

ほとんどのサービスは以下のパターンでアップデートできます。--reuse-values により既存の設定値はすべて保持され、--set-string "image.tag=..." で指定したイメージタグのみが更新されます。

curl
export HELM_DRIVER=configmap

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

アプリケーションコンポーネント​

librechat(メインアプリケーション):

curl
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(認証サービス):

curl
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(認証基盤):

curl
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(管理画面):

curl
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(エージェント実行基盤):

curl
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):

curl
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(ゲートウェイ):

curl
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(データベースマイグレーション):

curl
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(エージェントの実行環境の管理):

curl
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(メール受信):

curl
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(ゼロトラスト認可サービス):

curl
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 コントローラー):

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

qdrant(ベクトル DB):

curl
HELM_DRIVER=configmap helm upgrade qdrant ./charts/qdrant-3.3.0.tgz \
--namespace qdrant \
--reuse-values \
--wait \
--timeout 20m

監視・運用​

prometheus-operator(Prometheus 監視スタック):

curl
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(ログストレージ):

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

alloy-logs(ログコレクター):

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

alloy-metrics(メトリクスコレクター):

curl
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 モニタリング):

curl
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):

curl
HELM_DRIVER=configmap helm upgrade agenticai-observability ./charts/agenticai-observability-3.3.0.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 15m

agenticai-datadog(Datadog 連携):

curl
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 ライフサイクル管理):

curl
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(バージョン管理):

curl
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 の状態確認​

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

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

ログの確認​

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

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

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

注意事項​

  • アップデートはサービス単位で実行してください。全サービスを一度にアップデートするのではなく、1つずつ確認しながら進めることを推奨します(方法A は内部で順次実行されます)。
  • --reuse-values を使用するため、ドメイン設定ガイドやセキュリティガイドで変更した設定値はそのまま保持されます。
  • アップデート前にバックアップを取得することを推奨します。
  • データベースの移行を伴う版では、前のバージョンのチャートに戻してもデータは前の形に戻らないため、ロールバックできないことがあります。アップデート前のバックアップを取得したうえで、問題が発生した場合はサポートへ連絡してください。