자주 묻는 질문 - Azure Container Registry

예. 레지스트리를 만드는 데 사용할 수 있는 템플릿이 있습니다.

예. Microsoft Defender for Cloud, Twistlock 및 Aqua의 설명서를 참조하세요.

Kubernetes 설명서 및 Azure Kubernetes Service 단계를 참조하세요.

관리자 자격 증명을 가져오기 전에 레지스트리의 관리 사용자를 사용하도록 설정되어 있는지 확인합니다.

Azure CLI를 사용하여 자격 증명을 가져오려면 다음을 수행합니다.

az acr credential show -n myRegistry

Azure PowerShell 사용:

Invoke-AzureRmResourceAction -Action listCredentials -ResourceType Microsoft.ContainerRegistry/registries -ResourceGroupName myResourceGroup -ResourceName myRegistry

관리자 자격 증명을 가져오기 전에 레지스트리의 관리 사용자를 사용하도록 설정되어 있는지 확인합니다.

첫 번째 암호를 가져오려면 다음을 수행합니다.

{
    "password": "[listCredentials(resourceId('Microsoft.ContainerRegistry/registries', 'myRegistry'), '2017-10-01').passwords[0].value]"
}

두 번째 암호를 가져오려면 다음을 수행합니다.

{
    "password": "[listCredentials(resourceId('Microsoft.ContainerRegistry/registries', 'myRegistry'), '2017-10-01').passwords[1].value]"
}

사용자에게 레지스트리에 대한 권한이 있지만 구독에 대한 읽기 권한자 수준 권한이 없는 경우 이 오류가 표시됩니다. 이 문제를 해결하려면 사용자에게 구독에 대한 읽기 권한자 권한을 할당합니다.

az role assignment create --role "Reader" --assignee user@contoso.com --scope /subscriptions/<subscription_id> 

방화벽 규칙 변경 내용을 전파하는 데 다소 시간이 걸립니다. 방화벽 설정이 변경되면 몇 분 정도 기다렸다가 해당 변경 내용을 확인하세요.

ACR은 Docker Registry HTTP API V2를 지원합니다. API는 https://<your registry login server>/v2/에서 액세스할 수 있습니다. 예: https://mycontainerregistry.azurecr.io/v2/

Bash의 경우:

az acr manifest list-metadata --name myRepository --registry myRegistry --query "[?tags[0]==null].digest" --output tsv  | xargs -I% az acr repository delete --name myRegistry ---image myRepository@%

PowerShell의 경우:

az acr manifest list-metadata --name myRepository --repository myRegistry --query "[?tags[0]==null].digest" --output tsv | %{ az acr repository delete --name myRegistry --image myRepository@$_ }

자세한 내용은 Azure Container Registry에서 컨테이너 이미지 삭제를 참조하세요.

다른 컨테이너 이미지에서 기본 계층을 여전히 참조하고 있는 경우 이 상황이 발생할 수 있습니다. 참조가 없는 이미지를 삭제하면 몇 분 안에 레지스트리 사용량이 업데이트됩니다.

다음 Docker 파일을 사용하여 이미지를 1GB 계층으로 만듭니다. 이렇게 하면 레지스트리의 다른 이미지와 공유하지 않는 계층이 이미지에 있습니다.

FROM alpine
RUN dd if=/dev/urandom of=1GB.bin  bs=32M  count=32
RUN ls -lh 1GB.bin

Docker CLI를 사용하여 이미지를 빌드하고 레지스트리에 푸시합니다.

docker build -t myregistry.azurecr.io/1gb:latest .
docker push myregistry.azurecr.io/1gb:latest

Azure Portal에서 스토리지 사용량이 증가했음을 확인하거나 CLI를 사용하여 사용량을 쿼리할 수 있습니다.

az acr show-usage -n myregistry

Azure CLI 또는 포털을 사용하여 이미지를 삭제하고 몇 분 안에 업데이트된 사용량을 확인합니다.

az acr repository delete -n myregistry --image 1gb

Docker 소켓을 탑재하여 Azure CLI 컨테이너를 실행해야 합니다.

docker run -it -v /var/run/docker.sock:/var/run/docker.sock azuresdk/azure-cli-python:dev

