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

構築トラブルシューティングガイド

マーケットプレイスからの導入(マネージドアプリケーションのデプロイ)が途中で止まったときに、何が起きているかを調べ、復旧するための手引きです。インフラの構築後に行われるアプリケーションのインストールは、コンポーネントを決まった順序で 1 つずつ Helm リリースとして導入します。途中で止まると、その後ろのコンポーネントが入らないまま終わるため、「ログインできない」「管理画面が開かない」といった症状になります。

注記

この手引きのコマンドと画面は Azure のものです。AWS で導入した場合は、AWS の場合を参照してください。

注意

失敗した環境でインストールを手作業でやり直さないでください。インストーラーは実行のたびに認証用の鍵やパスワードを新しく生成するため、同じクラスターで再実行すると、導入済みのコンポーネントと値が食い違い、復旧がさらに難しくなります。復旧方法は途中で止まった環境の復旧を参照してください。

症状から原因を探す​

症状起きていること見る所
ログインや新規登録で Realm not found / Realm does not exist と表示される認証基盤の初期設定ジョブ(init-platform)が動いておらず、realm agenticstar が作られていないinit-platform の状態、導入の進み具合
管理画面の IP にアクセスしても応答が無い、または認証サービスのログに Admin S2S request failed が出る管理画面(agenticai-admin)が導入されていない。agentic-star-admin 名前空間に Pod が無い導入の進み具合
Pod が Pending のまま動かないノードに空きが無い(Insufficient cpu / Insufficient memory)。多くはサブスクリプションの vCPU クォータ不足でノードを増やせないPending の理由、ノードを増やせない理由
マネージドアプリケーションのデプロイが Failed になり、エラーが Azure の一般的な文言だけデプロイスクリプト(インストーラー)が時間切れや失敗で終了したデプロイスクリプトのログ、導入の進み具合
デプロイが AvailabilityZoneNotSupported で失敗する選んだ可用性ゾーンに VM を置けないサブスクリプション・リージョンである別のゾーンの組み合わせでデプロイし直す(Azure クイックスタート)

導入の進み具合を調べる​

クラスターに接続する​

curl
# リソースグループはマネージドアプリケーションの管理リソースグループ(名前は mrg- で始まる)
az aks get-credentials --resource-group <管理リソースグループ> --name <AKS Cluster Name>

Helm リリースの一覧を見る​

マーケットプレイス版は Helm のストレージドライバに configmap を使っています。HELM_DRIVER=configmap を付けないと何も表示されません。

curl
HELM_DRIVER=configmap helm list -A

インストーラーは次の順序でリリースを導入します。一覧の UPDATED の時刻を順に並べると、どこまで入ったかが分かります。STATUS が failed のリリースが止まった所です。

順リリース名名前空間役割
1prometheus-operatormonitoring監視基盤
2prometheus-adaptermonitoring監視基盤
3ingress-nginxingress-nginx入口(LoadBalancer)
4cert-managercert-manager証明書
5qdrantqdrantベクトルデータベース
6db-migrationdb-migrationデータベースの初期化
7extauth-serviceproxy-system認証プロキシ
8gate-servicesgate-servicesLLM ゲートウェイ
9mail-ingressmail-ingressメール受信
10agent-sandbox-controlleragent-sandbox-systemエージェント実行基盤
11agent-executoragent-executorエージェント実行
12agenticai-extapiagenticai-extapi-service外部 API
13agenticai-datadogagenticai-datadogDatadog 連携
14pvc-lifecycle-managerpvc-lifecycle-managerストレージ管理
15librechat-authlibrechat-auth認証サービス
16keycloak-extensionslibrechat-auth認証基盤(Keycloak)
17librechatagentic-star-frontメイン画面
18agenticai-adminagentic-star-admin管理画面
19lokiobservabilityログ基盤
20alloy-logsobservabilityログ収集
21alloy-metricsobservabilityメトリクス収集
22k8s-monitoringobservability監視
23agenticai-observabilityobservability監視
24init-platformlibrechat-auth認証基盤の初期設定(realm・クライアント・初期管理者の作成)
25upgrade-controllerupgrade-controllerバージョン管理

AWS では、1 番目の前に、ノードを自動で増減する cluster-autoscaler(名前空間 kube-system)が入ります(全部で 26 リリース)。

たとえば 17 番目のメイン画面(librechat)で止まると、管理画面・ログ基盤・init-platform が入らないため、「ログインで Realm not found」「管理画面が開かない」の両方が起きます。

失敗したリリースの理由を見る​

curl
HELM_DRIVER=configmap helm history <リリース名> -n <名前空間>

DESCRIPTION に失敗の理由が出ます。context deadline exceeded は、待ち時間内に Pod が起動しなかったことを示します(多くは Pod が Pending のまま)。

調べ方​

Pod が Pending の理由​

curl
# Running / Completed 以外の Pod を探す
kubectl get pods -A | grep -v -E 'Running|Completed'

# Events に理由が出る(Insufficient cpu / Insufficient memory など)
kubectl describe pod <Pod 名> -n <名前空間>

ノードを増やせない理由​

curl
# オートスケーラーの状態
kubectl get configmap -n kube-system cluster-autoscaler-status -o yaml

# ノードの追加に失敗したイベント
kubectl get events -n kube-system --field-selector reason=FailedToScaleUpGroup

# ノードの空き(Allocated resources の cpu / memory)
kubectl describe nodes | grep -A 7 'Allocated resources'

ノードの追加に失敗したイベントに次のような内容があれば、vCPU クォータ不足です。

OperationNotAllowed: Operation could not be completed as it results in exceeding approved standardDDSv4Family Cores quota.
Location: japaneast, Current Limit: 10, Current Usage: 8, Additional Required: 4, (Minimum) New Limit Required: 12.
curl
# クォータの使用量と上限
az vm list-usage --location <リージョン> -o table

# クォータ申請の履歴(quota 拡張が必要: az extension add --name quota)
az quota request list --scope /subscriptions/<サブスクリプション ID>/providers/Microsoft.Compute/locations/<リージョン>

デプロイスクリプトのログ​

インストーラーは Azure のデプロイスクリプト(postDeploy- で始まる名前)として管理リソースグループ内で実行されます。ログはスクリプトの終了から 1 日で消えます。

curl
az deployment-scripts list --resource-group <管理リソースグループ> -o table
az deployment-scripts show-log --resource-group <管理リソースグループ> --name <スクリプト名>

init-platform の状態​

curl
# Job が Complete なら realm は作られている
kubectl get jobs -n librechat-auth

# realm の有無を直接確かめる(200 なら有り、404 なら無し)
kubectl port-forward -n librechat-auth svc/keycloak-extensions-keycloakx-http 18080:8080 &
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18080/realms/agenticstar

途中で止まった環境の復旧​

導入が途中で止まった環境は、原因を直したうえで、マネージドアプリケーションを削除して作り直します。マネージドアプリケーションを削除すると、管理リソースグループ(AKS・PostgreSQL・ストレージなど)がまとめて削除されます。削除せずに残しておくと、作成済みのリソースの利用料が発生し続けます。

  1. 原因を調べる(上記)。vCPU クォータ不足なら、Azure クイックスタートの vCPU クォータを参考に、申請して上限を上げる。ファミリーによっては申請が自動承認されないため、その場合は既定の Standard_E4ds_v5 を使う
  2. Azure ポータルでマネージドアプリケーションを削除する
  3. Azure クイックスタートの手順で、見直した設定値でもう一度購入してデプロイする
  4. デプロイ後に導入の確認を行う
注記

失敗した環境でデプロイを「再デプロイ」したり、インストーラーを再実行したりする方法は提供していません。インストーラーは実行のたびに鍵やパスワードを生成するため、同じクラスターでやり直すと導入済みのコンポーネントと値が食い違います。

AWS の場合​

AWS Marketplace から導入した環境は、CloudFormation のスタックで作られます。インストールが失敗すると、スタックは失敗としてロールバックされ、作成済みのリソース(EKS クラスターを含む)の多くは削除されます。ただし、S3 バケットは中身があるため残る場合があります。

失敗の理由を見る​

  1. CloudFormation コンソールでスタックを開き、Events タブで最初に失敗したリソースを探します。インストールの完了を待つリソース(WaitCondition)は、ネストしたスタック(SetupHelperStack)の中にあります。親のスタックの Events に SetupHelperStack の失敗が出ているときは、そのネストしたスタックを開いて、その Events を見ます
  2. インストールで失敗した場合は、ネストしたスタックの WaitCondition の理由に、インストーラーの最後の出力が表示されます。止まったリリースの名前やエラーのメッセージを確認してください
  3. インストーラーの出力の全体は、スタックが作ったプライベートの S3 バケットの install-logs/ に保存されます。ロールバックやスタックの削除の後も、バケットが残っていれば読めます

ノードを増やせないことが原因のときは、AWS クイックスタートの EC2 vCPU クォータを確認してください。

復旧する​

原因(vCPU クォータの不足など)を直してから、スタックを削除します。作り直す前に、残った S3 バケットが無いかを確かめ、要らなければ空にしてから削除してください(バージョニングが有効なので、古いバージョンも消します)。そのうえで、AWS クイックスタートの手順で作り直してください。失敗したスタックに対する手作業での復旧や、インストーラーの再実行は提供していません。

導入後に調べる​

導入が完了した後の環境では、Azure と同じく HELM_DRIVER=configmap helm list -A と kubectl で導入の進み具合と調べ方の手順を使えます。クラスターへの接続は aws eks update-kubeconfig --region <リージョン> --name <EKS クラスター名> で行います。

導入後にノードの空きが足りないとき​

導入は完了したが、エージェントの実行が増えて Pod が Pending になる場合は、オートスケーラーがノードを足せるだけの vCPU クォータがあるかを確認してください。既定の VM ファミリーのクォータを上げられない場合は、別のファミリーのノードプールを追加できます。

curl
RG=<管理リソースグループ>
AKS=<AKS Cluster Name>

# 既存の User Pool(apppool)と同じサブネット・ゾーンを使う
SUBNET=$(az aks nodepool show -g $RG --cluster-name $AKS --name apppool --query vnetSubnetId -o tsv)
ZONES=$(az aks nodepool show -g $RG --cluster-name $AKS --name apppool --query availabilityZones -o tsv | tr '\n' ' ')

# 例: Standard_E8ds_v5 のノードプールを追加(OS ディスクなどは既存の User Pool に合わせる)
az aks nodepool add -g $RG --cluster-name $AKS --name extrapool \
--mode User --node-vm-size Standard_E8ds_v5 --zones $ZONES \
--enable-cluster-autoscaler --min-count 1 --max-count 2 --node-count 1 \
--os-sku Ubuntu --node-osdisk-type Managed --node-osdisk-size 128 --max-pods 110 \
--vnet-subnet-id "$SUBNET"

ノードが追加されると、Pending だった Pod は自動的に配置されます。