Azure 容器注册表中的工件缓存

项目
12/20/2024

工件缓存功能允许用户在专用容器注册表中缓存容器映像。工件缓存在基本、标准和高级服务层级提供。

工件缓存通过为公共和专用存储库提供缓存解决方案来增强容器映像管理。

工件缓存通过 Azure 容器注册表 (ACR) 提供更快、更可靠的拉取操作，利用地理复制和可用性区域支持等功能实现更高的可用性和更快的映像拉取速度。

工件缓存允许通过专用网络访问缓存的注册表，以便用户无缝地与防火墙配置和合规标准保持一致。

工件缓存解决了公共注册表施加的拉取限制的难题。我们建议用户使用其上游源凭据对缓存规则进行身份验证。然后从本地 ACR 拉取映像，以帮助缓解速率限制。

术语

缓存规则 - 缓存规则是你可以创建的规则，用于将工件从受支持的存储库拉取到缓存中。
- 缓存规则包含四个部分：
  - 规则名称 - 缓存规则的名称。例如，Hello-World-Cache。
  - 源 - 源注册表的名称。
  - 存储库路径 - 存储库的源路径，用于查找和检索要缓存的工件。例如，docker.io/library/hello-world。
  - 新 ACR 存储库命名空间 - 用于存储工件的新存储库路径的名称。例如，hello-world。存储库不能已存在于 ACR 实例中。
凭据
- 凭据是源注册表的一组用户名和密码。需要凭据才能使用公共或专用存储库进行身份验证。凭据包含四个部分
  - 凭据 - 凭据的名称。
  - 源注册表登录服务器 - 源注册表的登录服务器。
  - 源身份验证 - 用于存储凭据的密钥保管库位置。
  - 用户名和密码机密 - 包含用户名和密码的机密。

限制

只有在可用容器映像上至少完成一个映像拉取后，才会发生缓存。对于每个可用的新映像，必须完成新的映像拉取。当新标记可用时，工件缓存不会自动拉取映像的新标记。它位于路线图中，但在此版本中不受支持。
工件缓存仅支持 1,000 条缓存规则。

上游支持

工件缓存当前支持以下上游注册表：

警告

客户必须生成凭据集以从 Docker Hub 获取内容。

上游注册表	支持	可用性
Docker Hub	仅支持经过身份验证的拉取。	Azure CLI、Azure 门户
Microsoft 工件注册表	仅支持未经身份验证的拉取。	Azure CLI、Azure 门户
AWS 弹性容器注册表 (ECR) 公共库	仅支持未经身份验证的拉取。	Azure CLI、Azure 门户
GitHub 容器注册表	支持经过身份验证的拉取和未经身份验证的拉取。	Azure CLI、Azure 门户
Quay	支持经过身份验证的拉取和未经身份验证的拉取。	Azure CLI、Azure 门户
registry.k8s.io	支持经过身份验证的拉取和未经身份验证的拉取。	Azure CLI

通配符

通配符使用星号 (*) 来匹配容器映像注册表中的多个路径。工件缓存当前支持以下通配符：

注意

缓存规则从目标存储库映射到源存储库。

注册表级别通配符

注册表级别通配符允许你缓存来自上游注册表的所有存储库。