컨테이너에서 docker를 설치합니다.

apk --update add docker

그런 다음, 레지스트리를 사용하여 인증합니다.

az acr login -n MyRegistry

최신 Docker 클라이언트(버전 18.03.0 이상)를 사용하여 TLS 1.2를 사용하도록 설정합니다.

예, Docker Notary가 통합되어 사용하도록 설정될 수 있으므로 Azure Container Registry에서 신뢰할 수 있는 이미지를 사용할 수 있습니다. 자세한 내용은 Azure Container Registry의 콘텐츠 신뢰를 참조하세요.

지문 파일은 어디에 있나요?

~/.docker/trust/tuf/myregistry.azurecr.io/myrepository/metadata 아래에서:

• 위임 역할을 제외한 모든 역할의 공개 키 및 인증서는 root.json에 저장되어 있습니다.
• 위임 역할의 공개 키 및 인증서는 해당 부모 역할의 JSON 파일(예: targets/releases 역할에 대한 targets.json)에 저장되어 있습니다.

Docker 및 Notary 클라이언트에서 전체 TUF 확인을 수행한 후에 이러한 공개 키 및 인증서를 확인하는 것이 좋습니다.

ACR은 다양한 수준의 권한을 제공하는 사용자 지정 역할을 지원합니다. 특히 AcrPull 및 AcrPush 역할을 통해 사용자는 Azure에서 레지스트리 리소스를 관리할 수 있는 권한 없이 이미지를 풀하거나 푸시할 수 있습니다.

• Azure Portal: 레지스트리 -> 액세스 제어(IAM) -> 추가(역할에 대해 AcrPull 또는 AcrPush 선택).

• Azure CLI: 다음 명령을 실행하여 레지스트리의 리소스 ID를 찾습니다.

  az acr show -n myRegistry
  

  그런 다음, 사용자에게 AcrPull 또는 AcrPush 역할을 할당할 수 있습니다(다음 예제에서는 AcrPull 사용).

  az role assignment create --scope resource_id --role AcrPull --assignee user@example.com
  

  또는 해당 애플리케이션 ID로 식별된 서비스 주체에게 역할을 할당합니다.

  az role assignment create --scope resource_id --role AcrPull --assignee 00000000-0000-0000-0000-000000000000
  

그러면 담당자가 레지스트리의 이미지를 인증하고 액세스할 수 있습니다.

• 레지스트리에 인증하려면:

  az acr login -n myRegistry 
  

• 리포지토리를 나열하려면:

  az acr repository list -n myRegistry
  

• 이미지를 끌어오려면:

  docker pull myregistry.azurecr.io/hello-world
  

AcrPull 또는 AcrPush 역할만 사용하는 경우 담당자에게는 Azure에서 레지스트리 리소스를 관리할 수 있는 권한이 없습니다. 예를 들어 az acr list 또는 az acr show -n myRegistry에서 레지스트리가 표시되지 않습니다.

이미지 격리는 현재 ACR의 미리 보기 기능입니다. 보안 검사를 성공적으로 통과한 이미지만 일반 사용자에게 표시되도록 레지스트리의 격리 모드를 사용하도록 설정할 수 있습니다. 자세한 내용은 ACR GitHub 리포지토리를 참조하세요.

자세한 내용은 레지스트리 콘텐츠를 공개적으로 사용할 수 있도록 설정을 참조하세요.

매니페스트의 배포 불가능 레이어에는 콘텐츠를 가져올 수 있는 URL 매개 변수가 포함되어 있습니다. 배포 불가능 레이어 푸시를 사용하도록 설정하는 몇 가지 가능한 사용 사례로, 네트워크가 제한된 레지스트리, 액세스가 제한된 에어 갭 레지스트리 또는 인터넷 연결이 없는 레지스트리가 있습니다.

예를 들어 VM이 Azure 컨테이너 레지스트리에서만 이미지를 풀할 수 있도록 NSG 규칙을 설정한 경우 Docker는 외부/배포 불가능 레이어의 경우 오류를 풀합니다. 예를 들어 Windows Server Core 이미지는 매니페스트에 Azure 컨테이너 레지스트리에 대한 외부 레이어 참조를 포함하고 이 시나리오에서 풀하지 못합니다.

