メインコンテンツへスキップ

トラブルシューティング FAQ

AWSops ダッシュボードの使用中に発生し得る問題と解決方法です。AWSops は ECS Fargate 上で動作する Next.js thin-BFF であり、すべてのライブ AWS 照会は AgentCore MCP ツールを通じて行われ、状態は Aurora（PostgreSQL）に保存されます。ほとんどの問題は、接続経路（エッジ）、認証（Cognito）、データ接続（Aurora・権限）のいずれかに分類されます。

サイトが 504 または接続不能です​

CloudFront が応答しない、あるいは 504 Gateway Timeout が発生する場合、エッジ経路（CloudFront → VPC Origin → 内部 ALB → Fargate）のどこかで接続が切れています。AWSops には公開 ALB がないため、点検の順序は次のとおりです。

  1. Fargate タスクの状態 — ECS サービスのタスクが RUNNING で、ターゲットグループで healthy かを確認します。タスクが UNHEALTHY で循環している場合は、下記の「ECS タスクが UNHEALTHY」の項目を参照してください。
  2. TLS end-to-end — CloudFront → ALB 区間は TLS が途切れずにつながっている必要があります。VPC Origin が https-only（443）で、Origin ドメインが公開 FQDN（例：awsops.example.com）に設定され、SNI が ALB 証明書と一致していなければなりません。
  3. ALB 証明書 / リスナー — 内部 ALB は HTTPS:443 + リージョン ACM 証明書でリスニングする必要があります（CloudFront の証明書は us-east-1 ですが、ALB はリージョン ACM です）。
  4. ALB セキュリティグループ — 最も多い 504 の原因です。ALB SG は CloudFront マネージドセキュリティグループ CloudFront-VPCOrigins-Service-SG からの 443 を許可する必要があります。VPC CIDR のみを許可するとトラフィックが遮断され 504 が発生します。
ヒント

504 はほぼ常に ALB SG が CloudFront マネージド SG を許可していないことが原因で発生します。VPC-CIDR-only のルールは動作しません。CloudFront マネージド SG（CloudFront-VPCOrigins-Service-SG）からの 443 インバウンドが許可されているかを最初に確認してください。

情報

VPC Origin のプロトコルは in-place では変更できません。https-only 設定を変更するには、Terraform で create_before_destroy + リソース置換（-replace）が必要です。

ログインできません​

AWSops はセルフホストのログインフォーム（/login）を使用します。未認証の状態で保護されたページにアクセスすると、エッジ（Lambda@Edge）が自動的に /login へリダイレクトします。

  1. ログインフォームの使用 — /login でユーザー名とパスワードを入力すると、BFF（POST /api/auth/login）が Cognito の InitiateAuth(USER_PASSWORD_AUTH) を呼び出し、成功すると awsops_token クッキー（id_token、12 時間有効）を発行します。
  2. 認証情報のエラー — ユーザー名/パスワードが間違っているか、ユーザーが Cognito User Pool に存在しない場合、ログインは拒否されます。パスワードのリセットやユーザー作成は管理者に依頼してください。
  3. クッキーの確認 — ログインはできたのに /login に戻され続ける場合は、awsops_token クッキーが正しく設定されているかを確認します。クッキーは HttpOnly のため JavaScript では読めません。ブラウザの開発者ツール → Application → Cookies で確認してください。期限切れ（12 時間）であれば再ログインすれば解決します。
  4. ログアウト後の再ログイン — セッションが不整合になった場合は、ログアウト（クッキー削除 → /login）してから再度ログインしてください。別途 Hosted UI /logout の往復はありません。
情報

エッジは単純な有効期限チェックではなく、RS256 JWKS 署名検証（iss/aud/token_use を含む）を実行します。トークンが偽造されていたり、別の User Pool から発行されたものであれば拒否されます。Cognito Hosted UI PKCE フロー（/_callback）はダークフォールバックとしてのみ残っており、通常のログインは /login フォームを使用します。

管理者画面（設定・カスタマイズ）にアクセスすると 403 が出ます​

管理者機能は、ログインの有無とは別にサーバー側の管理者ゲートでもう一段保護されています。次のいずれかを満たす必要があります。

  • ログインユーザーが Cognito の admins グループに属している、または
  • ユーザーのメールアドレスが SSM の管理者メール許可リストに含まれている。

両方とも空の場合、すべてのユーザーが fail-closed で 403 を受け取ります（安全なデフォルト）。管理者グループにユーザーを追加するか、SSM の許可リストにメールアドレスを登録すれば解決します。

データが表示されません​

