다음을 통해 공유

Azure Container Registry 인증 문제 해결

  • 아티클

ACR(Azure Container Registry)은 프라이빗 레지스트리 서비스입니다. 밀어넣기 또는 끌어오기(익명 끌어오기 작업 제외)와 같은 작업을 수행하려면 먼저 ACR에 대해 인증해야 합니다.

이 문서는 ACR 인증 문제를 해결하는 데 도움이 되며 컨테이너 레지스트리에서 이미지를 끌어올 때 발생하는 가장 일반적인 오류에 대한 솔루션을 제공합니다.

초기 문제 해결

  1. 사용 중인 인증 옵션을 식별합니다. 하나를 선택하면 인증 문제를 재현하여 오류를 가져옵니다.

  2. Azure Container Registry의 상태를 확인하여 문제 해결을 시작합니다.

    컨테이너 레지스트리의 상태를 확인하려면 다음 명령을 실행합니다.

    az acr check-health --name <acr-name> --ignore-errors --yes

    문제가 감지되면 명령 출력은 오류 코드와 설명을 제공합니다. 오류 코드 및 가능한 솔루션에 대한 자세한 내용은 상태 검사 오류 참조를 참조하세요.

    참고 항목

    Helm 또는 공증과 관련된 오류가 발생하는 경우 컨테이너 레지스트리 또는 디바이스에 영향을 주는 문제가 있는 것은 아닙니다. Helm 또는 공증이 설치되지 않았거나 Azure CLI가 현재 설치된 Helm 또는 공증 버전과 호환되지 않음을 나타냅니다.

오류 1: "DOCKER_COMMAND_ERROR Docker 클라이언트가 설치되어 실행 중인지 확인하세요."

오류 세부 정보의 예는 다음과 같습니다.

You may want to use 'az acr login -n <acr-name> --expose-token' to get an access token, which does not require Docker to be installed.
<date and time> An error occurred: DOCKER_COMMAND_ERROR
Please verify if Docker client is installed and running.

해결 방법 1: Docker가 설치되어 있는지 확인

이 az acr login 명령은 명령을 호출 docker login 하고 Microsoft Entra 액세스 토큰을 사용하여 ACR에 대해 인증합니다. 명령을 실행하는 컴퓨터에 Docker 클라이언트 및 Docker 디먼을 설치해야 합니다. Docker를 설치하려면 Docker 엔진 설치를 참조 하세요.

해결 방법 2: "--expose-token" 매개 변수와 함께 "az acr login" 명령을 사용합니다.

Docker 디먼이 사용자 환경에서 실행되지 않는 경우 ACR을 사용하여 인증해야 하는 경우 --expose-token 매개 변수와 함께 az acr login 명령을 사용합니다. 이 명령은 Docker 디먼이 필요하지 않고 Docker CLI(예: Azure Cloud Shell을 사용하는 경우)만 필요한 스크립트를 실행해야 하는 경우에 유용합니다.

오류 2: "이 명령을 사용하려면 Azure Cloud Shell에서 지원되지 않는 Docker 디먼을 실행해야 합니다."

오류 세부 정보의 예는 다음과 같습니다.

This command requires running the docker daemon, which is not supported in Azure Cloud Shell. You may want to use 'az acr login -n <acr-name> --expose-token' to get an access token, which does not require Docker to be installed.

해결 방법 1: 다른 환경에서 "az acr login -n <acr-name>" 명령 실행

이 az acr login -n <acr-name> 명령을 실행하려면 Docker 클라이언트 및 Docker 디먼이 필요합니다. Azure Cloud Shell은 Docker 클라이언트만 제공합니다. 이 오류를 해결하려면 Docker 디먼이 az acr login -n <acr-name> 설치된 환경에서 명령을 실행합니다.

해결 방법 2: "--expose-token" 매개 변수와 함께 "az acr login" 명령을 사용합니다.

이 az acr login -n <acr-name> 명령을 실행하려면 Docker 클라이언트 및 Docker 디먼이 필요합니다. Azure Cloud Shell은 Docker 클라이언트만 제공합니다. 그러나 매개 변수가 az acr login --expose-token 있는 명령은 Azure Cloud Shell과 같은 Docker 디먼이 없는 환경에서 작동합니다.

오류 3: "권한 없음: 인증 필요"

오류 세부 정보의 예는 다음과 같습니다.

Error response from daemon: Get "https://<acr-name>.azurecr.io/v2/": unauthorized: {"errors":[{"code":"UNAUTHORIZED","message":"authentication required, visit https://aka.ms/acr/authorization for more information."}]}

이 오류는 ACR에 액세스할 때 인증에 실패했음을 나타냅니다. 이 오류는 잘못된 사용자 이름 및/또는 암호 또는 만료된 자격 증명을 사용하여 또는 docker login 명령을 실행할 az acr login 때 발생할 수 있습니다(서비스 주체, 범위 맵이 있는 토큰 또는 관리자 사용자를 사용하는 경우).