배포 불가능 레이어 푸시를 사용하도록 설정하려면:

1. Linux 호스트의 /etc/docker/ 및 Windows Server의 C:\ProgramData\docker\config\daemon.json에 있는 daemon.json 파일을 편집합니다. 파일이 이전에 비어 있다고 가정하고 다음 내용을 추가합니다.

   {
     "allow-nondistributable-artifacts": ["myregistry.azurecr.io"]
   }
   

   참고 항목

   값은 쉼표로 구분된 레지스트리 주소의 배열입니다.

2. 파일을 저장하고 종료합니다.

3. Docker를 다시 시작합니다.

이미지를 목록의 레지스트리로 푸시하면 배포 불가능 레이어가 레지스트리로 푸시됩니다.

일반적인 환경 및 레지스트리 문제를 해결하려면 Azure 컨테이너 레지스트리의 상태 검사를 참조하세요.

• 이 오류가 일시적인 문제인 경우 다시 시도하면 성공합니다.
• docker pull이 계속 실패하면 Docker 디먼에 문제가 있을 수 있습니다. 일반적으로 Docker 디먼을 다시 시작하여 문제를 완화할 수 있습니다.
• Docker 디먼을 다시 시작한 후에도 이 문제가 계속 표시되면 머신의 일부 네트워크 연결 문제일 수 있습니다. 머신의 일반 네트워크가 정상인지 확인하려면 다음 명령을 실행하여 엔드포인트 연결을 테스트합니다. 이 연결 검사 명령이 포함된 최소 az acr 버전은 2.2.9입니다. 이전 버전을 사용하는 경우 Azure CLI를 업그레이드하세요.

az acr check-health -n myRegistry

• 모든 Docker 클라이언트 작업에는 항상 다시 시도 메커니즘이 있어야 합니다.

속도 도구를 사용하여 컴퓨터 네트워크 다운로드 속도를 테스트합니다. 컴퓨터 네트워크가 느린 경우 레지스트리와 동일한 지역에서 Azure VM을 사용하여 네트워크 속도를 높이는 것이 좋습니다.

속도 도구를 사용하여 컴퓨터 네트워크 업로드 속도를 테스트합니다. 컴퓨터 네트워크가 느린 경우 레지스트리와 동일한 지역에서 Azure VM을 사용하여 네트워크 속도를 높이는 것이 좋습니다.

이 오류는 기본적으로 --signature-verification을 사용하도록 설정되어 있는 Docker 디먼의 Red Hat 버전에서 발생할 수 있습니다. 다음 명령을 실행하여 RHEL(Red Hat Enterprise Linux) 또는 Fedora에 대한 Docker 디먼 옵션을 확인할 수 있습니다.

grep OPTIONS /etc/sysconfig/docker

예를 들어 Fedora 28 Server에 있는 Docker 디먼 옵션은 다음과 같습니다.

OPTIONS='--selinux-enabled --log-driver=journald --live-restore'

--signature-verification=false가 누락되면 다음과 비슷한 오류로 인해 docker pull이 실패합니다.

Trying to pull repository myregistry.azurecr.io/myimage ...
unauthorized: authentication required

오류를 해결하려면:

1. --signature-verification=false 옵션을 Docker 디먼 구성 파일(/etc/sysconfig/docker)에 추가합니다. 예시:

   OPTIONS='--selinux-enabled --log-driver=journald --live-restore --signature-verification=false'

2. 다음 명령을 실행하여 Docker 디먼 서비스를 다시 시작합니다.

   sudo systemctl restart docker.service
   

man dockerd를 실행하여 --signature-verification의 세부 정보를 확인할 수 있습니다.

레지스트리 리소스 이름이 대문자 또는 대/소문자(예: myRegistry)인 경우에도 모두 소문자인 서버 URL(예: docker push myregistry.azurecr.io/myimage:latest)을 사용해야 합니다.

debug 옵션을 사용하여 dockerd를 시작합니다. 먼저 Docker 디먼 구성 파일(/etc/docker/daemon.json)이 없는 경우 해당 파일을 만들고, debug 옵션을 추가합니다.

{    
    "debug": true    
}

