다음을 통해 공유

Azure Container Registry로 인증

  • 아티클

Azure Container Registry로 인증하는 방법은 여러 가지가 있으며 각 방법을 하나 이상의 레지스트리 사용 시나리오에 적용할 수 있습니다.

권장되는 방법은 다음과 같습니다.

  • 개별 로그인을 통해 직접 레지스트리에 인증
  • 애플리케이션 및 컨테이너 오케스트레이터는 Microsoft Entra 서비스 주체를 사용하여 무인 또는 "헤드리스" 인증을 수행할 수 있습니다.

AKS(Azure Kubernetes Service) 또는 다른 Kubernetes 클러스터와 함께 컨테이너 레지스트리를 사용하는 경우 Kubernetes의 Azure Container Registry 사용하여 인증하는 시나리오를 참조하세요.

인증 옵션

다음 표에는 사용 가능한 인증 방법과 일반적인 시나리오가 나와 있습니다. 자세한 내용은 연결된 콘텐츠를 참조하세요.

메서드 인증 방법 시나리오 Azure RBAC(Azure 역할 기반 액세스 제어) 제한 사항
개별 AD ID  az acr login(Azure CLI)

Azure PowerShell의 Connect-AzContainerRegistry 		개발자, 테스터의 대화형 푸시/풀 예 AD 토큰을 3시간마다 갱신해야 합니다.
AD 서비스 주체  docker login

az acr login(Azure CLI)

Azure PowerShell의 Connect-AzContainerRegistry

API 또는 도구의 레지스트리 로그인 설정

Kubernetes 풀 비밀   		 CI/CD 파이프라인에서 무인 푸시

Azure 또는 외부 서비스에 무인 풀 		예 SP 암호 기본 만료는 1년입니다.
Azure 리소스에 대한 관리 ID  docker login

 az acr login(Azure CLI)

Azure PowerShell의 Connect-AzContainerRegistry		 Azure CI/CD 파이프라인에서 무인 푸시

Azure 서비스로 무인 풀

 예 Azure 리소스의 관리 ID를 지원하는 일부 Azure 서비스에서만 사용
AKS 클러스터 관리 ID  AKS 클러스터를 만들거나 업데이트할 때 레지스트리 연결 동일하거나 다른 구독에서 AKS 클러스터로 무인 끌어오기 아니요, 풀 액세스만 AKS 클러스터에서만 사용 가능

테넌트 간 인증에 사용할 수 없습니다.
AKS 클러스터 서비스 주체  AKS 클러스터를 만들거나 업데이트 시 활성화 다른 AD 테넌트의 레지스트리에서 AKS 클러스터로 무인 끌어오기 아니요, 풀 액세스만 AKS 클러스터에서만 사용 가능
관리 사용자  docker login  개인 개발자 또는 테스터의 대화형 푸시/풀

레지스트리에서 Azure App Service 또는 Azure Container Instances로 이미지 포털 배포		 아니요, 항상 풀 및 푸시 액세스 레지스트리당 단일 계정, 여러 사용자에는 권장되지 않음
리포지토리 범위 액세스 토큰  docker login

az acr login(Azure CLI)

Azure PowerShell의 Connect-AzContainerRegistry

Kubernetes 풀 비밀 		 개인 개발자 또는 테스터의 리포지토리로 대화형 푸시/풀

개별 시스템 또는 외부 디바이스별 리포지토리에서 무인 끌어오기 		예 현재 AD ID와 통합되어 있지 않음

Microsoft Entra ID를 사용한 개별 로그인

개발 워크스테이션에서 만든 레지스트리로 이미지 풀 및 푸시와 같이 직접 레지스트리를 사용하여 작업할 때 개별 Azure ID를 사용하여 인증합니다. az login을 사용하여 Azure CLI에 로그인한 다음 az acr login 명령을 실행합니다.

az login
az acr login --name <acrName>

az acr login을 사용하여 로그인하는 경우 CLI는 az login을 실행할 때 만든 토큰을 사용하여 원활하게 레지스트리로 세션을 인증합니다. 인증 흐름을 완료하려면 환경에서 Docker CLI 및 Docker 디먼이 설치되어 실행되고 있어야 합니다. az acr login은 Docker 클라이언트를 사용하여 docker.config 파일에 Microsoft Entra 토큰을 설정합니다. 이러한 방식으로 로그인하고 나면 자격 증명이 캐시되고 세션의 후속 docker 명령에 사용자 이름 또는 암호가 필요하지 않습니다.

