Azure Container Appsでの一般的なデプロイ エラーのトラブルシューティング

この記事は、Azure Container Appsでサポートエスカレーションが最も頻繁に必要な展開エラーシナリオを特定して解決するのに役立ちます。 各シナリオには、症状、ポータルと CLI の診断手順、および解決策が含まれます。

クイック リファレンス テーブルで症状を見つけ、一致するシナリオへのリンクに従います。

症状のクイック リファレンス

確認箇所: 診断画面

次の診断画面を使用して、デプロイの失敗を調査します。

イメージ プル エラー

イメージ プルエラーは、デプロイ エラーの最も一般的な原因の 1 つです。 これらは通常、Azure Container Appsが使用可能なリビジョンを作成する前に発生します。

Symptoms

• リビジョンは作成されませんでした。
• provisioningState は Failedです。
• エラー メッセージには、 ImagePullBackOff、 UNAUTHORIZED、または manifest unknownが記載されています。

検索する場所: イメージ プル診断

# Check app-level provisioning state and error
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "{provisioning:properties.provisioningState, error:properties.provisioningError, latestRevision:properties.latestRevisionName}" -o json

# List revisions (expect empty or failed)
az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "[].{name:name, health:properties.healthState, provisioning:properties.provisioningState}" -o table

一般的な原因と解決策

コンテナーのクラッシュと起動エラー

このセクションは、リビジョンが作成されていても、ワークロードの開始または実行の維持に失敗する場合に使用します。

Symptoms

• リビジョンは作成されますが、 healthState は Unhealthy となります。
• runningState は Failedです。
• コンソール ログが空の場合があります (出力を書き込む前にコンテナーが終了します)。

検索する場所: クラッシュ診断とスタートアップ診断

# Inspect revision detail
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "{health:properties.healthState, running:properties.runningState, details:properties.runningStateDetails, error:properties.provisioningError}" -o json

# Pull console logs (if any output was written)
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100

# Pull system logs for platform-level events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

一般的な原因と解決策

シークレット アクセスの問題

このセクションでは、実行時にアプリケーションの構成を中断するシークレット値が見つからないか空の場合のトラブルシューティングを行います。

Symptoms

• コンテナーが起動しますが、予期される構成値が空か不足しているため、アプリケーションは失敗します。
• シークレットを参照する環境変数には値がありません。

検索する場所: シークレット参照診断

# List secrets defined on the app
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table

# Show the revision template to verify env var references
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "properties.template.containers[].env" -o json

一般的な原因と解決策

Key Vault参照エラー

このセクションは、Key Vaultに基づくシークレットがデプロイ中またはアプリの実行中に解決できない場合に使用します。

Symptoms

• デプロイが失敗するか、シークレット値が使用できません。
• システム ログには、Key Vault へのアクセス エラーが記録されています。
• provisioningErrorでは、Key Vaultに対する認証または承認の失敗について説明します。

確認場所: Key Vault のアクセス診断

# List secrets and check for Key Vault reference status
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json

# Verify managed identity is assigned
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>

一般的な原因と解決策

マネージド ID の構成ミス

このセクションは、マネージド ID を使用するようにアプリが構成されていても、サービスAzure認証が失敗する場合に使用します。

Symptoms

• アプリケーション コードは、Azure サービスを呼び出すときに 401 (未承認) または 403 (禁止) を受け取ります。
• マネージド ID トークンの取得が失敗する。

検索する場所: ID と承認の診断

# Verify identity configuration
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>

# Check role assignments for the identity's principal ID
az role assignment list --assignee <PRINCIPAL_ID> --all -o table

一般的な原因と解決策

初期化のタイミングに関する問題

このセクションは、メイン コンテナーがトラフィックの提供を開始する前に、init コンテナーが起動または失敗をブロックする場合に使用します。

Symptoms

• アプリが実行中の状態に達することはありません。
• Init コンテナーがスタックしているか失敗しているようです。
• システム ログには、実行中の init コンテナーが表示されますが、完了しません。

確認場所: init コンテナーの診断情報

# Check revision running state
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "{running:properties.runningState, details:properties.runningStateDetails}" -o json

# Check init container logs
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --container <INIT_CONTAINER_NAME> --tail 100

# System logs for platform events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

一般的な原因と解決策

正常性プローブのエラー

このセクションは、リビジョンのデプロイは正常に完了したものの、プローブ チェックの結果、正常でない、またはパフォーマンスが低下していると判定された場合に使用します。

Symptoms

• リビジョンはプロビジョニングされますが、実行中の状態は Degraded。
• システム ログには、プローブエラーの詳細を含む Unhealthy イベントが表示されます。
• アプリはローカルで動作しますが、ACA の正常性チェックに失敗します。

確認場所: プローブの正常性診断

# Check the revision's probe configuration
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "properties.template.containers[].probes" -o json

# System logs for probe failure events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

一般的な原因と解決策

既定のプローブ値

イングレスを有効にし、プローブを構成しない場合、ACA は次の既定値を適用します。

イングレスとトラフィック のルーティングに関する問題

