Troubleshoot guide for Artifact Cache

  • Article

This article is part four in a tutorial series. Part one provides an overview of Artifact Cache, its features, benefits, and limitations. In part two, you learn how to enable Artifact Cache feature by using the Azure CLI. In part three, you learn how to enable Artifact Cache feature with authentication by using Azure CLI.

This article helps you troubleshoot problems you might encounter when attempting to use Artifact Cache.

Symptoms and Causes

May include one or more of the following issues:

Potential Solutions

Cached images don't appear in a live repository

If you're having an issue with cached images not showing up in your repository in ACR, we recommend verifying the repository path. Incorrect repository paths lead the cached images to not show up in your repository in ACR.

  • The Login server for Docker Hub is docker.io.
  • The Login server for Microsoft Artifact Registry is mcr.microsoft.com.

The Azure portal autofills these fields for you. However, many Docker repositories begin with library/ in their path. For example, in-order to cache the hello-world repository, the correct Repository Path is docker.io/library/hello-world.

Unhealthy Credentials

Credentials are a set of Key Vault secrets that operate as a Username and Password for private repositories. Unhealthy Credentials are often a result of these secrets no longer being valid. In the Azure portal, you can select the credentials, to edit and apply changes.

  • Verify the secrets in Azure Key Vault haven't expired.
  • Verify the secrets in Azure Key Vault are valid.
  • Verify the access to the Azure Key Vault is assigned.

To assign the access to Azure Key Vault:

az keyvault set-policy --name myKeyVaultName --object-id myObjID --secret-permissions get

Learn more about Key Vaults. Learn more about Assigning the access to Azure Key Vault.

Unable to create a Cache rule

Cache rule Limit

If you're facing issues while creating a Cache rule, we recommend verifying if you have more than 1000 cache rules created.

We recommend deleting any unwanted cache rules to avoid hitting the limit.

Learn more about the Cache Terminology

Unable to create cache rule using a wildcard

If you're trying to create a cache rule, but there's a conflict with an existing rule. The error message suggests that there's already a cache rule with a wildcard for the specified target repository.

To resolve this issue, you need to follow these steps:

  1. Identify Existing cache rule causing the conflict. Look for an existing rule that uses a wildcard (*) for the target repository.

  2. Delete the conflicting cache rule that is overlapping source repository and wildcard.

  3. Create a new cache rule with the desired wildcard and target repository.

  4. Double-check your cache configuration to ensure that the new rule is correctly applied and there are no other conflicting rules.

Upstream support

Artifact Cache currently supports the following upstream registries:

Upstream registries Support Availability
Docker Hub Supports both authenticated pulls and unauthenticated pulls. Azure CLI, Azure portal
Microsoft Artifact Registry Supports unauthenticated pulls only. Azure CLI, Azure portal
ECR Public Supports unauthenticated pulls only. Azure CLI, Azure portal
GitHub Container Registry Supports both authenticated pulls and unauthenticated pulls. Azure CLI, Azure portal
Nvidia Supports both authenticated pulls and unauthenticated pulls. Azure CLI
Quay Supports both authenticated pulls and unauthenticated pulls. Azure CLI, Azure portal
registry.k8s.io Supports both authenticated pulls and unauthenticated pulls. Azure CLI