팁

또한 OCI 아티팩트와 같은 Docker 이미지 외의 아티팩트를 레지스트리로 푸시 또는 풀하려면 az acr login을 사용하여 개별 ID를 인증합니다.

레지스트리 액세스의 경우 az acr login에 사용되는 토큰은 3시간 동안 유효하므로 항상 docker 명령을 실행하기 전에 레지스트리에 로그인하는 것이 좋습니다. 토큰이 만료될 경우 다시 az acr login 명령을 사용하여 토큰을 새로 고친 후 다시 인증합니다.

Azure ID와 함께 az acr login을 사용하면 Azure RBAC(Azure 역할 기반 액세스 제어)가 제공됩니다. 일부 시나리오에서는 Microsoft Entra ID에서 고유의 개인 ID를 사용하여 레지스트리에 로그인하거나 특정 Azure 역할 및 권한을 사용하여 다른 Azure 사용자를 구성할 수 있습니다. 교차 서비스 시나리오의 경우나 개별 액세스를 관리하지 않으려는 작업 그룹 또는 개발 워크플로의 요구 사항을 처리해야 하는 시나리오에서는 Azure 리소스의 관리 ID로 로그인할 수도 있습니다.

az acr login with --expose-token

경우에 따라 환경에서 Docker 디먼이 실행되고 있지 않으면 az acr login을 사용하여 인증해야 합니다. 예를 들어 Docker CLI를 제공하지만 Docker 디먼을 실행하지 않는 Azure Cloud Shell에서는 스크립트에서 az acr login을 실행해야 할 수 있습니다.

이 시나리오의 경우 먼저 --expose-token 매개 변수를 사용하여 az acr login을 실행합니다. 이 옵션을 지정하면 Docker CLI를 통해 로그인하지 않고 액세스 토큰을 노출합니다.

az acr login --name <acrName> --expose-token

출력에 액세스 토큰이 약식으로 표시됩니다.

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs[...]24V7wA",
  "loginServer": "myregistry.azurecr.io"
}

레지스트리 인증의 경우 토큰 자격 증명을 안전한 위치에 저장하고 권장 방법에 따라 docker 로그인 자격 증명을 관리하는 것이 좋습니다. 예를 들어 다음과 같이 환경 변수에 토큰 값을 저장합니다.

TOKEN=$(az acr login --name <acrName> --expose-token --output tsv --query accessToken)

그런 다음 00000000-0000-0000-0000-000000000000을 사용자 이름으로 전달하고 액세스 토큰을 암호로 사용하여 docker login을 실행합니다.

docker login myregistry.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin <<< $TOKEN

마찬가지로 helm registry login 명령과 함께 az acr login에 의해 반환된 토큰을 사용하여 레지스트리로 인증할 수 있습니다.

echo $TOKEN | helm registry login myregistry.azurecr.io \
            --username 00000000-0000-0000-0000-000000000000 \
            --password-stdin

서비스 사용자

레지스트리에 서비스 주체를 할당하면 애플리케이션 또는 서비스에서 헤드리스 인증에 이를 사용할 수 있습니다. 서비스 주체는 레지스트리에 Azure RBAC(Azure 역할 기반 액세스 제어)를 허용하며 사용자는 레지스트리에 여러 서비스 주체를 할당할 수 있습니다. 여러 서비스 주체를 사용하면 서로 다른 애플리케이션에 대한 다양한 액세스를 정의할 수 있습니다.

ACR 인증 토큰은 ACR에 로그인할 때 만들어지고 후속 작업 시 새로 고쳐집니다. 해당 토큰의 라이브 시간은 3시간입니다.

컨테이너 레지스트리에 사용할 수 있는 역할은 다음과 같습니다.

  • AcrPull: 끌어오기

  • AcrPush: 끌어오기 및 밀어넣기

  • 소유자: 풀, 푸시, 다른 사용자에게 역할 할당

전체 역할 목록은 Azure Container Registry 역할 및 권한을 참조하세요.