このセクションは、アプリが実行されているが、イングレスまたはリビジョン のトラフィック設定が正しくないために要求が失敗する場合に使用します。

Symptoms

• アプリは実行中で正常ですが、HTTP 要求はエラー (404、502) を返すか、応答を返しません。
• アプリは az containerapp exec 経由で動作しますが、パブリック URL 経由では動作しません。

確認箇所: イングレスとトラフィック診断

# Check ingress configuration and traffic split
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "{ingress:properties.configuration.ingress, latestReady:properties.latestReadyRevisionName}" -o json

# Verify the FQDN
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --query "properties.configuration.ingress.fqdn" -o tsv

一般的な原因と解決策

コンテナー レジストリ認証

このセクションは、アプリがコンテナー レジストリに対して認証できないためにイメージプルが失敗する場合に使用します。

Symptoms

• デプロイは UNAUTHORIZED: authentication requiredで失敗します。
• このエラーは、多くの場合、他の問題 (無効なイメージ タグなど) をマスクします。これは、レジストリがタグを確認する前に要求を拒否するためです。

参照する場所: レジストリ認証の診断

# Check configured registries
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "properties.configuration.registries" -o json

# Verify ACR credentials work
az acr login --name <AZURE_CONTAINER_REGISTRY_NAME>
docker pull <AZURE_CONTAINER_REGISTRY_NAME>.azurecr.io/<REPOSITORY_NAME>:<TAG>

一般的な原因と解決策

診断ワークフローの概要

何が失敗したかわからない場合は、次のシーケンスを使用します。

1. az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json を実行します。 provisioningState、provisioningError、およびlatestRevisionNameを確認します。

2. az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table を実行します。 一覧が空の場合、エラーはイメージ プルまたはテンプレート検証の問題です (イメージ プルエラーとコンテナー レジストリ認証)。 リビジョンが存在する場合は、手順 3 に進みます。

3. az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> -o json を実行します。 healthState、runningState、runningStateDetails、およびprovisioningErrorを確認します。

4. az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50を実行して、プローブの失敗、ID エラー、シークレット同期の問題などのプラットフォーム レベルのイベントを表示します。

5. az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100を実行して、スタック トレース、構成エラー、接続エラーなどのアプリケーション stdout/stderr を表示します。

6. 前の手順で認証関連のエラーが発生した場合は、 az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> を実行して ID 構成を確認します。

ポータルで問題の診断と解決を使用する

Log Analyticsクエリを使用して詳細な調査を行う

CLI の出力とポータルの診断が十分でない場合は、Log Analyticsで基になるログに直接クエリを実行します。 次の 2 つのクエリでは、プラットフォーム レベルのエラーとイングレス レベルの HTTP エラーの最も一般的な開始点について説明します。

システム レベルの障害を見つける

ContainerAppSystemLogs_CL
| where RevisionName_s == "<REV>"
| where Log_s contains "BackOff" or Log_s contains "Failed" or Log_s contains "Error"
  or Reason_s == "Unhealthy"
| project TimeGenerated, Reason_s, Log_s
| order by TimeGenerated desc
| take 50

このクエリでは、イメージのプル エラー、プローブエラー、プロビジョニング エラー、およびその他のプラットフォーム イベントが表示されます。

HTTP エラーを見つける (HTTP ログが有効になっている必要があります)

Ingress レイヤーは HTTP ログを出力し、それらを有効にするかどうかは選択できます。 Container Apps マネージド環境の Azure Monitor の診断設定で、これらのログを有効にします。 有効にすると、ContainerAppHTTPLogsテーブルがLog Analyticsに表示されます。 テーブルが表示されるまでに数分かかる場合があります。

ContainerAppHTTPLogs
| where TimeGenerated > ago(1h)
| where StatusCode >= 400
| project TimeGenerated, ContainerAppName, RevisionName, Method, Path,
  StatusCode, ResponseCodeDetails, RequestDuration, RequestId
| order by TimeGenerated desc
| take 100

このクエリでは、イングレスレイヤーの HTTP ログがフィルター処理され、過去 1 時間の失敗した要求 (状態コード 400 以上) のみが表示されます。 タイムスタンプ、アプリとリビジョン名、HTTP メソッドとパス、エラー状態コード、エラーがコンテナー (ResponseCodeDetails) またはプラットフォーム (via_upstream、route_not_found)、要求期間、およびアプリケーション ログとの関連付けに使用できる一意の要求 ID を示すconnection_timeout フィールドが返されます。

低速な要求分析、リビジョンごとのエラー率、単一要求トレース、失敗した上位のエンドポイントなど、その他のクエリについては、「Log Analyticsを使用してAzure Container Appsのログを監視する」を参照してください。

関連するコンテンツ

• コンテナー アプリのトラブルシューティング
• Azure Container Apps でシークレットを管理する
• Azure Container Apps でのマネージド ID
• Azure Container Appsでのヘルスプローブ
• Azure Container Apps でのイングレス
• Log Analytics を使用して Azure Container Apps のログを監視する