無法將映像從 Azure Container Registry 提取至 Azure Web 應用程式

發行項
08/22/2024

本文提供將映像從 Azure 容器登錄提取至 Azure Web 應用程式時可能遇到的最常見錯誤的疑難解答指引。

徵兆和初始疑難解答

建議您藉由檢查容器登錄健全狀況來啟動疑難解答。

若要檢查容器登錄健全狀況，請執行下列命令：

az acr check-health --name <myregistry> --ignore-errors --yes

如果偵測到問題，結果會包含錯誤碼和描述。如需這些錯誤和可能解決方案的詳細資訊，請參閱健康情況檢查錯誤參考。

注意

如果您收到 Helm 相關或 Notary 相關錯誤，這並不表示您的 Container Registry 或 AKS 無法運作或發生問題。它只會指出 Helm 或 Notary 未安裝，或 Azure CLI 與目前安裝的 Helm 或 Notary 版本不相容等問題。

接下來，找出需要疑難解答的提取相關錯誤訊息：

登入 Azure 入口網站。
在您的 Web 應用程式中，選取 [部署中心>記錄]。選取認可以檢視記錄詳細數據。您也可以在 [監視] 區段中檢查記錄數據流，以實時檢視映射提取程序的記錄。

下列各節可協助您針對 Web 應用程式記錄中顯示的最常見錯誤進行疑難解答。

錯誤 1：未經授權

Head \" https://<acr-name>.azurecr.io/v2/<repository>/manifests/<tag>\": unauthorized

系統管理使用者型驗證的解決方案

「未經授權」錯誤可能是由不正確的系統管理員認證所造成。這包括您在 Web 應用程式環境變數中設定的登入伺服器、使用者名稱或密碼。

若要解決此問題，請執行下列步驟：

在 Azure 入口網站中，流覽至您的登錄容器。在 [ 設定] 區段中，選取 [ 存取金鑰]。檢查登入伺服器、使用者名稱和密碼的管理員使用者認證設定。
流覽至您的 Web 應用程式。在 [設定] 區段中，選取 [環境變數]。
請確定為容器登錄設定的三個變數（登入伺服器、使用者名稱、密碼）符合登錄容器中的管理員使用者認證設定。

受控識別型驗證的解決方案

當您使用 Azure Web 應用程式的受控識別型驗證時， Microsoft.ContainerRegistry/registries/pull/read 必須將許可權指派給受控識別，才能執行提取動作。

包含許可權的 Microsoft.ContainerRegistry/registries/pull/read Azure 內建角色如下：

AcrPull
AcrPush
ReaderContributor
擁有者

如需詳細資訊，請參閱 Azure Container Registry 角色和權限。

當您從容器登錄起始提取作業時，AcrPull 角色會自動指派給 Azure Web 應用程式受控識別。您不需要手動新增許可權。不過，您必須確定不會封鎖角色指派建立，例如 Azure 原則。此外，請確認角色指派並未刪除。

錯誤 2：找不到標記標記的<>指令清單

DockerApiException : Docker API responded with status code=NotFound, response={"message":"manifest for <acr-name>.azurecr.io/<repository>:<tag> not found: manifest unknown: manifest tagged by \"<tag>\" is not found"}

解決方案：請確定標籤存在

錯誤訊息指出找不到與您嘗試提取之映像相關聯的標記。請確定標記存在於相關聯的存放庫和登錄內。

若要使用 Azure CLI 在相關聯的存放庫和登錄內尋找標籤，請執行下列命令：

az acr repository show-tags -n <ContainerRegistryName> --repository <RepositoryName>

若要使用 Azure 入口網站來尋找相關聯存放庫和登錄內的標籤，請遵循下列步驟：

流覽至您的登錄容器。在 [服務] 底下，選取 [存放庫]，開啟相關聯的存放庫，然後檢查卷標清單。

注意

az acr repository show-tags 命令，或檢查來自 Azure 入口網站的存放庫只有在容器登錄網路規則允許時才能運作。

錯誤 3：不允許具有 IP 的用戶端存取

DockerApiException: Docker API responded with status code=InternalServerError, response={"message":"Head \"https:// <acr-name>.azurecr.io/v2/<repository>/manifests/<tag>\": denied: client with IP '<web-app-outbound-ip>' is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}

解決方案 1：確定容器登錄內建防火牆允許裝置的 IP 位址

根據預設，容器登錄會接受來自所有網路的因特網連線。容器登錄具有內建防火牆，可限制特定IP位址或 CIDR 的存取，或完全停用公用網路存取。

如果容器登錄的內建防火牆封鎖 Web 應用程式的 IP 位址，就會發生此問題。

若要解決此問題，請確定內建防火牆允許必須提取映像之 Web 應用程式的輸出 IP 位址。

若要尋找 Web 應用程式的輸出 IP 位址，請遵循下列步驟：

在 Azure 入口網站中，流覽至您的 Web 應用程式。
在 [概觀] 頁面上，找出 [輸出 IP 位址]，然後選取 [ 顯示更多] 以取得輸出 IP 位址的完整清單

若要使用 Azure CLI 尋找 Web 應用程式的輸出 IP 位址，請參閱在 Azure App 服務中尋找輸出 IP 位址。

解決方案 2：設定 Web 應用程式的虛擬網路整合

如果您必須完全停用公用網路存取，或只允許容器登錄中選取的網路，而不需手動新增 Web 應用程式的 IP 位址，替代選項就是私下提取映像。若要私下提取映像，您必須使用私人端點來設定容器登錄，並啟用 Web 應用程式的虛擬網路整合。

您可以遵循下列步驟，在 Web 應用程式端設定虛擬網路整合：

在 Azure 入口網站中，流覽至您的 Web 應用程式，然後選取 [網络]。
在 [輸出流量設定] 下，設定 虛擬網絡整合，選取 [新增虛擬網络整合]，然後指定訂用帳戶、虛擬網路和子網。
在 [ 虛擬網络組態 ] 頁面上，確定 已選取 [容器映射提取 ] 選項。

若要透過虛擬網路提取映像，您必須在 Web 應用程式的部署中心啟用透過 VNet 的提取映像。此外，如果容器登錄已停用公用存取或設定為特定網路，您可能會收到「無法載入 ACR 標籤 - 失敗」訊息，如下列範例所示。此案例預期會發生該錯誤。如果發生這種情況，就無法使用 Image 和 Tag 的下拉式清單選項。您必須手動輸入影像和標籤。

下一步

如果此疑難解答指引無法解決問題，請考慮下列事項：

檢查與您的子網相關聯的網路安全組和路由表。如果虛擬設備，例如防火牆，控制子網之間的流量，請檢閱防火牆及其存取規則。

使用 Kudu 服務進行其他疑難解答。您可以連線到 Kudu 服務。例如，使用 Bash 執行來測試 DNS 解析 nslookup <acr-name>.azurecr.io，或使用檢查連線能力 tcpping <acr-name>.azurecr.io。

與我們連絡，以取得說明

如果您有問題或需要相關協助，請建立支援要求，或詢問 Azure community 支援。您也可以向 Azure 意見反應社群提交產品意見反應。

共用方式為