データが空に見える原因は大きく 3 つあります：(a) アプリ状態を保持する Aurora に接続できていない、(b) ライブ AWS 照会の権限不足、(c) インベントリ同期の未実行。

  1. セッション/認証の確認 — まずログインセッションが有効かを確認してください。トークンが期限切れになると API 呼び出しが拒否され、画面が空に見えることがあります（上記の「ログインできません」を参照）。
  2. Aurora 接続の確認 — チャットスレッド、診断レポート、ジョブキューなど、アプリの状態はすべて Aurora に保存されます。/api/db ヘルスチェックで DB ping が正常かを確認してください。失敗する場合は DB 自体、またはネットワーク/シークレットの問題です。
  3. ライブ AWS 照会の権限 — EC2/IAM のようなリアルタイム AWS データは AgentCore MCP ツール（読み取り専用）を通じて照会します。特定のセクションだけが空の場合、そのサービスの Describe*/List* 権限がブロックされている可能性があります（SCP/IAM）。Cost データには Cost Explorer の権限、メトリクスには CloudWatch の権限が必要です。
  4. インベントリ同期 — インベントリページの表が空の場合、インベントリ同期（steampipe_enabled フラグ、デフォルト OFF）が実行されていない可能性があります。インベントリ同期は独立したバッチ同期機能であり、ライブ照会（MCP）とは独立しています。
ヒント

「特定のページだけ」が空の場合 → そのサービスの AWS API 権限（SCP/IAM）の問題である可能性が高いです。「すべてのページ」が空の場合 → セッション期限切れまたは Aurora 接続の問題である可能性が高いです。

SCP によるブロックで一部のデータが欠落します​

SCP（Service Control Policy）や IAM 境界により特定の AWS API がブロックされると、該当するデータのみが部分的に欠落することがあります。

ブロックされた API の例影響
iam:ListMFADevicesMFA 状態の照会不可
ce:GetCostAndUsageCost データの照会不可
cloudwatch:GetMetricDataメトリクス/グラフの照会不可

AWSops は読み取り専用のため、ブロックされた API については該当項目を空の値として表示し、残りは正常に動作します。欠落したデータが必要な場合は、その API への読み取り権限を追加してください。権限を変更せずに自然言語で部分的な照会が可能な場合は、AI アシスタントに質問すれば利用可能な範囲のデータで回答します。

ページの読み込みが遅いです​

AWSops の Web は ECS Fargate 上で事前ビルドされた standalone イメージとして実行されます。ホスト上で npm run dev で動いていたレガシーとは異なり、ランタイムに別途のビルドステップが介在しません。それでも特定のページが遅い場合は、次を確認してください。

  1. 重い作業は非同期ワーカーへ — 長時間/大容量/OOM リスクのある作業（例：AI 総合診断、レポートのエクスポート）は Web が直接処理せず、非同期ワーカーキューへ enqueue されます。画面にはジョブの状態が表示され、完了後に結果が埋められます。即座に応答しないのが正常です。
  2. ライブ AWS 照会の遅延 — Cost Explorer や CloudWatch のような AWS API は応答が遅いことがあります（数十秒単位）。この場合、画面は正常ですがデータが埋まるまで時間がかかります。
  3. 新しいタスクのローリング — デプロイ直後（make deploy による ECS ローリング中）は一時的に応答が遅くなることがあります。ローリングが終わり /api/health が安定すれば正常化します。

ECS タスクが UNHEALTHY で循環します（オペレーター向け）​

デプロイ後に Fargate タスクが UNHEALTHY になり続け、circuit breaker でロールバックされる場合、ほぼ常に次の 3 つのいずれかです。

  1. HOSTNAME=0.0.0.0 ランタイム env の欠落 — Next.js standalone をコンテナとしてデプロイする際は、タスク定義の environment に HOSTNAME=0.0.0.0 を明示する必要があります。イメージ ENV だけでは不十分です — ECS が HOSTNAME を ENI IP で上書きすると、アプリが 0.0.0.0/loopback にバインドされず、ヘルスチェックが失敗します。
  2. ヘルスチェックパスの不一致 — コンテナとターゲットグループのヘルスチェックパスは、アプリの /api/health と正確に一致する必要があります。不一致の場合、circuit breaker のループが発生します。
  3. Fargate ワーカーの Dockerfile は CMD（ENTRYPOINT 禁止） — Fargate ワーカーイメージは CMD を使用しなければなりません。exec-form の ENTRYPOINT を使うと、Step Functions の containerOverrides.command が ENTRYPOINT に append されて argv が重複し、argparse が失敗します。
ヒント

最も多い原因は、HOSTNAME=0.0.0.0 をイメージではなくタスク定義のランタイム env として明示していないことです。ヘルスチェックが即座に失敗する場合は、この項目から確認してください。

