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

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

> **注記**
>
> この手引きのコマンドと画面は Azure のものです。AWS で導入した場合は、[AWS の場合](#aws)を参照してください。

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

## 症状から原因を探す

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

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

### クラスターに接続する

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

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

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

```bash
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」「管理画面が開かない」の両方が起きます。

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

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

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

## 調べ方

### Pod が Pending の理由

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

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

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

```bash
# オートスケーラーの状態
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 クォータ不足です。

```text
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.
```

```bash
# クォータの使用量と上限
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 日で消えます。

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

### init-platform の状態

```bash
# 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 クォータ](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/quickstart/quickstart-azure.md#vcpu-quota)を参考に、申請して上限を上げる。ファミリーによっては申請が自動承認されないため、その場合は既定の Standard\_E4ds\_v5 を使う
2. Azure ポータルでマネージドアプリケーションを削除する
3. [Azure クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/quickstart/quickstart-azure.md)の手順で、見直した設定値でもう一度購入してデプロイする
4. デプロイ後に[導入の確認](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/quickstart/quickstart-azure.md#verify-deployment)を行う

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

## AWS の場合

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

### 失敗の理由を見る

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

ノードを増やせないことが原因のときは、[AWS クイックスタートの EC2 vCPU クォータ](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/quickstart/quickstart-aws.md#vcpu-quota)を確認してください。

### 復旧する

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

### 導入後に調べる

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

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

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

```bash
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 は自動的に配置されます。