Azure Container Registry에 인증하기 위한 서비스 주체를 만드는 CLI 스크립트와 자세한 지침은 Azure Container Registry authentication with service principals(서비스 주체를 사용한 Azure Container Registry 인증)를 참조하세요.

관리자 계정

각 컨테이너 레지스트리에는 관리 사용자 계정이 포함되어 있으며 기본적으로 사용하지 않도록 설정되어 있습니다. 관리 사용자를 사용하도록 설정하고 Azure Portal을 사용하거나 Azure CLI, Azure PowerShell 또는 기타 Azure 도구를 사용하여 해당 자격 증명을 관리할 수 있습니다. 관리자 계정은 레지스트리에 대한 모든 권한을 가집니다.

컨테이너 레지스트리에서 특정 Azure 서비스로 이미지를 배포하는 일부 시나리오에서는 현재 관리자 계정이 필요합니다. 예를 들어 Azure Portal을 사용하여 레지스트리에서 Azure Container Instances 또는 Azure Web Apps for Containers로 컨테이너 이미지를 직접 배포할 경우 관리자 계정이 필요합니다.

Important

관리자 계정은 주로 테스트 용도로 단일 사용자가 레지스트리에 액세스하도록 설계되었습니다. 관리자 계정 자격 증명을 여러 사용자 간에 공유하지 않는 것이 좋습니다. 관리자 계정으로 인증하는 모든 사용자는 레지스트리에 대한 푸시 및 풀 액세스 권한이 있는 단일 사용자로 나타납니다. 이 계정을 변경하거나 사용하지 않도록 설정하면 해당 자격 증명을 사용하는 모든 사용자의 레지스트리 액세스는 허용되지 않습니다. 헤드리스 시나리오의 경우 사용자 및 서비스 주체는 개별 ID를 사용하는 것이 좋습니다.

관리자 계정은 두 개의 암호가 제공되며, 둘 다 다시 생성할 수 있습니다. 관리자 계정에 대해 만든 새 암호는 즉시 사용할 수 있습니다. 관리자 계정의 암호를 다시 생성하면 복제하고 사용할 수 있는 데 60초가 걸립니다. 두 개의 암호를 사용하면 다른 암호를 다시 생성하는 동안에 하나의 암호를 사용하여 레지스트리에 대한 연결을 유지할 수 있습니다. 관리자 계정을 사용할 수 있으면 레지스트리에 대한 기본 인증 메시지가 표시될 때 사용자 이름과 둘 중 한 가지 암호를 docker login 명령에 전달할 수 있습니다. 예시:

docker login myregistry.azurecr.io

로그인 자격 증명을 관리하는 권장 방법은 docker login 명령 참조를 참조하세요.

기존 레지스트리에 대한 관리 사용자를 사용하도록 설정하려면 Azure CLI에서 az acr update 명령의 --admin-enabled 매개 변수를 사용하면 됩니다.

az acr update -n <acrName> --admin-enabled true

레지스트리로 이동하여 설정에서 액세스 키를 선택한 다음 관리 사용자에서 사용을 선택하면 Azure Portal에서 관리 사용자를 사용하도록 설정할 수 있습니다.

Azure Portal에서 관리 사용자 UI 사용

Docker 대신 대체 컨테이너 도구로 로그인

어떤 시나리오에서는 일반 컨테이너 도구 docker 대신 podman과 같은 대체 컨테이너 도구를 사용해야 합니다. 예: Docker는 더 이상 RHEL 8 및 9에서 사용할 수 없으므로 컨테이너 도구를 전환해야 합니다.

az acr login 명령의 경우 기본 컨테이너 도구는 docker로 설정됩니다. 기본 컨테이너 도구를 설정하지 않았고 사용자 환경에서 docker 명령이 없으면 다음 오류가 발생합니다.

az acr login --name <acrName>
2024-03-29 07:30:10.014426 An error occurred: DOCKER_COMMAND_ERROR
Please verify if Docker client is installed and running.

az acr login 명령이 사용하는 기본 컨테이너 도구를 변경하려면 환경 변수 DOCKER_COMMAND를 설정하면 됩니다. 예시:

DOCKER_COMMAND=podman \
az acr login --name <acrName>

참고 항목

이 기능을 사용하려면 Azure CLI 버전 2.59.0 이상을 설치하고 구성해야 합니다. az --version을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.

다음 단계