Azure Container Registry 中的成品快取

發行項
09/29/2024

成品快取功能可讓使用者快取私人容器登錄中的容器映像。成品快取可在基本、標準和進階服務層級中使用。

成品快取藉由提供公用和私人存放庫的快取解決方案，來增強容器映像管理。

成品快取透過 Azure Container Registry (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 Elastic Container Registry (ECR) 公用資源庫	僅支援未經驗證的提取。	Azure CLI、Azure 入口網站
GitHub Container Registry	同時支援已驗證和未驗證的提取。	Azure CLI、Azure 入口網站
Quay	同時支援已驗證和未驗證的提取。	Azure CLI、Azure 入口網站
registry.k8s.io	同時支援已驗證和未驗證的提取。	Azure CLI
Google Container Registry	同時支援已驗證和未驗證的提取。	Azure CLI

萬用字元

萬用字元會使用星號 (*) 來比對容器映像登錄內的多個路徑。成品快取目前支援下列萬用字元：

注意

來自目標存放庫 => 來源存放庫的快取規則對應。

登錄層級萬用字元

登錄層級萬用字元可讓您從上游登錄快取所有存放庫。

快取規則	對應	範例
contoso.azurecr.io/* => mcr.microsoft.com/*	將 ACR 下的所有映像對應至 MCR。	contoso.azurecr.io/myapp/image1 => mcr.microsoft.com/myapp/image1 contoso.azurecr.io/myapp/image2 => mcr.microsoft.com/myapp/image2

存放庫層級萬用字元

存放庫層級萬用字元可讓您快取上游登錄中對應到存放庫前置詞的所有存放庫。

快取規則	對應	範例
contoso.azurecr.io/dotnet/* => mcr.microsoft.com/dotnet/*	將 ACR 下的特定存放庫對應至 MCR 中的相對應存放庫。	contoso.azurecr.io/dotnet/sdk => mcr.microsoft.com/dotnet/sdk contoso.azurecr.io/dotnet/runtime => mcr.microsoft.com/dotnet/runtime
contoso.azurecr.io/library/dotnet/* => mcr.microsoft.com/dotnet/* contoso.azurecr.io/library/python/* => docker.io/library/python/*	將 ACR 下的特定存放庫對應至不同上游登錄中的存放庫。	contoso.azurecr.io/library/dotnet/app1 => mcr.microsoft.com/dotnet/app1 contoso.azurecr.io/library/python/app3 => docker.io/library/python/app3

萬用字元型快取規則的限制

萬用字元快取規則會使用星號 (*) 來比對容器映像登錄內的多個路徑。這些規則不能與其他萬用字元快取規則重疊。換句話說，如果您對某個登錄路徑有萬用字元快取規則，則無法新增與它重疊的另一個萬用字元規則。

以下是重疊規則的一些範例：

範例 1：

現有的快取規則：contoso.azurecr.io/* => mcr.microsoft.com/*
正在新增的新快取：contoso.azurecr.io/library/* => docker.io/library/*

新增快取規則會被阻止，因為目標存放庫路徑 contoso.azurecr.io/library/* 與現有的萬用字元規則 contoso.azurecr.io/* 重疊。

範例 2：

現有的快取規則：contoso.azurecr.io/library/* =>mcr.microsoft.com/library/*
正在新增的新快取：contoso.azurecr.io/library/dotnet/* =>docker.io/library/dotnet/*

新增快取規則會被阻止，因為目標存放庫路徑 contoso.azurecr.io/library/dotnet/* 與現有的萬用字元規則 contoso.azurecr.io/library/* 重疊。

靜態/固定快取規則的限制

靜態或固定快取規則更具體，且不使用萬用字元。它們可以與萬用字元型快取規則重疊。如果快取規則指定固定存放庫路徑，則允許它與萬用字元型快取規則重疊。

範例 1：

現有的快取規則：contoso.azurecr.io/* =>mcr.microsoft.com/*
正在新增的新快取：contoso.azurecr.io/library/dotnet =>docker.io/library/dotnet

允許新增快取規則，因為 contoso.azurecr.io/library/dotnet 是靜態路徑，而且可以與萬用字元快取規則 contoso.azurecr.io/* 重疊。

啟用成品快取 - Azure CLI

您可以遵循下列步驟，在 Azure Container Registry 中使用或不使用 Azure CLI 驗證來啟用成品快取。

必要條件

您可以使用 Azure Cloud Shell，或安裝在本機的 Azure CLI 以執行本文中的命令範例。如果想要在本機使用，則需要 2.46.0 版或更新版本。執行 az --version 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。
您現有的 Key Vault 可儲存認證。深入了解如何在 Key Vault 中建立和儲存認證。
您可以從 Key Vault 設定和擷取祕密。深入了解如何從 Key Vault 設定和擷取祕密。

設定並建立不含認證的快取規則。

執行 az acr Cache create 命令以建立快取規則。
- 例如，在不使用認證的情況下，為指定 MyRegistry Azure Container Registry 建立快取規則。
```
az acr Cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu-
```
執行 az acr Cache show 命令以顯示快取規則。
- 例如，顯示指定 MyRegistry Azure Container Registry 的快取規則。
```
 az acr Cache show -r MyRegistry -n MyRule
```

建立認證

設定認證之前，您必須在 Azure KeyVault 中建立和儲存祕密，並從 Key Vault 擷取祕密。深入了解如何在 Key Vault 中建立和儲存認證 (部分機器翻譯)。以及從 Key Vault 設定及擷取祕密。

執行 az acr credential set create 命令以建立認證。

例如，為指定的 MyRegistry Azure Container Registry 建立認證。

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

執行 az acr credential set update 以更新認證集上的使用者名稱或密碼 KV 祕密識別碼。
- 例如，為指定的 MyRegistry Azure Container Registry 更新認證上的使用者名稱或密碼 KV 祕密識別碼。
```
az acr credential-set update -r MyRegistry -n MyDockerHubCredSet -p https://MyKeyvault.vault.azure.net/secrets/newsecretname
```
執行 az acr credential-set show 以顯示認證。
- 例如，在指定的 MyRegistry Azure Container Registry 中顯示認證集。
```
az acr credential-set show -r MyRegistry -n MyDockerHubCredSet
```

使用認證設定和建立快取規則

執行 az acr cache create 命令以建立快取規則。
- 例如，為指定的 MyRegistry Azure Container Registry，建立具有認證的快取規則。
```
az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyDockerHubCredSet
```
執行 az acr cache update 命令，以更新快取規則上的認證。
- 例如，為指定的 MyRegistry Azure Container Registry 更新快取規則上的認證。
```
az acr cache update -r MyRegistry -n MyRule -c NewCredSet
```
- 例如，從指定 MyRegistry Azure Container Registry 的現有快取規則中移除認證。
```
az acr cache update -r MyRegistry -n MyRule --remove-cred-set
```
執行 az acr cache show 命令以顯示快取規則。
- 例如，顯示指定 MyRegistry Azure Container Registry 的快取規則。
```
 az acr cache show -r MyRegistry -n MyRule
```

使用存取原則將權限指派給金鑰保存庫（舊版）

取得用以存取 Key Vault 的系統身分識別主體標識碼。

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

執行 az keyvault set-policy 命令，以在提取映像之前，將存取權指派給 Key Vault。
- 例如，指派認證存取 KeyVault 祕密的權限
```
az keyvault set-policy --name MyKeyVault \
--object-id $PRINCIPAL_ID \
--secret-permissions get
```

提取您的映像

使用 Docker 命令，依據登錄登入伺服器名稱、存放庫名稱及其所需標籤從快取提取映像。
- 例如，針對指定的登錄登入伺服器 myregistry.azurecr.io，從所需標籤為 latest 的存放庫 hello-world 提取映像。
```
 docker pull myregistry.azurecr.io/hello-world:latest
```

清除資源

執行 az acr cache list 命令，以列出 Azure Container Registry 中的快取規則。
- 例如，列出指定 MyRegistry Azure Container Registry 的快取規則。
```
 az acr cache list -r MyRegistry
```
執行 az acr cache delete 命令，以刪除快取規則。
- 例如，刪除指定 MyRegistry Azure Container Registry 的快取規則。
```
az acr cache delete -r MyRegistry -n MyRule
```
執行 az acr credential set list，以列出 Azure Container Registry 中的認證。
- 例如，列出指定 MyRegistry Azure Container Registry 的認證。
```
az acr credential-set list -r MyRegistry
```
執行 az acr credential-set delete 以刪除認證。
- 例如，刪除指定 MyRegistry Azure Container Registry 的認證。
```
az acr credential-set delete -r MyRegistry -n MyDockerHubCredSet
```

啟用成品快取 - Azure 入口網站

您可以遵循下列步驟，在 Azure Container Registry 中使用或不使用 Azure 入口網站驗證來啟用成品快取。

必要條件

登入 Azure 入口網站
您有現有的 Key Vault 可儲存認證。深入了解如何在 Key Vault 中建立和儲存認證。
您具備現有的金鑰保存庫，但沒有角色型存取 (RBAC) 控制項。

在沒有認證的情況下設定成品快取

請遵循在 Azure 入口網站建立快取規則的步驟。

瀏覽至您的 Azure Container Registry。
在側邊 [功能表]，[服務] 下，選取 [快取]。
選取 [建立規則]。
[新增快取規則] 的視窗隨即出現。
輸入 [規則名稱]。
從下拉功能表中選取 [來源] 登錄。
輸入您要快取之成品 [存放庫路徑]。
如果您未存取私人存放庫或執行已驗證的提取，則可以略過 [驗證]。
在 [目的地] 下，輸入 [新增 ACR 存放庫命名空間] 的名稱來儲存快取的成品。
選取 [儲存]。
使用 Docker 命令，依據登錄登入伺服器名稱、存放庫名稱及其所需標籤從快取提取映像。
- 例如，針對指定的登錄登入伺服器 myregistry.azurecr.io，從所需標籤為 latest 的存放庫 hello-world 提取映像。
```
 docker pull myregistry.azurecr.io/hello-world:latest
```

設定具有驗證的成品快取

請遵循在 Azure 入口網站建立快取規則的步驟。

瀏覽至您的 Azure Container Registry。
在側邊 [功能表]，[服務] 下，選取 [快取]。
選取 [建立規則]。
[新增快取規則] 的視窗隨即出現。
輸入 [規則名稱]。
從下拉功能表中選取 [來源] 登錄。
輸入您要快取的成品 [存放庫路徑]。
若要將驗證新增至存放庫，請核取 [驗證] 方塊。
選擇 [建立新的認證] 以建立一組新的認證，儲存來源登錄的使用者名稱和密碼。了解如何建立新的認證。
如果您已備妥認證，請從下拉式功能表中選取認證。
在 [目的地] 下，輸入 [新增 ACR 存放庫命名空間] 的名稱來儲存快取的成品。
選取 [儲存]。
使用 Docker 命令，依據登錄登入伺服器名稱、存放庫名稱及其所需標籤從快取提取映像。
- 例如，針對指定的登錄登入伺服器 myregistry.azurecr.io，從所需標籤為 latest 的存放庫 hello-world 提取映像。
```
 docker pull myregistry.azurecr.io/hello-world:latest
```

建立新的認證

瀏覽至 [認證]>[建立認證]。
針對來源登錄的新認證，輸入 [名稱]。
選取 [來源驗證]。成品快取目前支援 [從 Key Vault 選取] 和 [輸入祕密 URI]。
針對 [從 Key Vault 選取] 選項，深入了解使用金鑰保存庫建立認證。
選取 [建立]。

下一步

請前進到下一篇文章，以查看登錄快取的疑難排解指南。

共用方式為

Azure Container Registry 中的成品快取

詞彙

限制

上游支援