해결 방법: 올바르고 유효한 사용자 이름 및 암호 사용

  • 관리자 사용자를 사용하여 인증하는 경우 액세스 키 블레이드에서 자격 증명을 확인하고 해당 자격 증명이 또는 az acr login 명령에서 docker login 사용한 자격 증명인지 확인합니다.

    ACR '액세스 키' 블레이드를 보여 주는 스크린샷.

    참고 항목

    이전에 사용한 암호가 다시 생성되었을 수 있습니다.

  • 범위 맵과 연결된 토큰을 사용하는 경우 사용된 자격 증명을 확인합니다. 토큰에 대한 암호를 생성한 후에는 화면을 닫은 후 암호가 더 이상 표시되지 않으므로 토큰을 검색하고 자격 증명을 안전하게 저장해야 합니다. 다음 스크린샷에서 메시지를 참조하세요.

    '생성 후 자격 증명을 안전하게 저장' 메시지를 보여 주는 스크린샷.

    사용한 암호를 잘 모르는 경우 다시 생성하는 것이 좋습니다.

  • 범위 맵과 연결된 토큰을 사용하는 경우 암호에 대한 만료 날짜를 설정할 수 있습니다. 만료 날짜를 보려면 토큰 세부 정보 표시에 설명된 Azure CLI 명령을 실행하거나 Azure Portal에서 토큰을 열고 다음 스크린샷에 따라 만료 날짜를 확인할 수 있습니다.

    '만료 날짜' 열을 보여 주는 스크린샷

  • 서비스 주체를 사용하는 경우 ACR을 사용하여 인증할 수 있는 특정 권한이 있는지 확인합니다. 특정 권한 및 사용 가능한 기본 제공 역할을 찾으려면 Azure Container Registry 역할 및 권한을 참조 하세요.

  • 서비스 주체를 사용하는 경우 사용된 자격 증명을 확인합니다. 비밀을 생성한 후에는 화면을 닫은 후 암호가 더 이상 표시되지 않으므로 암호를 검색하고 자격 증명을 안전하게 저장해야 합니다. 다음 스크린샷에서 메시지를 참조하세요.

    '페이지를 떠나기 전에 만들 때 비밀 저장' 메시지를 보여 주는 스크린샷.

    사용한 비밀 값을 잘 모르는 경우 새 비밀을 만드는 것이 좋습니다.

  • 서비스 주체를 사용하는 경우 비밀이 만료되지 않았는지 확인합니다.

    az ad app credential list 명령을 실행하여 비밀 유효성을 확인할 수 있습니다.

    az ad app credential list --id "$SP_ID" --query "[].endDateTime" -o tsv

    또는 Azure Portal에서 만료 열을 확인하여 비밀 유효성을 확인할 수 있습니다.

    ACR '만료' 열을 보여 주는 스크린샷.

    비밀이 만료된 경우 새 비밀을 만드는 것이 좋습니다.

오류 4: "관리자 사용자 자격 증명을 가져올 수 없음"

오류 세부 정보의 예는 다음과 같습니다.

Unable to get AAD authorization tokens with message: <date> <time> An error occurred: CONNECTIVITY_REFRESH_TOKEN_ERROR
Access to registry '<acr-name>.azurecr.io' was denied. Response code: 401. Please try running 'az login' again to refresh permissions.
Unable to get admin user credentials with message: The resource with name '<acr-name>' and type 'Microsoft.ContainerRegistry/registries' could not be found in subscription '<subscription-name> (<subscription-id>)'.

해결 방법: 사용된 ID에 특정 권한이 있는지 확인합니다.

인증하는 데 사용되는 ID(예: 사용자 또는 관리 ID)에 특정 권한이 있는지 확인합니다. 특정 권한 및 사용 가능한 기본 제공 역할을 찾으려면 Azure Container Registry 역할 및 권한을 참조 하세요.

오류 5: "IP <IP 주소를> 가진 클라이언트에 액세스할 수 없습니다."

오류 세부 정보의 예는 다음과 같습니다.

Unable to get AAD authorization tokens with message: <date> <time> An error occurred: CONNECTIVITY_REFRESH_TOKEN_ERROR
Access to registry '<acr-name>.azurecr.io' was denied. Response code: 403. Please try running 'az login' again to refresh permissions.
Error response from daemon: Get "https://<acr-name>.azurecr.io/v2/": denied: {"errors":[{"code":"DENIED","message":"client with IP \u0027<ip-address>\u0027 is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}]}

해결 방법: 인증하려는 디바이스가 ACR과 연결되어 있는지 확인합니다.

ACR에는 공용 액세스를 제한하는 메커니즘인 기본 제공 방화벽이 있습니다. 전체 액세스를 허용하거나, 특정 네트워크에만 액세스를 허용하거나, 공용 액세스를 완전히 사용하지 않도록 설정할 수 있습니다. 그러나 성공적인 인증을 위해서는 적절한 연결이 필요합니다. IP 주소가 레지스트리에 액세스하고 로그인할 수 있는지 확인합니다. 공용 액세스 구성에 대한 자세한 내용은 공용 IP 네트워크 규칙 구성을 참조 하세요.

또는 Azure Private Link를 사용하여 Azure 컨테이너 레지스트리에 비공개로 연결하는 것이 좋습니다.

도움을 요청하십시오.

질문이 있거나 도움이 필요한 경우 지원 요청을 생성하거나Azure 커뮤니티 지원에 문의하세요. Azure 피드백 커뮤니티에 제품 피드백을 제출할 수도 있습니다.