그런 다음, 디먼을 다시 시작합니다. 예를 들어 Ubuntu 14.04를 사용하는 경우 다음과 같습니다.

sudo service docker restart

자세한 내용은 Docker 설명서에서 확인할 수 있습니다.

• 로그는 시스템에 따라 다른 위치에서 생성될 수 있습니다. 예를 들어 Ubuntu 14.04의 경우 /var/log/upstart/docker.log입니다.
  자세한 내용은 Docker 설명서를 참조하세요.

• Windows용 Docker의 경우 로그는 %LOCALAPPDATA%/docker/ 아래에 생성됩니다. 그러나 일부 디버그 정보가 아직 포함되지 않았을 수 있습니다.

  전체 디먼 로그에 액세스하려면 몇 가지 추가 단계가 필요할 수 있습니다.

  docker run --privileged -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /usr/local/bin/docker:/usr/local/bin/docker alpine sh
  
  docker run --net=host --ipc=host --uts=host --pid=host -it --security-opt=seccomp=unconfined --privileged --rm -v /:/host alpine /bin/sh
  chroot /host
  

  이제 dockerd를 실행하는 VM의 모든 파일에 액세스할 수 있습니다. 로그는 /var/log/docker.log에 있습니다.

새 권한(역할)을 서비스 주체에게 부여하면 변경 내용이 즉시 적용되지 않을 수 있습니다. 가능한 두 가지 이유가 있습니다.

• Microsoft Entra 역할 할당 연기. 일반적으로 속도가 빠르지만 전파 지연으로 인해 몇 분 정도 걸릴 수 있습니다.

• ACR 토큰 서버의 권한 지연에는 최대 10분이 걸릴 수 있습니다. 완화하려면 docker logout을 수행한 다음, 1분 후에 동일한 사용자로 다시 인증하면 됩니다.

  docker logout myregistry.azurecr.io
  docker login myregistry.azurecr.io
  

ACR은 현재 사용자의 홈 복제 삭제를 지원하지 않습니다. 이 문제를 해결하려면 홈 복제 만들기를 템플릿에 포함하지만 아래와 같이 "condition": false를 추가하여 만들기를 건너뜁니다.

{
    "name": "[concat(parameters('acrName'), '/', parameters('location'))]",
    "condition": false,
    "type": "Microsoft.ContainerRegistry/registries/replications",
    "apiVersion": "2017-10-01",
    "location": "[parameters('location')]",
    "properties": {},
    "dependsOn": [
        "[concat('Microsoft.ContainerRegistry/registries/', parameters('acrName'))]"
     ]
},

특히 리디렉션을 수행하기 위해 -L, --location 옵션이 포함된 curl 도구를 사용하는 경우 InvalidAuthenticationInfo 오류가 발생할 수 있습니다. 예를 들어 -L 옵션이 있는 curl 및 기본 인증을 사용하여 Blob을 가져오는 경우입니다.

curl -L -H "Authorization: basic $credential" https://$registry.azurecr.io/v2/$repository/blobs/$digest

다음과 같은 응답이 발생할 수 있습니다.

<?xml version="1.0" encoding="utf-8"?>
<Error><Code>InvalidAuthenticationInfo</Code><Message>Authentication information is not given in the correct format. Check the value of Authorization header.
RequestId:00000000-0000-0000-0000-000000000000
Time:2019-01-01T00:00:00.0000000Z</Message></Error>

근본 원인은 일부 curl 구현에서 원래 요청의 헤더를 사용하여 리디렉션을 수행한다는 것입니다.

이 문제를 해결하려면 헤더 없이 수동으로 리디렉션을 수행해야 합니다. curl의 -D - 옵션을 사용하여 응답 헤더를 출력한 다음, Location 헤더를 추출합니다.

