常見問題集 - Azure Container Registry

是。 以下是您可以用來建立登錄的範本。

是。 請參閱適用於雲端的 Microsoft Defender、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。 可以在 https://<your registry login server>/v2/ 存取 API。 範例: 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 入口網站中的儲存體使用量已增加，您也可以使用 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。

是，您可以在 Azure Container Registry 中使用受信任的映像，因為 Docker Notary 已經整合，而且可以啟用。 如需詳細資訊，請參閱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 入口網站：您的登錄 -> [存取控制 (IAM)] -> [新增] (選取角色的 AcrPull 或 AcrPush)。

• Azure CLI：執行下列命令來尋找登錄的資源識別碼：

  az acr show -n myRegistry
  

  接著，您可以將 AcrPull 或 AcrPush 角色指派給使用者 (下列範例會使用 AcrPull)：

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

  或者，將角色指派給其應用程式識別碼所識別的服務主體：

  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 參數。 下列是啟用不可散發層推播的一些可能使用案例：網路受限登錄、具有限制存取的網路隔絕登錄，或是沒有網際網路連線的登錄。

舉例來說，如果您已設定 NSG 規則讓 VM 只能從 Azure 容器登錄提取映像，則 Docker 對外部/不可散發層會提取失敗。 舉例來說，如果 Windows Server Core 映像在其資訊清單中包含 Azure 容器登錄的外部層參考，則在此案例中會提取失敗。

若要啟用不可散發層的推送：

1. 編輯 daemon.json 檔案，其位於 Linux 主機中的 /etc/docker/ 和 Windows Server 中的 C:\ProgramData\docker\config\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，以改善網路速度。

此錯誤可能會發生在 Red Hat 版本的 Docker 精靈上，其中 --signature-verification 預設為啟用。 您可以執行下列命令來檢查 Red Hat Enterprise Linux (RHEL) 或 Fedora 的 Docker 精靈選項：

grep OPTIONS /etc/sysconfig/docker

例如，Fedora 28 伺服器具有下列 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
   

可以找到 --signature-verification 的詳細資料，方法為執行 man dockerd。

即使登錄資源名稱為大寫或混合大小寫，例如 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'))]"
     ]
},

您可能會遇到 InvalidAuthenticationInfo 錯誤，特別是使用 curl 工具搭配選項 -L、--location (以遵循重新導向)。 例如，使用 curl 搭配 -L 選項和基本驗證來提取 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 或私用工作階段，以避免任何過時的瀏覽器快取或 Cookie。

以下是可能不允許作業的一些案例：

• 已不再支援傳統登錄。 請使用 az acr update 或 Azure 入口網站升級至支援的服務層級。
• 映像或存放庫可能已鎖定，所以無法刪除或更新。 您可以使用 az acr repository show 命令來查看目前的屬性。
• 如果映像處於隔離中，則不允許某些作業。 深入瞭解隔離。
• 您的登錄可能已達其儲存體限制。

在存放庫作業中指定存放庫名稱時，如果看到「不支援的存放庫格式」、「格式無效」或「要求的資料不存在」之類的錯誤，請檢查名稱的拼字和大小寫。 有效的存放庫名稱只能包含小寫英數位元、句號、連字號、底線和正斜線。

必要條件

• 啟用在 Fiddler 中解密 HTTPS
• 透過 Docker UI 讓 Docker 使用 Proxy。
• 完成時，請務必還原。 如果這樣啟用且 Fiddler 未執行，Docker 無法運作。

Windows 容器

將 Docker Proxy 設定為 127.0.0.1:8888

Linux 容器

尋找 Docker VM 虛擬交換器的 IP：

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

將 Docker Proxy 設定為上一個命令和連接埠 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 for Source 觸發程序。

執行錯誤訊息的疑難排解

CI/CD 整合

• CircleCI
• GitHub 動作

為現有的網路安全性群組或使用者定義的路由，設定正確的防火牆規則。 設定之後，請等候幾分鐘，讓防火牆規則生效。

下列 Azure 內建原則設定為各自的原則狀態時，將導致使用者無法在其登錄上啟用管理使用者。

下一步

• 深入瞭解 Azure Container Registry。