Azure Container Apps 일반적인 배포 오류 문제 해결

이 문서는 Azure Container Apps 지원 에스컬레이션이 가장 자주 필요한 배포 실패 시나리오를 식별하고 해결하는 데 도움이 됩니다. 각 시나리오에는 증상, 포털 및 CLI 진단 단계 및 해결 방법이 포함됩니다.

빠른 참조 테이블에서 증상을 찾고 일치하는 시나리오에 대한 링크를 따릅니다.

증상 빠른 참조

확인할 위치: 진단 관련 화면

다음 진단 화면을 사용하여 배포 실패를 조사합니다.

이미지 끌어오기 실패

이미지 끌어오기 실패는 배포 오류의 가장 일반적인 원인 중 하나입니다. 일반적으로 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. 이전 단계에서 인증 관련 오류가 나타난 경우 ID 구성을 확인하려면 실행 az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> 합니다.

포털에서 진단 및 문제 해결 사용

심층 조사를 위한 Log Analytics 쿼리

CLI 출력 및 포털 진단이 충분하지 않은 경우 Log Analytics 직접 기본 로그를 쿼리합니다. 다음 두 쿼리는 플랫폼 수준 오류 및 수신 수준 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 로그를 사용하도록 설정해야 함)

인그레스 계층은 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_upstreamroute_not_found,connection_timeout), 요청 기간 및 애플리케이션 로그와 상관 관계를 지정하는 데 사용할 수 있는 고유한 요청 ID에서 발생했는지 여부를 나타내는 필드를 반환합니다.

느린 요청 분석, 수정 버전별 오류 비율, 단일 요청 추적 및 최고 실패 엔드포인트를 비롯한 더 많은 쿼리는 Log Analytics Azure Container Apps 로그 모니터링을 참조하세요.

관련 콘텐츠

• 컨테이너 앱 문제 해결
• Azure Container Apps에서 비밀 관리
• Azure Container Apps의 관리형 ID
• Azure Container Apps의 상태 프로브
• Azure Container Apps의 수신
• Azure Container Apps에서 Log Analytics로 로그를 모니터링하기