使用 Azure CLI 在 Azure 容器注册表中启用项目缓存

项目
2025-03-27

本文介绍如何使用 Azure CLI 在 Azure 容器注册表（ACR）中启用项目缓存功能，或者不使用 Azure CLI 进行身份验证。

除了此处列出的先决条件之外，还需要具有活动订阅的 Azure 帐户。创建试用订阅。

先决条件

Azure CLI。可以使用 Azure CLI 的本地安装来运行本文中的命令。如果想要在本地使用它，则需要 Azure CLI 2.46.0 或更高版本。若要确认 Azure CLI 版本，请运行 az --version。若要安装或升级，请参阅安装 Azure CLI。
现有的 ACR 实例。如果你还没有容器注册表，可以使用快速入门创建一个新的容器注册表。
现有的密钥保管库，用于创建和存储凭据。
有权设置和检索密钥保管库中的机密。

在本文中，我们使用名为 MyRegistry的示例 ACR 实例。

创建凭据

在配置凭据之前，请确保能够在 Azure Key Vault 中创建和存储机密，并从 Key Vault 检索机密。。

若要创建凭据，请运行 az acr credential set create：

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

若要更新凭据集上的用户名或密码 Key Vault 机密 ID，请运行 az acr credential set update：

az acr credential-set update -r MyRegistry -n MyDockerHubCredSet -p https://MyKeyvault.vault.azure.cn/secrets/newsecretname

若要显示凭据，请运行 az acr credential-set show：

az acr credential-set show -r MyRegistry -n MyDockerHubCredSet

创建缓存规则

接下来，创建并配置缓存规则，用于将工件从存储库拉取到缓存中。

若要创建新的缓存规则，请运行 az acr cache create：

az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyDockerHubCredSet

若要更新缓存规则上的凭据，请运行 az acr cache update：
```
az acr cache update -r MyRegistry -n MyRule -c NewCredSet
```
如果需要删除凭据，请运行 az acr cache update -r MyRegistry -n MyRule --remove-cred-set。
若要显示缓存规则，请运行 az acr cache show：
```
 az acr cache show -r MyRegistry -n MyRule
```

提示

若要创建不使用凭据的缓存规则，请使用不指定凭据的相同命令。例如，az acr cache create -r MyRegistry -n MyRule -s dockerhub.io/library/ubuntu -t ubuntu。对于某些源（如 Docker 中心），需要凭据才能创建缓存规则。

使用访问策略向 Key Vault 分配权限

可以使用访问策略向用户分配适当的权限，以便他们可以访问 Azure KeyVault。

获取用于访问 Key Vault 的系统身份的主要标识符：

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

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

拉取映像

使用 Docker 命令，通过注册表登录服务器名称、存储库名称和所需标记，从缓存中拉取镜像。例如，要从存储库 hello-world 拉取带有标签 latest 的映像到注册表登录服务器 myregistry.azurecr.cn，请运行：

 docker pull myregistry.azurecr.cn/hello-world:latest

清理资源

不再需要时，请删除创建的缓存规则和凭据。

若要删除缓存规则，请运行 az acr cache delete：
```
az acr cache delete -r MyRegistry -n MyRule
```

若要删除凭据，请运行 az acr credential-set delete：

az acr credential-set delete -r MyRegistry -n MyDockerHubCredSet

后续步骤

了解如何排查工件缓存的问题。
了解如何使用 Azure 门户启用工件缓存。

通过