Azure Container Registry에서 Azure Web App으로 이미지를 끌어올 수 없습니다.
이 문서에서는 Azure 컨테이너 레지스트리에서 Azure Web App으로 이미지를 끌어올 때 발생할 수 있는 가장 일반적인 오류를 해결하기 위한 지침을 제공합니다.
증상 및 초기 문제 해결
컨테이너 레지스트리 상태를 확인하여 문제 해결을 시작하는 것이 좋습니다.
컨테이너 레지스트리 상태를 확인하려면 다음 명령을 실행합니다.
az acr check-health --name <myregistry> --ignore-errors --yes
문제가 감지되면 결과에 오류 코드와 설명이 포함됩니다. 이러한 오류 및 가능한 솔루션에 대한 자세한 내용은 상태 검사 오류 참조를 참조하세요.
참고 항목
Helm 관련 또는 공증 관련 오류가 발생하는 경우 Container Registry 또는 AKS가 작동하지 않거나 문제가 있는 것은 아닙니다. Helm 또는 공증이 설치되지 않았거나 Azure CLI가 현재 설치된 Helm 또는 공증 버전과 호환되지 않는 것과 같은 문제를 나타냅니다.
다음으로, 문제 해결에 필수적인 끌어오기 관련 오류 메시지를 식별합니다.
- Azure Portal에 로그인합니다.
- 웹앱에서 배포 센터>로그를 선택합니다. 커밋을 선택하여 로그 세부 정보를 봅니다. 모니터링 섹션에서 로그 스트림을 확인하여 이미지 끌어오기 프로세스에 대한 로그를 실시간으로 볼 수도 있습니다.
다음 섹션에서는 웹앱 로그에 표시되는 가장 일반적인 오류를 해결하는 데 도움이 됩니다.
오류 1: 권한 없음
Head \" https://<acr-name>.azurecr.io/v2/<repository>/manifests/<tag>\": unauthorized
관리자 사용자 기반 인증을 위한 솔루션
잘못된 관리자 자격 증명으로 인해 "권한 없는" 오류가 발생할 수 있습니다. 여기에는 웹앱 환경 변수에서 구성한 로그인 서버, 사용자 이름 또는 암호가 포함됩니다.
문제를 해결하려면 다음 단계를 수행합니다.
- Azure Portal에서 레지스트리 컨테이너로 이동합니다. 설정 섹션에서 액세스 키를 선택합니다. 로그인 서버, 사용자 이름 및 암호의 관리자 사용자 자격 증명 설정을 확인합니다.
- 웹앱으로 이동합니다. 설정 섹션에서 환경 변수를 선택합니다.
- 컨테이너 레지스트리에 대해 구성된 세 가지 변수(로그인 서버, 사용자 이름, 암호)가 레지스트리 컨테이너의 관리자 사용자 자격 증명 설정과 일치하는지 확인합니다.
관리 ID 기반 인증을 위한 솔루션
Azure Web App의 관리 ID 기반 인증 Microsoft.ContainerRegistry/registries/pull/read 을 사용하는 경우 끌어오기 작업을 수행하려면 관리 ID에 권한을 할당해야 합니다.
권한이 포함된 Microsoft.ContainerRegistry/registries/pull/read Azure 기본 제공 역할은 다음과 같습니다.
- AcrPull
- AcrPush
- ReaderContributor
- 담당자
자세한 내용은 Azure Container Registry 역할 및 권한을 참조하세요.
컨테이너 레지스트리에서 끌어오기 작업을 시작하면 AcrPull 역할이 Azure Web App 관리 ID에 자동으로 할당됩니다. 수동으로 권한을 추가할 필요가 없습니다. 그러나 역할 할당 만들기가 Azure 정책과 같이 차단되지 않도록 해야 합니다. 또한 역할 할당이 삭제되지 않았는지 확인합니다.
오류 2: 태그>로 <태그가 지정된 매니페스트를 찾을 수 없음
DockerApiException : Docker API responded with status code=NotFound, response={"message":"manifest for <acr-name>.azurecr.io/<repository>:<tag> not found: manifest unknown: manifest tagged by \"<tag>\" is not found"}
해결 방법: 태그가 있는지 확인
오류 메시지는 끌어오려는 이미지와 연결된 태그를 찾을 수 없음을 나타냅니다. 태그가 연결된 리포지토리 및 레지스트리 내에 있는지 확인합니다.
Azure CLI를 사용하여 연결된 리포지토리 및 레지스트리 내에서 태그를 찾으려면 다음 명령을 실행합니다.
az acr repository show-tags -n <ContainerRegistryName> --repository <RepositoryName>
Azure Portal을 사용하여 연결된 리포지토리 및 레지스트리 내에 있는 태그를 찾으려면 다음 단계를 수행합니다.
레지스트리 컨테이너로 이동합니다. 서비스에서 리포지토리를 선택하고 연결된 리포지토리를 연 다음 태그 목록을 확인합니다.
참고 항목
az acr repository show-tags 명령 또는 Azure Portal에서 리포지토리 확인은 컨테이너 레지스트리 네트워크 규칙이 허용하는 경우에만 작동합니다.
오류 3: IP가 있는 클라이언트에 액세스할 수 없음
DockerApiException: Docker API responded with status code=InternalServerError, response={"message":"Head \"https:// <acr-name>.azurecr.io/v2/<repository>/manifests/<tag>\": denied: client with IP '<web-app-outbound-ip>' is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}
해결 방법 1: 컨테이너 레지스트리 기본 제공 방화벽에서 디바이스의 IP 주소를 허용하는지 확인합니다.
기본적으로 컨테이너 레지스트리는 모든 네트워크에서 인터넷을 통해 연결을 허용합니다. 컨테이너 레지스트리에는 특정 IP 주소 또는 CIDR에 대한 액세스를 제한하거나 공용 네트워크 액세스를 완전히 사용하지 않도록 설정할 수 있는 기본 제공 방화벽이 있습니다.
이 문제는 웹앱의 IP 주소가 컨테이너 레지스트리의 기본 제공 방화벽에 의해 차단되는 경우에 발생할 수 있습니다.
이 문제를 해결하려면 기본 제공 방화벽에서 이미지를 끌어와야 하는 웹앱의 아웃바운드 IP 주소를 허용하는지 확인합니다.
웹앱의 아웃바운드 IP 주소를 찾으려면 다음 단계를 수행합니다.
- Azure Portal에서 웹앱으로 이동합니다.
- 개요 페이지에서 아웃바운드 IP 주소를 찾은 다음 자세히 표시를 선택하여 아웃바운드 IP 주소의 전체 목록을 가져옵니다.
Azure CLI를 사용하여 웹앱의 아웃바운드 IP 주소를 찾으려면 Azure 앱 Service에서 아웃바운드 IP 주소 찾기를 참조하세요.
솔루션 2: 웹앱에 대한 가상 네트워크 통합 구성
공용 네트워크 액세스를 완전히 사용하지 않도록 설정하거나 웹앱의 IP 주소를 수동으로 추가하지 않고 컨테이너 레지스트리에서 선택한 네트워크만 허용해야 하는 경우 이미지를 비공개로 끌어오는 것이 좋습니다. 이미지를 비공개로 끌어오려면 프라이빗 엔드포인트를 사용하여 컨테이너 레지스트리를 구성하고 웹앱에 가상 네트워크 통합을 사용하도록 설정해야 합니다.
다음 단계에 따라 웹앱 쪽에서 가상 네트워크 통합을 구성할 수 있습니다.
Azure Portal에서 웹앱으로 이동한 다음 네트워킹을 선택합니다.
아웃바운드 트래픽 구성에서 Virtual Network 통합을 구성하고, 가상 네트워크 통합 추가를 선택한 다음, 구독, 가상 네트워크 및 서브넷을 지정합니다.
가상 네트워크 구성 페이지에서 컨테이너 이미지 끌어오기 옵션이 선택되어 있는지 확인합니다.
가상 네트워크를 통해 이미지를 끌어오려면 웹앱의 배포 센터에서 VNet을 통해 끌어오기 이미지를 사용하도록 설정해야 합니다. 또한 컨테이너 레지스트리에 공용 액세스가 비활성화되거나 특정 네트워크로 설정된 경우 다음 예제와 같이 "ACR 태그 로드 실패 - 실패" 메시지가 표시될 수 있습니다. 이 시나리오에서는 이 오류가 필요합니다. 이 경우 이미지 및 태그에 대한 드롭다운 옵션을 사용할 수 없습니다. 이미지와 태그를 수동으로 입력해야 합니다.
다음 단계
이 문제 해결 지침이 문제를 해결하지 못하는 경우 다음을 고려하세요.
서브넷과 연결된 네트워크 보안 그룹 및 경로 테이블을 확인합니다. 방화벽과 같은 가상 어플라이언스가 서브넷 간의 트래픽을 제어하는 경우 방화벽 및 해당 액세스 규칙을 검토합니다.
추가 문제 해결을 위해 Kudu 서비스를 사용합니다. Kudu 서비스에 연결할 수 있습니다. 예를 들어 Bash를 사용하여 DNS 확인을 실행 nslookup <acr-name>.azurecr.io하여 테스트하거나 을 사용하여 tcpping <acr-name>.azurecr.io연결을 확인합니다.
도움을 요청하십시오.
질문이 있거나 도움이 필요한 경우 지원 요청을 생성하거나Azure 커뮤니티 지원에 문의하세요. Azure 피드백 커뮤니티에 제품 피드백을 제출할 수도 있습니다.