構築トラブルシューティングガイド
マーケットプレイスからの導入(マネージドアプリケーションのデプロイ)が途中で止まったときに、何が起きているかを調べ、復旧するための手引きです。インフラの構築後に行われるアプリケーションのインストールは、コンポーネントを決まった順序で 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 クイックスタート) |
導入の進み具合を調べる
クラスターに接続する
# リソースグループはマネージドアプリケーションの管理リソースグループ(名前は mrg- で始まる)
az aks get-credentials --resource-group <管理リソースグループ> --name <AKS Cluster Name>
Helm リリースの一覧を見る
マーケットプレイス版は Helm のストレージドライバに configmap を使っています。HELM_DRIVER=configmap を付けないと何も表示されません。
HELM_DRIVER=configmap helm list -A
インストーラーは次の順序でリリースを導入します。一覧の UPDATED の時刻を順に並べると、どこまで入ったかが分かります。STATUS が failed のリリースが止まった所です。
| 順 | リリース名 | 名前空間 | 役割 |
|---|---|---|---|
| 1 | prometheus-operator | monitoring | 監視基盤 |
| 2 | prometheus-adapter | monitoring | 監視基盤 |
| 3 | ingress-nginx | ingress-nginx | 入口(LoadBalancer) |
| 4 | cert-manager | cert-manager | 証明書 |
| 5 | qdrant | qdrant | ベクトルデータベース |
| 6 | db-migration | db-migration | データベースの初期化 |
| 7 | extauth-service | proxy-system | 認証プロキシ |
| 8 | gate-services | gate-services | LLM ゲートウェイ |
| 9 | mail-ingress | mail-ingress | メール受信 |
| 10 | agent-sandbox-controller | agent-sandbox-system | エージェント実行基盤 |
| 11 | agent-executor | agent-executor | エージェント実行 |
| 12 | agenticai-extapi | agenticai-extapi-service | 外部 API |
| 13 | agenticai-datadog | agenticai-datadog | Datadog 連携 |
| 14 | pvc-lifecycle-manager | pvc-lifecycle-manager | ストレージ管理 |
| 15 | librechat-auth | librechat-auth | 認証サービス |
| 16 | keycloak-extensions | librechat-auth | 認証基盤(Keycloak) |
| 17 | librechat | agentic-star-front | メイン画面 |
| 18 | agenticai-admin | agentic-star-admin | 管理画面 |
| 19 | loki | observability | ログ基盤 |
| 20 | alloy-logs | observability | ログ収集 |
| 21 | alloy-metrics | observability | メトリクス収集 |
| 22 | k8s-monitoring | observability | 監視 |
| 23 | agenticai-observability | observability | 監視 |
| 24 | init-platform | librechat-auth | 認証基盤の初期設定(realm・クライアント・初期管理者の作成) |
| 25 | upgrade-controller | upgrade-controller | バージョン管理 |
AWS では、1 番目の前に、ノードを自動で増減する cluster-autoscaler(名前空間 kube-system)が入ります(全部で 26 リリース)。
たとえば 17 番目のメイン画面(librechat)で止まると、管理画面・ログ基盤・init-platform が入らないため、「ログインで Realm not found」「管理画面が開かない」の両方が起きます。
失敗したリリースの理由を見る
HELM_DRIVER=configmap helm history <リリース名> -n <名前空間>
DESCRIPTION に失敗の理由が出ます。context deadline exceeded は、待ち時間内に Pod が起動しなかったことを示します(多くは Pod が Pending のまま)。
調べ方
Pod が Pending の理由
# Running / Completed 以外の Pod を探す
kubectl get pods -A | grep -v -E 'Running|Completed'
# Events に理由が出る(Insufficient cpu / Insufficient memory など)
kubectl describe pod <Pod 名> -n <名前空間>
ノードを増やせない理由
# オートスケーラーの状態
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.
# クォータの使用量と上限
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 日で消えます。
az deployment-scripts list --resource-group <管理リソースグループ> -o table
az deployment-scripts show-log --resource-group <管理リソースグループ> --name <スクリプト名>
init-platform の状態
# 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・ストレージなど)がまとめて削除されます。削除せずに残しておくと、作成済みのリソースの利用料が発生し続けます。
- 原因を調べる(上記)。vCPU クォータ不足なら、Azure クイックスタートの vCPU クォータを参考に、申請して上限を上げる。ファミリーによっては申請が自動承認されないため、その場合は既定の Standard_E4ds_v5 を使う
- Azure ポータルでマネージドアプリケーションを削除する
- Azure クイックスタートの手順で、見直した設定値でもう一度購入してデプロイする
- デプロイ後に導入の確認を行う
失敗した環境でデプロイを「再デプロイ」したり、インストーラーを再実行したりする方法は提供していません。インストーラーは実行のたびに鍵やパスワードを生成するため、同じクラスターでやり直すと導入済みのコンポーネントと値が食い違います。
AWS の場合
AWS Marketplace から導入した環境は、CloudFormation のスタックで作られます。インストールが失敗すると、スタックは失敗としてロールバックされ、作成済みのリソース(EKS クラスターを含む)の多くは削除されます。ただし、S3 バケットは中身があるため残る場合があります。
失敗の理由を見る
- CloudFormation コンソールでスタックを開き、Events タブで最初に失敗したリソースを探します。インストールの完了を待つリソース(WaitCondition)は、ネストしたスタック(
SetupHelperStack)の中にあります。親のスタックの Events にSetupHelperStackの失敗が出ているときは、そのネストしたスタックを開いて、その Events を見ます - インストールで失敗した場合は、ネストしたスタックの WaitCondition の理由に、インストーラーの最後の出力が表示されます。止まったリリースの名前やエラーのメッセージを確認してください
- インストーラーの出力の全体は、スタックが作ったプライベートの 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 ファミリーのクォータを上げられない場合は、別のファミリーのノードプールを追加できます。
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 は自動的に配置されます。