缓存规则	映射	示例
contoso.azurecr.cn/* => mcr.microsoft.com/*	将 ACR 下的所有映像映射到 MCR。	contoso.azurecr.cn/myapp/image1 => mcr.microsoft.com/myapp/image1 contoso.azurecr.cn/myapp/image2 => mcr.microsoft.com/myapp/image2

存储库级别通配符

存储库级别通配符允许你缓存来自上游注册表的所有存储库（映射到存储库前缀）。

缓存规则	映射	示例
contoso.azurecr.cn/dotnet/* => mcr.microsoft.com/dotnet/*	将 ACR 下的特定存储库映射到 MCR 中的相应存储库。	contoso.azurecr.cn/dotnet/sdk => mcr.microsoft.com/dotnet/sdk contoso.azurecr.cn/dotnet/runtime => mcr.microsoft.com/dotnet/runtime
contoso.azurecr.cn/library/dotnet/* => mcr.microsoft.com/dotnet/* contoso.azurecr.cn/library/python/* => docker.io/library/python/*	将 ACR 下的特定存储库映射到来自不同上游注册表的存储库。	contoso.azurecr.cn/library/dotnet/app1 => mcr.microsoft.com/dotnet/app1 contoso.azurecr.cn/library/python/app3 => docker.io/library/python/app3

基于通配符的缓存规则的限制

通配符缓存规则使用星号 (*) 来匹配容器映像注册表中的多个路径。这些规则不能与其他通配符缓存规则重叠。换句话说，如果你为某个注册表路径设置了通配符缓存规则，则无法添加与其重叠的另一个通配符规则。

下面是重叠规则的一些示例：

示例 1：

现有缓存规则：contoso.azurecr.cn/* => mcr.microsoft.com/*
正在添加的新缓存：contoso.azurecr.cn/library/* => docker.io/library/*

由于目标存储库路径 contoso.azurecr.cn/library/* 与现有通配符规则 contoso.azurecr.cn/* 重叠，因此系统会阻止添加新的缓存规则。

示例 2：

现有缓存规则：contoso.azurecr.cn/library/* =>mcr.microsoft.com/library/*
正在添加的新缓存：contoso.azurecr.cn/library/dotnet/* =>docker.io/library/dotnet/*

由于目标存储库路径 contoso.azurecr.cn/library/dotnet/* 与现有通配符规则 contoso.azurecr.cn/library/* 重叠，因此系统会阻止添加新的缓存规则。

静态/固定缓存规则的限制

静态或固定缓存规则更加具体，不使用通配符。它们可以与基于通配符的缓存规则重叠。如果缓存规则指定固定存储库路径，则允许与基于通配符的缓存规则重叠。

示例 1：

现有缓存规则：contoso.azurecr.cn/* =>mcr.microsoft.com/*
正在添加的新缓存：contoso.azurecr.cn/library/dotnet =>docker.io/library/dotnet

允许添加新的缓存规则，因为 contoso.azurecr.cn/library/dotnet 是静态路径，可以与通配符缓存规则 contoso.azurecr.cn/* 重叠。

启用工件缓存 - Azure CLI

可以按照以下步骤在 Azure 容器注册表中使用 Azure CLI 启用工件缓存（无论是否进行身份验证）。

先决条件

可以使用本地安装的 Azure CLI 来运行本文中的命令示例。如果想要在本地使用它，则需要使用 2.46.0 版或更高版本。运行 az --version 以查找版本。如果需要进行安装或升级，请参阅安装 Azure CLI。
你有一个用于存储凭据的现有密钥保管库。详细了解如何在密钥保管库中创建和存储凭据。
可以在密钥保管库中设置和检索机密。详细了解如何在密钥保管库中设置和检索机密。

不使用凭据配置和创建缓存规则。

运行 az acr Cache create 命令以创建缓存规则。
- 例如，在不使用给定 MyRegistry Azure 容器注册表的凭据集的情况下创建缓存规则。
```
az acr Cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu-
```
运行 az acr Cache show 命令以显示缓存规则。
- 例如，显示给定 MyRegistry Azure 容器注册表的缓存规则。
```
 az acr Cache show -r MyRegistry -n MyRule
```

创建凭据

在配置凭据之前，必须在 Azure 密钥保管库中创建和存储机密，并从密钥保管库检索机密。详细了解如何在密钥保管库中创建和存储凭据。在密钥保管库中设置和检索机密。

运行 az acr credential set create 命令以创建凭据。

例如，为给定 MyRegistry Azure 容器注册表创建凭据。

az acr credential-set create 
-r MyRegistry \
-n MyDockerHubCredSet \
-l docker.io \ 
-u https://MyKeyvault.vault.azure.cn/secrets/usernamesecret \
-p https://MyKeyvault.vault.azure.cn/secrets/passwordsecret

运行 az acr credential set update 以更新凭据集上的用户名或密码 KV 机密 ID。
- 例如，更新给定 MyRegistry Azure 容器注册表的凭据上的用户名或密码 KV 机密 ID。
```
az acr credential-set update -r MyRegistry -n MyDockerHubCredSet -p https://MyKeyvault.vault.azure.cn/secrets/newsecretname
```
运行 az acr credential-set show 以显示凭据。
- 例如，显示给定 MyRegistry Azure 容器注册表中的凭据集。
```
az acr credential-set show -r MyRegistry -n MyDockerHubCredSet
```

使用凭据配置和创建缓存规则

运行 az acr cache create 命令以创建缓存规则。
- 例如，使用给定 MyRegistry Azure 容器注册表的凭据创建缓存规则。
```
az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyDockerHubCredSet
```
运行 az acr cache update 命令以更新缓存规则上的凭据。
- 例如，更新给定 MyRegistry Azure 容器注册表的缓存规则上的凭据。
```
az acr cache update -r MyRegistry -n MyRule -c NewCredSet
```
- 例如，从给定 MyRegistry Azure 容器注册表的现有缓存规则中删除凭据。
```
az acr cache update -r MyRegistry -n MyRule --remove-cred-set
```
运行 az acr cache show 命令以显示缓存规则。
- 例如，显示给定 MyRegistry Azure 容器注册表的缓存规则。
```
 az acr cache show -r MyRegistry -n MyRule
```

使用访问策略向 Azure Key Vault 分配权限（旧版）

获取用于访问密钥保管库的系统标识的主体 ID。

PRINCIPAL_ID=$(az acr credential-set show 
                -n MyDockerHubCredSet \ 
                -r MyRegistry  \
                --query 'identity.principalId' \ 
                -o tsv)

在拉取映像之前，运行 az keyvault set-policy 命令以分配对密钥保管库的访问权限。
- 例如，若要为凭据分配权限，请访问密钥保管库机密
```
az keyvault set-policy --name MyKeyVault \
--object-id $PRINCIPAL_ID \
--secret-permissions get
```

拉取映像

使用 Docker 命令按注册表登录服务器名称、存储库名称及其所需标记从缓存中拉取映像。
- 例如，使用给定注册表登录服务器 myregistry.azurecr.cn 的所需标记 latest 从存储库 hello-world 中拉取映像。
```
 docker pull myregistry.azurecr.cn/hello-world:latest
```

清理资源

运行 az acr cache list 命令以列出 Azure 容器注册表中的缓存规则。
- 例如，列出给定 MyRegistry Azure 容器注册表的缓存规则。
```
 az acr cache list -r MyRegistry
```
运行 az acr cache delete 命令以删除缓存规则。
- 例如，删除给定 MyRegistry Azure 容器注册表的缓存规则。
```
az acr cache delete -r MyRegistry -n MyRule
```
运行 az acr credential set list 以列出 Azure 容器注册表中的凭据。
- 例如，列出给定 MyRegistry Azure 容器注册表的凭据。
```
az acr credential-set list -r MyRegistry
```
运行 az acr credential-set delete 以删除凭据。
- 例如，删除给定 MyRegistry Azure 容器注册表的凭据。
```
az acr credential-set delete -r MyRegistry -n MyDockerHubCredSet
```

启用工件缓存 - Azure 门户

可以按照以下步骤在 Azure 容器注册表中使用 Azure 门户启用工件缓存（无论是否进行身份验证）。

先决条件

登录到 Azure 门户
你有一个用于存储凭据的现有密钥保管库。详细了解如何在密钥保管库中创建和存储凭据。
你现有的密钥保管库没有基于角色的访问控制 (RBAC)。

不使用凭据配置工件缓存

按步骤在 Azure 门户中创建缓存规则。

导航到你的 Azure 容器注册表。
在边侧“菜单”中的“服务”下，选择“缓存”。
选择“创建规则”。
此时会显示“新建缓存规则”的窗口。
输入“规则名称”。
从下拉菜单中选择“源”注册表。
输入要缓存的工件的“存储库路径”。
如果未访问专用存储库或执行经过身份验证的拉取，则可跳过“身份验证”。
在“目标”下，输入用于存储缓存工件的“新建 ACR 存储库命名空间”的名称。
选择“保存”。
使用 Docker 命令按注册表登录服务器名称、存储库名称及其所需标记从缓存中拉取映像。
- 例如，使用给定注册表登录服务器 myregistry.azurecr.cn 的所需标记 latest 从存储库 hello-world 中拉取映像。
```
 docker pull myregistry.azurecr.cn/hello-world:latest
```

配置带身份验证的工件缓存

按步骤在 Azure 门户中创建缓存规则。

导航到你的 Azure 容器注册表。
在边侧“菜单”中的“服务”下，选择“缓存”。
选择“创建规则”。
此时会显示“新建缓存规则”的窗口。
输入“规则名称”。
从下拉菜单中选择“源”注册表。
输入要缓存的工件的“存储库路径”。
若要为存储库添加身份验证，请选中“身份验证”框。
选择“创建新凭据”，以创建一组用于存储源注册表用户名和密码的新凭据。了解如何创建新凭据。
如果你已准备好凭据，请从下拉菜单中选择凭据。
在“目标”下，输入用于存储缓存工件的“新建 ACR 存储库命名空间”的名称。
选择“保存”。
使用 Docker 命令按注册表登录服务器名称、存储库名称及其所需标记从缓存中拉取映像。
- 例如，使用给定注册表登录服务器 myregistry.azurecr.cn 的所需标记 latest 从存储库 hello-world 中拉取映像。
```
 docker pull myregistry.azurecr.cn/hello-world:latest
```

创建新凭据

在配置凭据之前，必须在 Azure Key Vault 中创建和存储机密，并从 Key Vault 检索机密。详细了解如何在密钥保管库中创建和存储凭据。在密钥保管库中设置和检索机密。

导航到“凭据”>“创建凭据”。
输入源注册表的新凭据的名称。
选择一个源身份验证。工件缓存当前支持“从 Key Vault 中选择”和“输入机密 URI”。
对于“从密钥保管库选择”选项，请详细了解如何使用密钥保管库创建凭据。
选择“创建”。

后续步骤

请转到下一篇文章阅读注册表缓存的故障排除指南。

通过

Azure 容器注册表中的工件缓存

术语

限制

上游支持

通配符

注册表级别通配符

存储库级别通配符

基于通配符的缓存规则的限制

静态/固定缓存规则的限制

启用工件缓存 - Azure CLI

先决条件

不使用凭据配置和创建缓存规则。

创建凭据

使用凭据配置和创建缓存规则

使用访问策略向 Azure Key Vault 分配权限（旧版）

拉取映像

清理资源

启用工件缓存 - Azure 门户

先决条件

不使用凭据配置工件缓存

配置带身份验证的工件缓存

创建新凭据

后续步骤

其他资源