ECS タスクが起動時に ResourceInitializationError を出します（オペレーター向け）​

タスクが起動すらできず ResourceInitializationError で失敗する場合は、Aurora シークレットを注入する secrets valueFrom の権限問題です。

ECS の secrets valueFrom（Aurora シークレットなど）には**実行ロール（execution role）**の権限が必要です — task role ではありません。実行ロールに該当シークレットに対する secretsmanager:GetSecretValue 権限があるかを確認してください。

AI 総合診断が失敗するか止まります​

AI 診断は Web が直接実行するのではなく、非同期ワーカーティアがバックグラウンドで生成する読み取り専用レポートです（Light·Mid 8+1 セクション（計 9） / Deep 15+1 セクション（計 16））。したがって「応答がない」ことが即「失敗」ではありません。

  1. まずジョブの状態を確認 — 診断をリクエストするとジョブがキューに登録され、ワーカーが処理します。レポート画面のジョブ状態（queued → running → succeeded/failed）を確認してください。running であれば正常に進行中です。
  2. failed で終わった場合 — ワーカーが失敗すると状態が failed として記録されます。同じ診断を再度リクエストすれば再試行されます（ジョブは job_id 基準で冪等）。
  3. deep + Opus モデル — deep 診断（15+1 セクション）で Opus モデルを選択するとコストゲートが適用され、時間もより長くかかります。すばやく確認したい場合は、デフォルトの Sonnet で Light/Mid 診断を使用してください。
  4. データ権限 — 診断はライブ AWS データを読み取るため、ブロックされた API（Cost/CloudWatch など）のセクションはデータが空に見えることがあります（上記の「SCP によるブロック」を参照）。これは診断自体の失敗ではなく、データ可用性の問題です。
情報

長時間止まっている（stale）ジョブは、reaper（5 分周期）が自動的に整合化します。ワーカーが死んで状態が更新されないジョブも、最終的には failed として整理されます — 長く待っても succeeded にならない場合は再試行してください。

AI アシスタントの応答がおかしい、または権限エラーが出ます​

AI アシスタントは読み取り専用ツール（約 160 個）でライブ AWS データを照会し、会話は Aurora に保存されます。

  1. 読み取り専用の動作 — AWSops は AWS リソースを変更しません。「リソースを修正/削除してほしい」というリクエストは拒否されるか、診断/案内のみで応答するのが正常です（恒久的な read-only ポリシー）。
  2. 権限エラー — 特定の照会が AccessDenied で失敗する場合、そのサービスの読み取り権限がブロックされています。ブロックされた範囲は回答から除外され、利用可能なデータのみで応答します。
  3. 会話が消えた — 会話は Aurora に永続化されており、サイドバーから再度開くことができます。表示されない場合は、セッション（ログイン）が変わったか期限切れになった可能性があります。

データソース（Prometheus/Loki など）に接続できません​

/datasources の読み取り専用コネクタ（Prometheus・Loki・Tempo・ClickHouse・Mimir など）は、コネクタ Lambda を通じて外部オブザーバビリティバックエンドを照会します。

  1. エンドポイントへの到達性 — コネクタが該当エンドポイントにネットワークで到達できる必要があります。private エンドポイントには VPC 経路が必要です。
  2. SSRF ガード — コネクタの入力には SSRF 防御が適用されます。メタデータ/IMDS アドレスなど内部アドレスへの接続は遮断されます。社内の内部アドレスを指すとブロックされることがあります。
  3. 認証情報 — 認証が必要なバックエンドは、Secrets Manager に保存された認証情報を使用します。401/403 が出る場合はシークレットが正しいかを確認してください。
  4. レスポンスサイズ — コネクタの入力にはサイズ制限があります（パース前に bound を適用）。過度に大きいペイロードは拒否されます。

通知が外部（Slack/チケット）へ届きません​

外部への記録/チケット/メッセージの書き込みはガバナンスの下で動作するオプション機能であり、デフォルトではフラグ OFF の場合があります。

  1. 機能の有効化状況 — 外部書き込みはガバナンス（宛先許可リスト・シークレット・DLP/マスキング・ヒューマンゲート・フラグ）を前提とします。無効の状態ではメッセージは送信されません。
  2. 宛先許可リスト — 宛先（チャンネル/エンドポイント）が許可リストにない場合、送信は遮断されます。
  3. 認証情報 — 外部サービスのトークン/Webhook は Secrets Manager に保存されます。期限切れやタイプミスがあると送信が失敗します。
情報

外部書き込みは**データレコード（メッセージ・チケット）**の作成であり、AWS リソースの変更ではありません。AWS リソースの変更と自律実行は恒久的に凍結されています。