이 가이드를 사용하여 흔히 발생하는 Azure Container Apps 배포 실패를 진단하고 수정하세요. 증상표부터 시작해서 해당 문제 해결 흐름도를 따라 진행하세요.
Tip
Azure 포털에는 일반적인 배포 문제에 대해 자동화된 감지기를 실행하는 문제 진단 및 해결 기능이 포함되어 있습니다. 이 글의 단계들과 함께 사용하세요. 탐지기 선택 방법에 대한 도움말은 Azure Container Apps의 문제 진단 및 해결 항목을 참조하세요.
증상부터 시작해
다음 표를 참고하여 문제 해결 경로를 선택하세요.
| 증상 | 가능한 원인 | 이동 |
|---|---|---|
| 환경 생성이 용량 오류로 실패합니다 | 제한된 지역 수용력 | 환경 용량 오류 문제 해결 |
| 배포에 실패하고 수정본이 생성되지 않습니다 | 이미지 또는 레지스트리 인증 문제 | 배포가 리비전 생성 전에 실패합니다 |
ImagePullBackOff 또는 UNAUTHORIZED 오류 |
이미지 태그 또는 레지스트리 자격 증명 | 배포가 리비전 생성 전에 실패합니다 |
CrashLoopBackOff 또는 컨테이너가 즉시 종료되는 경우 |
시작 시 충돌 | 컨테이너 충돌 및 시작 오류 |
리비전은 Degraded 준비된 복제본 0개인 상태입니다 |
건강 프로브 오류 | 헬스 프로브 실패 |
수정 사항은 Provisioning에 보관됩니다 |
컨테이너 또는 프로브 타이밍 | 초기화 타이밍 문제 |
| Secret 또는 환경 변수가 런타임에 비어 있습니다 | 비밀 참조 또는 동기화 문제 | 비밀 액세스 문제 |
| 관리형 ID에서 401 또는 403이 반환됨 | ID의 잘못된 구성 | 관리 ID 구성 오류 |
| 엔드포인트는 403 또는 502를 반환합니다 | 인그레스 또는 네트워킹 문제 | 요청이 실패하거나 예상치 못하게 동작함 |
올바른 로그 소스를 선택하세요
포털 진단이나 CLI 상태에서 근본 원인이 나타나지 않을 때는 로그를 사용하세요.
| 로그 형식 | 표시되는 내용 | 중요 세부 정보 |
|---|---|---|
| 시스템 로그 | 이미지 풀 상태, 프로브 결과, 식별 오류, 비밀 동기화 결과 등 플랫폼 수준 이벤트가 포함됩니다. | 복제본 범위 시스템 이벤트에는 복제본 식별자가 ContainerAppSystemLogs_CL의 ReplicaName_s 또는 ContainerAppSystemLogs의 ReplicaName와 같이 포함됩니다. |
| 콘솔 로그 | 스택 트레이스, 시작 메시지, 런타임 오류 등을 포함한 애플리케이션 stdout/stderr | 콘솔 로그에는 복제 수준 문제 해결을 위해 ContainerAppConsoleLogs_CL의 ContainerGroupName_s 또는 ContainerAppConsoleLogs의 ContainerGroupName가 포함됩니다. |
| HTTP 로그 | 상태 코드, 지연 시간, 경로, 응답 세부 정보를 포함한 인그레스 계층 요청 로그. | HTTP 로그에는 ReplicaName 필드가 포함됩니다. 환경 내 Azure Monitor 진단 설정을 통해 활성화하세요. |
배포가 리비전 생성 전에 실패합니다
플랫폼이 수정을 생성할 수 없을 때 이 섹션을 사용하세요. 이 실패는 보통 애플리케이션 코드가 실행되기 전 이미지 풀이나 레지스트리 인증 중에 발생합니다.
포털 상태 확인
Azure 포털에서 컨테이너 앱>구성>더 보기>수정 버전 & 복제본으로 이동합니다. 목록이 비어 있거나 실패한 항목이 나오면 이미지 가져오기나 템플릿 검증 실패를 확인하세요. 또한 자동 분석을 위해 문제 진단 및 해결에서 'image pull'을 검색할 수도 있습니다.
# 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 no revision or a failed revision.
az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
--query "[].{name:name, health:properties.healthState, provisioning:properties.provisioningState}" -o table
시스템 로그에서 이미지 풀 이벤트를 확인해 보세요
Azure 포털에서 컨테이너 앱>모니터링>로그 스트림으로 가서 시스템 로그를 선택하세요. 이미지 가져오기 오류를 찾아보세요.
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50
이미지 및 레지스트리 구성 검증
Azure 포털에서 컨테이너 앱>구성>컨테이너로 이동합니다. 이미지 이름, 태그, 레지스트리 설정을 확인하세요.
# Check configured registries
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
--query "properties.configuration.registries" -o json
# Verify that the image tag exists in your registry
az acr repository show-tags --name <AZURE_CONTAINER_REGISTRY_NAME> --repository <REPOSITORY_NAME>
# Verify that ACR credentials work
az acr login --name <AZURE_CONTAINER_REGISTRY_NAME>
docker pull <AZURE_CONTAINER_REGISTRY_NAME>.azurecr.io/<REPOSITORY_NAME>:<IMAGE_TAG>
일반적인 이미지 및 레지스트리 문제를 해결하기
| 이 조건이 표시되는 경우 | 이 동작을 수행하세요 |
|---|---|
manifest unknown 또는 tag not found |
정확한 이미지 태그가 레지스트리에 있는지 확인하세요. |
UNAUTHORIZED: authentication required |
레지스트리 자격 증명을 설정하세요. ACR pull에 관리 ID를 사용하려면 az containerapp registry set -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --server <AZURE_CONTAINER_REGISTRY_NAME>.azurecr.io --identity system을 실행하세요. |
name unknown 또는 DNS 해석 실패 |
--image 값이 올바른 <REGISTRY>.azurecr.io 호스트네임을 사용하는지 확인하세요. |
| 레지스트리 연결 시간 초과 | 커스텀 VNet을 사용할 경우, 반드시 아웃바운드 액세스를 보장하세요.
AzureContainerRegistry 서비스 태그 또는 FQDN 규칙을 추가합니다. |
UNAUTHORIZED 관리자 사용자가 구성된 상태 |
az acr update -n <AZURE_CONTAINER_REGISTRY_NAME> --admin-enabled true로 관리자 사용자를 활성화하거나 AcrPull 역할을 사용하여 관리형 ID로 전환하세요. |
UNAUTHORIZED 관리형 ID |
az role assignment create --role AcrPull --assignee <PRINCIPAL_ID> --scope <ACR_RESOURCE_ID>에 AcrPull 역할을 할당하세요. |
비고
레지스트리 속도 제한 및 이미지 풀 검증 동작을 포함한 이미지 풀 문제에 대한 자세한 지침은 이미지 풀 실패 문제 해결을 참조하세요.
수정 실패 또는 성능 저하
리비전이 생성되었지만 건강한 실행 상태에 도달하지 못할 때 이 섹션을 사용하세요. 원인은 컨테이너 충돌, 상태 프로브 실패 또는 초기화 타이밍 문제일 수 있습니다.
컨테이너 충돌 및 시작 오류
컨테이너가 시작되거나 즉시 종료되거나 크래시 루프에 들어갈 때 이 섹션을 사용하세요. 리비전은 존재하지만 트래픽을 처리할 수 없습니다.
수정 상태 확인
Azure 포털에서 컨테이너 앱>구성>더보기>수정 & 복제본으로 이동한 다음 실패한 버전을 선택하세요. 수정 세부 사항에서 BackOff 또는 CrashLoopBackOff 이벤트를 찾아보세요.
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME> \
--query "{health:properties.healthState, running:properties.runningState, details:properties.runningStateDetails, error:properties.provisioningError}" -o json
스택 트레이스가 있는지 콘솔 로그를 확인하세요
Azure 포털에서 컨테이너 앱>모니터링>로그 스트림으로 가서 콘솔 로그를 선택하세요. 스택 트레이스나 오류 메시지를 찾아보세요. 콘솔 로그에는 복제본 식별자, ContainerGroupName_s의 ContainerAppConsoleLogs_CL 또는 ContainerGroupName의 ContainerAppConsoleLogs가 포함되어 있어서 특정 복제본으로 필터링할 수 있습니다.
# Pull console logs if the app wrote output
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
컨테이너 구성 검증하기
Azure 포털에서 컨테이너 앱>구성>컨테이너로 가세요. 명령어, 인수, 환경 변수, 자원 제한을 확인하세요.
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME> \
--query "properties.template.containers[].{command:command, args:args, env:env, resources:resources}" -o json
일반적인 충돌 및 시작 문제 해결
| 이 오류를 보신다면 | 이 동작을 수행하세요 |
|---|---|
| 콘솔 로그의 스택 추적 | 애플리케이션 오류를 수정합니다. 로그가 비어 있으면 stdout이 플러시되기 전에 충돌이 발생합니다. 조기 로깅을 추가하거나 런타임에서 출력 버퍼링을 비활성화하도록 설정하세요. 예를 들어, PYTHONUNBUFFERED=1을(를) 설정하십시오. |
exec format error 또는 executable file not found |
컨테이너 command와 args가 이미지가 기대하는 것과 일치하는지 확인하세요. |
KeyError, undefined, 또는 널 참조 |
필요한 모든 환경 변수가 설정되어 있는지 확인하세요. 비밀 액세스 문제를 참조하세요. |
OOMKilled |
메모리 및 CPU 한계를 증가시키려면 az containerapp update -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --cpu 1.0 --memory 2.0Gi을 사용하여. |
비고
로컬 Docker 테스트와 CPU 스로틀링을 포함한 추가 컨테이너 시작 문제 해결은 '컨테이너 시작 실패 문제 해결'을 참조하세요. 포털 내 컨테이너 종료 이벤트 진단에 대해서는 '컨테이너 종료 실패 문제 해결'을 참조하세요.
건강 프로브 오류
리비전이 배포되었지만 상태 확인이 실패할 때 이 섹션을 사용하세요. 플랫폼은 복제본을 비정상 상태로 표시하거나 재시작합니다. 앱이 로컬에서는 작동하지만 컨테이너 앱에서는 프로브 검사에 실패할 수 있습니다.
프로브 고장이 있는지 시스템 로그를 확인하세요
Azure 포털에서 컨테이너 앱>모니터링>로그 스트림으로 가서 시스템 로그를 선택하세요. 프로브 고장 정보가 포함된 이벤트를 Unhealthy 찾아보세요. 또한 자동 분석을 위해 문제 진단 및 해결에서 "health probe"를 검색할 수도 있습니다.
# System logs for probe failure events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50
프로브 구성 점검
Azure 포털에서 Container App>Configure>Container>Health Probes로 가세요. 포트, 경로, 타이밍 설정을 확인하세요.
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME> \
--query "properties.template.containers[].probes" -o json
프로브 엔드포인트를 검증합니다
건강 엔드포인트가 설정된 타임아웃 내에 HTTP 200을 반환하는지 확인하세요. TCP 프로브를 사용한다면, 앱이 예상된 포트에서 수신 대기하는지 확인하세요.
일반적인 상태 프로브 문제 해결하기
| 이 조건을 보면 | 이 동작을 수행하세요 |
|---|---|
| 프로브가 거부된 연결을 반환합니다. | 프로브 포트를 앱의 수신 대기 포트 및 인그레스 targetPort와 일치하도록 설정합니다. |
프로브가 앱이 준비되기 전에 실패하고, 수정본이 Degraded가 됩니다 |
라이브니스 및 준비 상태 프로브의 initialDelaySeconds을 늘리세요. 앱이 긴 시작 시간이 필요하다면, 불필요한 재시작을 막기 위해 프로브 설정을 조정하세요. |
| HTTP 오류로 프로브 실패 | 헬스 엔드포인트가 200을 반환하도록 하세요. HTTP 프로브의 경우, 경로가 존재하고 올바르게 응답하는지 확인하세요. |
| 앱이 수신 대기하기 전에 프로브 연결 | 더 높은 failureThreshold 시작 프로브를 사용하여 앱이 포트를 바인딩할 시간을 제공합니다. |
비고
포털 기반 프로브 진단에 대해서는 건강 프로브 실패 문제 해결을 참조하세요. 목표 포트 불일치 진단은 '목표 포트 설정 문제 해결'을 참조하세요.
기본 프로브 값
인그레스를 활성화하고 프로브를 설정하지 않으면, 컨테이너 앱이 이 기본값을 적용합니다.
| 속성 | Startup | 활동성 | 준비 상태 |
|---|---|---|---|
| Protocol | HTTP GET / |
HTTP GET / |
HTTP GET / |
| 항구 | Ingress 대상 포트, 설정하지 않으면 80 | 인그레스 대상 포트, 설정하지 않으면 80 | 인그레스 대상 포트, 설정하지 않으면 80 |
| 초기 지연 | 1s | 1s | 3s |
| 기간 | 10초 | 10초 | 10초 |
| 일시 중지 | 1s | 1s | 1s |
| 성공 임계값 | 1 | 1 | 1 |
| 실패 임계값 | 48 | 3 | 3 |
초기화 타이밍 문제
init 컨테이너가 메인 컨테이너 시작을 막을 때 이 섹션을 사용하세요. 앱이 정지되거나 실패하거나 사용 불가능한 자원에 의존하면 앱이 실행 상태에 도달하지 못합니다.
수정 상태 확인
Azure 포털에서 컨테이너 앱>구성>더보기>수정 & 복제본으로 이동한 다음 실패한 버전을 선택하세요. 수정 세부 정보에서 init 컨테이너 이벤트를 찾아보세요.
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME> \
--query "{running:properties.runningState, details:properties.runningStateDetails}" -o json
init 컨테이너 로그를 확인하세요
Azure 포털에서 Container App>Observe>Log Stream으로 가서 컨테이너 드롭다운에서 init 컨테이너를 선택하세요.
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --container <INIT_CONTAINER_NAME> --tail 100
init 컨테이너 종료 동작 검증
init 컨테이너가 종료되는 명령을 실행하고 코드 0으로 종료되도록 하세요. 무기한 작동하는 init 컨테이너는 메인 컨테이너를 막습니다.
일반적인 초기화 문제 해결
| 이 오류를 보신다면 | 이 동작을 수행하세요 |
|---|---|
| init 컨테이너 로그에서 연결이 거부되거나 시간 제한이 발생했습니다. | 재시도 논리나 준비 상태 검사를 추가하세요. 종속 서비스를 초기화 시 사용할 수 있다고 가정하지 마세요. |
수정본은 Provisioning 무기한 유지됩니다 |
init 컨테이너가 유한 명령어를 실행하고 코드 0으로 종료되도록 하세요. |
| init 컨테이너가 401 또는 403 오류로 실패함 | 소비 전용 및 전용 워크로드 프로필 환경에서는 메인 컨테이너만 관리 신원을 사용할 수 있습니다. 소비 작업 프로필 환경에서는 init 컨테이너가 기본적으로 관리형 ID를 사용할 수 있습니다. API 버전 2024-02-02-preview 이상에서는 identitySettings가 ID를 Init, Main, None 또는 All로 범위 지정할 수 있습니다. |
| Init 컨테이너 이미지 끌어오기 실패 | Deployment fails before revision creation에서와 동일한 레지스트리 인증 및 이미지 태그 검사를 적용하세요. |
| Init 컨테이너가 빈 비밀을 읽습니다 | Key Vault에서 참조된 비밀이 즉시 업데이트된다고 가정하지 마세요. init 컨테이너가 Key Vault에서 참조된 값에 의존한다면, 재시도 로직을 추가하거나 init-time 의존성에 대해 직접 컨테이너 앱 비밀을 사용하세요. 버전이 지정되지 않은 Key Vault 참조의 경우, 최신 버전을 가져오기까지 최대 30분이 걸릴 수 있습니다. |
앱이 설정이 누락된 상태로 시작됩니다
컨테이너가 시작되었지만 구성, 비밀 정보 또는 ID 설정이 누락되었거나 잘못되어 애플리케이션이 실패할 때 이 섹션을 사용하세요.
비밀 액세스 문제
시크릿이나 Key Vault 참조와 같은 예상되는 구성 값이 실행 시 비어 있거나 누락된 경우 이 섹션을 사용하세요.
시크릿 및 환경 변수 참조를 검증
Azure Portal에서 Container App>Configure>Identity>Secrets로 이동하여 비밀이 존재하는지 확인하세요. Key Vault 참조를 사용한다면 경고 아이콘을 찾아보세요. 그 다음 Container App>Configure>More>Revisions & Replicas로 가서 리비전을 선택한 후 Container details>Environment variables를 확인해 secretRef 값이 정확한지 확인하세요.
# List secrets defined on the app
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table
# Verify environment variable references in the revision template
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME> \
--query "properties.template.containers[].env" -o json
Key Vault 접근 확인
이 단계는 Key Vault 참조를 사용할 때만 사용하세요.
Azure 포털에서 자동화된 분석을 위해 문제 진단 및 해결에서 "Key Vault"를 검색하세요.
# Verify that managed identity is assigned
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>
# Check system logs for Key Vault sync errors
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50
공통 시크릿 문제 해결
| 이 오류를 보신다면 | 이 동작을 수행하세요 |
|---|---|
| 환경 변수 값이 비어 있습니다 |
secretRef의 이름은 비밀 이름과 정확히 일치해야 합니다. 일치 항목 찾기에서는 대/소문자를 구분합니다. |
| 알 수 없는 비밀을 참조하는 배포 오류 |
az containerapp secret set -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --secrets mysecret=myvalue로 배포하기 전에 비밀을 정의하세요. |
| Old Container Apps 비밀 값이 업데이트 후에도 유지됩니다 | 새 리비전을 배포하거나 az containerapp revision restart -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME>로 기존 리비전을 재시작하세요. 컨테이너 앱 비밀을 업데이트해도 새 개정이 발생하지 않습니다. |
| 비밀이 삭제된 후 컨테이너가 시작되지 않음 | 삭제된 비밀에 대한 참조를 제거하는 새 수정 버전을 배포한 다음 이전 수정 버전을 비활성화합니다. |
Managed identity not configuredKey Vault와 함께 |
az containerapp identity assign -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --system-assigned를 통한 관리 ID 사용. |
Key Vault의 Authorization failed |
az role assignment create --role "Key Vault Secrets User" --assignee <IDENTITY_PRINCIPAL_ID> --scope <KEY_VAULT_RESOURCE_ID>을 통해 관리 신원에 Key Vault Secrets User 역할을 부여합니다. |
| Key Vault 방화벽이 액세스를 거부함 | 컨테이너 앱 환경의 아웃바운드 IP를 Key Vault 방화벽에 추가하거나, 개인 엔드포인트를 설정하세요. |
| 참조된 Key Vault 비밀은 비활성화되어 있습니다 | Key Vault에서 비밀을 활성화하세요. Azure 포털에서 Key Vault>Secrets로 이동하여 비밀을 선택한 다음 Enable을 선택하세요. |
| 잘못된 형식의 Key Vault URI | 형식 확인: https://<KEY_VAULT_NAME>.vault.azure.net/secrets/<SECRET_NAME> 또는 https://<KEY_VAULT_NAME>.vault.azure.net/secrets/<SECRET_NAME>/<SECRET_VERSION>. |
| Key Vault 접근은 약 5분에서 10분 후에 작동합니다 | 기다렸다가 다시 시도합니다. RBAC 전파는 최대 10분이 걸릴 수 있습니다. |
Important
컨테이너 앱의 앱 비밀은 애플리케이션에 스코프가 지정되고, 환경 변수 참조는 개정에 스코프가 지정됩니다. Container Apps 앱 비밀을 업데이트해도 새로운 개정이 생성되지 않습니다. 변경된 앱 비밀이 적용되도록 새 리비전을 배포하거나 기존 버전을 재시작하세요. 버전 제한이 없는 Key Vault 참조의 경우, 컨테이너 앱은 30분 이내에 최신 버전을 가져오고, 환경 변수에서 비밀을 참조하는 활성 수정본을 자동으로 재시작할 수 있습니다.
관리 ID 구성 오류
컨테이너가 시작되었지만 관리 ID가 제대로 설정되지 않았거나 필요한 권한이 없어 Azure 서비스 호출이 실패할 때 이 섹션을 사용하세요.
ID가 할당되었는지 확인하세요
Azure 포털에서 컨테이너 앱>구성>Identity>Identity로 가세요. 시스템 할당이 켜짐인지 또는 올바른 사용자 할당 ID가 나열되어 있는지 확인하세요.
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>
목표 자원에서 역할 할당을 확인하세요
Azure 포털에서 스토리지 계정이나 Key Vault와 같은 대상 리소스로 가서 Access Control (IAM)>으로 이동한 다음 역할 할당으로 가세요. ID 주체 ID가 필요한 역할을 갖고 있는지 확인하세요.
az role assignment list --assignee <PRINCIPAL_ID> --all -o table
인증 오류가 있는지 콘솔 로그를 확인하세요
Azure 포털에서 Container App>Observe>Log Stream으로 가세요. 애플리케이션 출력에서 401 또는 403 오류가 있는지 확인하세요.
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100
공통 관리 ID 문제 해결
| 이 오류를 보신다면 | 이 동작을 수행하세요 |
|---|---|
ManagedIdentityCredential 오류 |
az containerapp identity assign -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --system-assigned로 ID를 할당합니다 |
| 대상 자원에서 사용자 할당 ID로 인해 403 발생 | 코드에 DefaultAzureCredential(managed_identity_client_id="<CLIENT_ID>") 클라이언트 ID를 지정하세요. |
| ID가 할당된 상태에서도 403 오류 | 목표 자원에 필요한 역할을 할당하세요. 예를 들어, 스토리지 계정에 Storage Blob Data Contributor 를 할당하는 식입니다. |
| 인증 오류로 Init 컨테이너가 실패함 | 소비 전용 및 전용 워크로드 프로필 환경에서는 메인 컨테이너만 관리 신원을 사용할 수 있습니다. 소비 작업 프로필 환경에서는 init 컨테이너가 기본적으로 관리 ID를 사용할 수 있습니다. API 버전 2024-02-02-preview 이상에서는 identitySettings가 ID를 Init, Main, None 또는 All로 범위 지정할 수 있습니다. |
| 403은 역할이나 그룹 구성원을 수정한 후에도 유지됩니다 | 관리형 ID 인가 데이터는 리소스 URI당 약 24시간 동안 캐시될 수 있습니다. 토큰 새로 고침 강제 적용은 지원되지 않습니다. 캐시가 만료될 때까지 기다리고, 시간에 민감한 액세스를 위해 관리 ID 그룹 구성원 변경에 의존하지 마세요. |
Tip
관리 ID REST 엔드포인트를 직접 호출하는 대신 Azure Identity SDK를 DefaultAzureCredential와 함께 사용하세요. SDK는 환경 전반에 걸쳐 일관된 경험을 제공합니다.
요청이 실패하거나 예기치 않게 동작함
앱이 실행 중이고 정상일 때 HTTP 요청이 404, 502, 403과 같은 오류를 반환하거나 응답이 없을 때 이 섹션을 사용합니다. 문제는 인그레스 구성이나 트래픽 라우팅에 있을 가능성이 큽니다.
인그레스 구성 확인
Azure 포털에서 Container App> > Configure> > Networking> > Ingress로 이동하세요. 인그레스가 활성화되어 있고, 대상 포트가 앱과 일치하며, FQDN이 할당되었는지 확인하세요. 또한 자동 분석을 위해 진단 및 문제 해결에서 "ingress"를 검색할 수 있습니다.
# 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
FQDN과 트래픽 분할 확인
Azure 포털에서 컨테이너 앱>구성>더 보기>수정 버전 및 복제본으로 이동합니다. 트래픽이 올바른 수정본으로 라우팅되고 그 수정본이 정상인지 확인하세요.
# Verify the FQDN
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --query "properties.configuration.ingress.fqdn" -o tsv
# Check traffic split
az containerapp ingress traffic show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table
HTTP 로그 확인
Azure 포털에서 사용자의 Log Analytics 작업 공간으로 가서 ContainerAppHTTPLogs 테이블에 대해 쿼리를 실행하세요. 실패한 요청과 ResponseCodeDetails 필드를 검토하여 오류가 앱에서 발생했는지 플랫폼에서 발생했는지 판단하세요.
# Query HTTP logs in Log Analytics. This command requires HTTP logs enabled through diagnostic settings.
az monitor log-analytics query -w <LOG_ANALYTICS_WORKSPACE_ID> \
--analytics-query "ContainerAppHTTPLogs | where TimeGenerated > ago(1h) | where StatusCode >= 400 | project TimeGenerated, Method, Path, StatusCode, ResponseCodeDetails | take 50"
일반적인 요청 및 Ingress 문제 해결
| 이 조건이 보이면 | 이 동작을 수행하세요 |
|---|---|
| FQDN이 할당되어 있지 않고, 앱에 접근할 수도 없습니다 |
az containerapp ingress enable -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type external --target-port 8080 --transport auto을 실행하여 ingress를 활성화하세요. |
| 502 잘못된 게이트웨이 |
targetPort을(를) 앱이 수신 대기 중인 포트와 일치하도록 설정합니다. |
| 구버전은 최신 버전 대신 트래픽을 처리합니다 |
az containerapp ingress traffic set -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision-weight latest=100을 실행하여 트래픽 분할을 업데이트하세요. |
| 403 금지됨 | Ingress 설정에서 IP 보안 제한을 확인하세요. |
| 연결 오류 | 인그레스 전송 유형이 HTTP 또는 TCP 중 하나의 애플리케이션 프로토콜과 일치하는지 확인하세요. |
CLI 진단 워크플로우를 사용하세요
섹션별 단계별로 문제가 해결되지 않거나 더 많은 정보를 수집해야 할 때 이 워크플로우를 사용하세요.
포털 기반 진단의 경우, 문제 진단 및 해결을 사용하고 다양한 문제 해결 카테고리를 시도해 보세요. 단계별 CLI 워크플로우는 Azure CLI 탭으로 전환하세요.
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json을 실행합니다.provisioningState,provisioningError및latestRevisionName를 확인하세요.az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table을 실행합니다. 리스트가 비어 있으면 이미지 풀 또는 템플릿 검증 문제입니다. 리비전 생성 전에 배포가 실패함을 참조하세요. 수정 사항이 있다면 다음 단계로 진행하세요.az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REVISION_NAME> -o json을 실행합니다.healthState,runningState,runningStateDetails및provisioningError을 확인하세요.프로브 실패, 신원 오류, 비밀 동기화 문제와 같은 플랫폼 수준의 이벤트를 보려면
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50를 실행합니다.실행
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100후 스택 트레이스, 구성 오류, 연결 실패 등 애플리케이션 stdout와 stderr를 볼 수 있습니다. 이 로그에서 복제본 이름을 사용하여 문제를 특정 인스턴스로 한정하세요.이전 단계에서 인증 관련 오류가 발생한 경우 신원 구성을 확인하기 위해
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>를 실행하세요.
더 깊은 조사를 위해 Log Analytics를 쿼리하세요
CLI 출력과 포털 진단이 충분한 정보를 제공하지 못할 때는 Log Analytics를 사용하세요.
시스템 수준 오류 찾기
이 쿼리는 이미지 끌어오기 오류, 프로브 오류, 프로비전 오류 및 기타 플랫폼 이벤트를 보여 줍니다.
ContainerAppSystemLogs_CL
| where RevisionName_s == "<REVISION_NAME>"
| 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
복제본별로 콘솔 로그 오류 찾기
이 쿼리는 콘솔 로그 오류를 반환하며 복제체 이름을 포함합니다.
ContainerAppConsoleLogs_CL
| where RevisionName_s == "<REVISION_NAME>"
| where Log_s contains "error" or Log_s contains "Exception" or Log_s contains "fatal"
| project TimeGenerated, ContainerGroupName_s, Log_s
| order by TimeGenerated desc
| take 50
ContainerGroupName_s 필드는 ContainerAppConsoleLogs_CL에서 복제본 이름입니다. 오류를 특정 인스턴스에 국한하는 데 사용하세요. 자원별 ContainerAppConsoleLogs 테이블에서 ContainerGroupName를 사용하세요.
HTTP 오류 찾기
컨테이너 앱 관리 환경에서 Azure Monitor의 진단 설정을 통해 HTTP 로그를 활성화하세요. 사용하도록 설정한 후 ContainerAppHTTPLogs 테이블이 Log Analytics에 표시됩니다. 몇 분 정도 소요될 수 있습니다.
ContainerAppHTTPLogs
| where TimeGenerated > ago(1h)
| where StatusCode >= 400
| project TimeGenerated, ContainerAppName, RevisionName, ReplicaName, Method, Path,
StatusCode, ResponseCodeDetails, RequestDuration, RequestId
| order by TimeGenerated desc
| take 100
ResponseCodeDetails 필드는 오류가 via_upstream와 같은 컨테이너에서 발생했는지, 또는 route_not_found나 upstream_per_try_timeout와 같은 플랫폼에서 발생했는지를 나타냅니다.
느린 요청 분석, 수정 버전별 오류 비율, 단일 요청 추적 및 최고 실패 엔드포인트를 비롯한 더 많은 쿼리는 Log Analytics Azure Container Apps 로그 모니터링을 참조하세요.
다음 단계
문제가 해결되지 않으면:
- 포털에서 Diagnose and solve problems을 사용해 자동 진단 분석을 진행하세요.
- Azure Monitor에서 리소스 활용률 패턴을 확인하기 위해 메트릭을 검토하세요.
- 추가 시나리오는 Azure Container Apps 문제 해결 가이드를 참고하세요.
관련 문제 해결 문서:
- 이미지 풀 실패 문제 해결
- 컨테이너 시동 실패 문제 해결
- 상태 프로브 실패 문제 해결
- 대상 포트 설정 문제 해결
- 컨테이너 종료 실패 문제 해결
- OCI 오류 문제 해결
- 스토리지 마운트 실패 문제 해결
- Azure Container Apps의 문제를 진단하고 해결합니다
관련 문서: