Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The artifact cache feature of Azure Container Registry lets you cache container images in both public and private repositories.
Artifact cache enables faster and more reliable pull operations through Azure Container Registry (ACR). It uses features like geo-replication and availability zone support for higher availability and faster image pulls. You can access cached registries over private networks to align with your firewall configurations and compliance standards.
Artifact cache addresses the challenge of pull limits imposed by public registries. We recommend authenticating your cache rules with your upstream source credentials. Then, you can pull images from the local ACR, helping to mitigate rate limits.
The artifact cache feature is available in Basic, Standard, and Premium service tiers. You can enable artifact cache rules in the Azure portal or by using Azure CLI.
Terminology
When working with artifact caching, it's helpful to understand the following terminology:
Cache Rule: A rule you create to pull artifacts from a supported repository into your cache. A cache rule contains four parts:
- Rule name: The name of your cache rule. For example,
Hello-World-Cache. - Source: The name of the source registry.
- Repository path: The source path of the repository to find and retrieve artifacts you want to cache. For example,
docker.io/library/hello-world. - New ACR repository namespace: The name of the new repository path to store artifacts. For example,
hello-world. The repository can't already exist inside the ACR instance.
- Rule name: The name of your cache rule. For example,
Credentials: A username and password set for the source registry. You require credentials to authenticate with a public or private repository. Credentials contain four parts:
- Credentials: The name of your credentials.
- Source registry login server: The login server of your source registry.
- Source authentication: The key vault locations to store credentials.
- Username and password secrets: Secrets containing the username and password.
Current limitations
When using artifact cache, keep in mind the following limitations:
- Cache only occurs after at least one image pull is complete on the available container image. For every new image available, a new image pull must be complete. Currently, artifact cache doesn't automatically pull new tags of images when a new tag is available.
- Artifact cache supports a maximum of 1,000 cache rules.
- Artifact cache rules can't overlap with other cache rules. In other words, if you have an artifact cache rule for a certain registry path, you can't add another cache rule that overlaps with it.
Upstream support
Artifact cache currently supports the following upstream registries.
Warning
To source content from Docker Hub, you must generate a credential set by using Azure CLI or the Azure portal.
Some public Docker Hub images are mapped to the publicly accessed namespace library. In this case, if you don't include the library path, artifact cache will automatically include it for you.
| Upstream registry | Support | Availability |
|---|---|---|
| Docker Hub | Supports authenticated pulls only. | Azure CLI, Azure portal |
| Microsoft Artifact Registry | Supports unauthenticated pulls only. | Azure CLI, Azure portal |
| AWS Elastic Container Registry (ECR) Public Gallery | Supports unauthenticated pulls only. | Azure CLI, Azure portal |
| GitHub Container Registry | Supports both authenticated and unauthenticated pulls. | Azure CLI, Azure portal |
| Quay | Supports both authenticated and unauthenticated pulls. | Azure CLI, Azure portal |
Kubernetes Container Image Registry (registry.k8s.io) |
Supports both authenticated and unauthenticated pulls. | Azure CLI |
Google Artifact Registry (*.pkg.dev) |
Supports authenticated pulls only. | Azure CLI |
Legacy Google Container Registry (gcr.io) |
Supports both authenticated and unauthenticated pulls. | Azure CLI |
Authentication method for Google Artifact Registry
To set up Artifact Cache from your private Google Artifact Registry (GAR), we recommend using a Service Account Key (created in Google Cloud's Console) to authenticate with GAR. You can define a custom expiry date for the Service Account key (for example, 3 months) and persist the key in Azure Key Vault.
Although you could use an access token (generated from gcloud CLI) to authenticate, it is not recommended for use with Artifact Cache, because the access token expires after 1 hour.
For more information about how to create a Service Account Key, see Authenticate with Google Artifact Registry. After you have the Service Account Key, save it as a secret in Azure Key Vault. Then point your credential set's password to this secret. The username should be set to:
_json_keyif you are using the service account key in JSON format as it was provided when you created the file._json_key_base64if you base64-encoded all of the contents of the account key file.
For more information about how to create a credential set, follow the links in the next section.
Next steps
- Learn how to enable artifact caching using the Azure portal or Azure CLI.
- Learn about using wildcards to match multiple paths within the container image registry.