常见问题解答 - Azure 容器注册表

是。 这里提供了模板，可以用来创建注册表。

是。 请参阅 Microsoft Defender for Cloud、Twistlock 和 Aqua 中的文档。

请参阅 Kubernetes 的文档以及适用于 Azure Kubernetes 服务的步骤。

在获取管理员凭据之前，请确保已启用注册表的管理员用户。

使用 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]"
}

当用户在注册表上具有 Container Registry Contributor and Data Access Configuration Administrator 角色（允许通过 Azure CLI 删除副本），但在订阅上缺乏读取者权限时，会发生此错误。 通过门户删除副本时，需要对订阅具有读取者访问权限。 若要解决此问题，请向用户分配对订阅的“读取者”权限：

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

传播防火墙规则更改需要一段时间。 更改防火墙设置后，请等待几分钟，然后验证此更改。

ACR 支持 Docker 注册表 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 容器注册表中的容器映像。

如果其他容器映像仍在引用基础层，则可能会发生这种情况。 如果删除不带引用的映像，则注册表用量在几分钟后即会更新。

使用以下 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 容器注册表中的受信任映像与 Docker 内容信任结合使用。 有关详细信息，请参阅 Azure 容器注册表中的内容信任。

指纹文件位于何处？

在 ~/.docker/trust/tuf/myregistry.azurecr.io/myrepository/metadata 下：

• 所有角色（委托角色除外）的公钥和证书都存储在 root.json 中。
• 委托角色的公钥和证书将存储在其父角色的 JSON 文件（例如，targets/releases 角色的 targets.json）中。

你应在 Docker 和 Notary 客户端完成总体 TUF 验证后验证这些公钥和证书。

ACR 支持 Microsoft Entra 基于角色的访问控制（RBAC）和内置角色，这些角色提供基于 Microsoft Entra 的不同级别权限，例如，在不授予对整个注册表权限的情况下授予映像推送或拉取的权限。

你可以选择使用 [Microsoft Entra 基于属性的访问控制 (ABAC)] 来管理基于 Microsoft Entra 的存储库权限，并将角色分配范围限定为特定存储库。

映像隔离目前是 ACR 的预览版功能。 可以启用注册表的隔离模式，以便只有通过安全扫描的映像才能对普通用户可见。 有关详细信息，请参阅 ACR GitHub 存储库。

有关详细信息，请参阅使注册表内容公用。

清单中的不可分发层包含一个 URL 参数，可以通过该参数提取内容。 启用不可分发层推送的一些可能用例适用于：网络受限制的注册表、具有受限访问权限的气隙注册表，或没有 Internet 连接的注册表。

例如，如果设置了网络安全组（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 以提高网络速度。

默认启用 --signature-verification 的 Red Hat 版 Docker 守护程序可能会发生此错误。 可以运行以下命令来检查 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
   

运行 man dockerd 可以找到 --signature-verification 的详细信息。

请确保使用全小写的服务器 URL（例如 docker push myregistry.azurecr.io/myimage:latest），即使注册表资源名称是大写的或大小写混合的（例如 myRegistry）。

使用 debug 选项启动 dockerd。 首先创建 Docker 守护程序配置文件 (/etc/docker/daemon.json)（如果不存在），并添加 debug 选项：

{    
    "debug": true    
}

然后重启守护程序。

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 错误，尤其是结合选项 -L（--location，跟踪重定向）使用 curl 工具时。 例如，结合 -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 或专用会话，避免使用任何过时的浏览器缓存或 Cookie。

以下是一些可能出现不允许进行操作的情况：

• 不再支持经典注册表。 请使用 az acr update 或 Azure 门户升级到受支持的服务层。
• 映像或存储库可能已锁定，因此无法进行删除或更新。 可以使用 az acr repository show 命令查看当前属性。
• 如果映像处于隔离状态，则会禁用某些操作。 详细了解隔离。
• 注册表可能已达到其存储限制。

如果在存储库操作中指定存储库名称时出现“存储库格式不受支持”、“无效格式”或“请求的数据不存在”等错误，请检查名称的拼写和大小写。 有效的存储库名称只能包含小写字母数字字符、句点、短划线、下划线和正斜杠。

Prerequisites

• 启用在 Fiddler 中解密 HTTPS
• 通过 Docker UI 使 Docker 能够使用代理。
• 完成后，请务必还原设置。 Docker 无法在启用此项但 Fiddler 未运行的情况下工作。

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 活动

为现有网络安全组或用户定义的路由设置正确的防火墙规则设置。 设置后，等待几分钟，等待防火墙规则应用。

以下 Azure 内置策略设置为相应的策略状态时，阻止用户在其注册表上启用管理员用户。

Next steps

• 详细了解 Azure 容器注册表。