REDIRECT_URL=$(curl -s -D - -H "Authorization: basic $credential" https://$registry.azurecr.io/v2/$repository/blobs/$digest | grep "^Location: " | cut -d " " -f2 | tr -d '\r')
curl $REDIRECT_URL

Microsoft Edge/IE 브라우저를 사용하는 경우 최대 100개의 리포지토리 또는 태그가 표시될 수 있습니다. 100개 이상의 리포지토리 또는 태그가 레지스트리에 있는 경우 Firefox 또는 Chrome 브라우저를 사용하여 모두 나열하는 것이 좋습니다.

브라우저에서 리포지토리 또는 태그를 가져오기 위한 요청을 서버에 보내지 못할 수 있습니다. 다음과 같은 여러 가지 이유가 있을 수 있습니다.

• 네트워크 연결 부족
• 방화벽
• 프라이빗 액세스만 허용하는 레지스트리에 대해 공용 네트워크의 포털 사용
• 광고 차단
• DNS 오류

네트워크 관리자에게 문의하거나 네트워크 구성 및 연결을 확인하세요. 환경에서 컨테이너 레지스트리에 연결할 수 있는지 확인하려면 Azure CLI를 사용하여 az acr check-health -n yourRegistry를 실행해 봅니다. 또한 오래된 브라우저 캐시 또는 쿠키를 방지하기 위해 브라우저에서 incognito(시크릿 모드) 또는 프라이빗 세션을 시도할 수도 있습니다.

작업이 허용될 수 없는 몇 가지 시나리오는 다음과 같습니다.

• 클래식 레지스트리가 더 이상 지원되지 않습니다. az acr update 또는 Azure Portal을 사용하여 지원되는 서비스 계층으로 업그레이드하세요.
• 이미지 또는 리포지토리가 잠겨 있어 삭제하거나 업데이트할 수 없습니다. az acr repository show 명령을 사용하여 현재 특성을 볼 수 있습니다.
• 이미지가 격리 모드에 있는 경우 일부 작업이 허용되지 않습니다. 격리에 대해 자세히 알아보세요.
• 레지스트리가 스토리지 한도에 도달했을 수 있습니다.

리포지토리 작업에서 리포지토리 이름을 지정할 때 "지원되지 않는 리포지토리 형식", "잘못된 형식" 또는 "요청된 데이터가 없음"과 같은 오류가 표시되는 경우 이름의 철자와 대/소문자를 확인합니다. 유효한 리포지토리 이름에는 소문자 영숫자, 마침표, 대시, 밑줄 및 슬래시만 포함될 수 있습니다.

필수 조건

• Fiddler에서 HTTPS 암호 해독 사용
• Docker UI를 통해 Docker가 프록시를 사용할 수 있도록 합니다.
• 완료되면 되돌려야 합니다. 이 기능을 사용하도록 설정되어 있고 Fiddler가 실행되지 않으면 Docker가 작동하지 않습니다.

Windows 컨테이너

Docker 프록시를 127.0.0.1:8888로 구성합니다.

Linux 컨테이너

Docker vm 가상 스위치의 ip를 찾습니다.

(Get-NetIPAddress -InterfaceAlias "*Docker*" -AddressFamily IPv4).IPAddress

Docker 프록시를 이전 명령과 8888 포트(예: 10.0.75.1:8888)의 출력에 맞게 구성합니다.

다음 명령은 지정된 레지스트리에서 실행 중인 모든 작업을 취소합니다.

az acr task list-runs -r $myregistry --run-status Running --query '[].runId' -o tsv \
| xargs -I% az acr task cancel-run -r $myregistry --run-id %

로컬 원본 폴더를 az acr build 명령에 전달하면 기본적으로 업로드된 패키지에서 .git 폴더가 제외됩니다. .dockerignore 파일은 다음 설정을 사용하여 만들 수 있습니다. 이 설정은 업로드된 패키지의 .git 아래에 있는 모든 파일을 복원하도록 명령에 지시합니다.

!.git/**

이 설정은 az acr run 명령에도 적용됩니다.

현재 원본 트리거에 대해 GitLab을 지원하지 않습니다.

실행 오류 메시지 문제 해결

CI/CD 통합

• CircleCI
• GitHub Actions

올바른 방화벽 규칙을 기존 네트워크 보안 그룹 또는 사용자 정의 경로에 설정합니다. 설정 후 방화벽 규칙이 적용될 때까지 몇 분 정도 기다립니다.

다음 Azure 기본 정책은 각 정책 상태로 설정하면 사용자가 해당 레지스트리에서 관리 사용자를 활성화하지 못하도록 차단합니다.

다음 단계

• Azure Container Registry에 대해 자세히 알아봅니다.