1---2name: azure-container-registry3description: Expert knowledge for Azure Container Registry development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when using ACR Tasks, geo-replication/connected registries, Defender scans, Notation signing, or AKS/ACI pulls, and other Azure Container Registry related development tasks. Not for Azure Container Apps (use azure-container-apps), Azure Container Instances (use azure-container-instances), Azure Kubernetes Service (AKS) (use azure-kubernetes-service), Azure Red Hat OpenShift (use azure-redhat-openshift).4---5# Azure Container Registry Skill
6
7This skill provides expert guidance for Azure Container Registry. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.
8
9## How to Use This Skill
10
11> **IMPORTANT for Agent**: Use the **Category Index** below to locate relevant sections. For categories with line ranges (e.g., `L35-L120`), use `read_file` with the specified lines. For categories with file links (e.g., `[security.md](security.md)`), use `read_file` on the linked reference file
12
13> **IMPORTANT for Agent**: If `metadata.generated_at` is more than 3 months old, suggest the user pull the latest version from the repository. If `mcp_microsoftdocs` tools are not available, suggest the user install it: [Installation Guide](https://github.com/MicrosoftDocs/mcp/blob/main/README.md)
14
15This skill requires **network access** to fetch documentation content:
16- **Preferred**: Use `mcp_microsoftdocs:microsoft_docs_fetch` with query string `from=learn-agent-skill`. Returns Markdown.
17- **Fallback**: Use `fetch_webpage` with query string `from=learn-agent-skill&accept=text/markdown`. Returns Markdown.
18
19## Category Index
20
21| Category | Lines | Description |
22|----------|-------|-------------|
23| Troubleshooting | L37-L52 | Diagnosing and fixing ACR issues: health checks, error codes, login/auth, network and performance problems, transfer/streaming/cache failures, logs, Arc/connected registry, and CMK encryption. |
24| Best Practices | L53-L60 | Best practices for ACR operations: managing public image dependencies, safe image deletion and storage cleanup, and robust image tagging/versioning strategies. |
25| Decision Making | L61-L66 | Guidance on choosing Kubernetes auth methods (managed identity, service principals, workload identity) for ACR and migrating image signing from Docker Content Trust to Notary Project. |
26| Architecture & Design Patterns | L67-L74 | Patterns for ACR performance and governance: caching image pulls, geo-replication strategies, connected registries for edge/offline, and gated import workflows for public images. |
27| Limits & Quotas | L75-L80 | ACR SKU comparisons, throughput and request limits, and how image/storage capacity, retention, and performance quotas work across registry tiers. |
28| Security | L81-L120 | Securing ACR with auth, RBAC/ABAC, network controls, encryption, image signing/verification, policies, Defender scans, and managed identity/Key Vault integration. |
29| Configuration | L121-L138 | Configuring ACR behavior: caching, purge/retention/soft delete, delete locks, webhooks, metrics/logs, and defining/scheduling multi-step ACR Tasks with YAML and agent pools. |
30| Integrations & Coding Patterns | L139-L154 | How to integrate ACR with ACI, AKS, Helm, ORAS, Buildpacks, ACR Transfer, GitHub Actions, Notation, Key Vault, and webhooks for image access, builds, signing, and automation |
31| Deployment | L155-L160 | Using ARM templates to automate ACR quick tasks and data transfer, and deploying/managing ACR connected registries via Azure Arc extension |
32
33### Troubleshooting
34| Topic | URL |
35|-------|-----|
36| Run az acr check-health for quick ACR diagnostics | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-check-health |
37| Azure Container Registry FAQ and known issues | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-faq |
38| Interpret az acr check-health error codes and fixes | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-health-error-reference |
39| View and manage Azure Container Registry task run logs | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-logs |
40| Troubleshoot Azure Container Registry Transfer failures | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-transfer-troubleshooting |
41| Troubleshoot Azure Container Registry network connectivity | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-troubleshoot-access |
42| Troubleshoot ACR login, authentication, and authorization issues | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-troubleshoot-login-authn-authz |
43| Troubleshoot Azure Container Registry performance problems | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-troubleshoot-performance |
44| Troubleshoot Azure Container Registry artifact cache issues | https://learn.microsoft.com/en-us/azure/container-registry/troubleshoot-artifact-cache |
45| Diagnose and fix Azure Container Registry artifact streaming issues | https://learn.microsoft.com/en-us/azure/container-registry/troubleshoot-artifact-streaming |
46| Troubleshoot connected registry Arc extension issues | https://learn.microsoft.com/en-us/azure/container-registry/troubleshoot-connected-registry-arc |
47| Troubleshoot customer-managed key issues in ACR | https://learn.microsoft.com/en-us/azure/container-registry/tutorial-troubleshoot-customer-managed-keys |
48
49### Best Practices
50| Topic | URL |
51|-------|-----|
52| Manage public image dependencies using ACR | https://learn.microsoft.com/en-us/azure/container-registry/buffer-gate-public-content |
53| Follow operational best practices for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-best-practices |
54| Delete ACR images safely to manage registry storage | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-delete |
55| Apply image tagging and versioning best practices in ACR | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-image-tag-version |
56
57### Decision Making
58| Topic | URL |
59|-------|-----|
60| Select Kubernetes authentication options for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/authenticate-kubernetes-options |
61| Migrate ACR signing from DCT to Notary Project | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-content-trust-deprecation |
62
63### Architecture & Design Patterns
64| Topic | URL |
65|-------|-----|
66| Optimize image pulls with ACR artifact cache | https://learn.microsoft.com/en-us/azure/container-registry/artifact-cache-overview |
67| Use geo-replication patterns with Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-geo-replication |
68| Design and use connected registries with ACR | https://learn.microsoft.com/en-us/azure/container-registry/intro-connected-registry |
69| Implement gated import workflow for public images in ACR | https://learn.microsoft.com/en-us/azure/container-registry/tasks-consume-public-content |
70
71### Limits & Quotas
72| Topic | URL |
73|-------|-----|
74| Compare Azure Container Registry SKUs and limits | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-skus |
75| Understand storage features and limits in ACR | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-storage |
76
77### Security
78| Topic | URL |
79|-------|-----|
80| Allow trusted Azure services to access network-restricted ACR | https://learn.microsoft.com/en-us/azure/container-registry/allow-access-trusted-services |
81| Enable anonymous pull access for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/anonymous-pull-access |
82| Configure cross-tenant AKS authentication to Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/authenticate-aks-cross-tenant |
83| Restrict Azure Container Registry public access by IP rules | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-access-selected-networks |
84| Use Microsoft Entra service principals to access ACR | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal |
85| Choose and configure authentication methods for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication |
86| Configure managed identity authentication to Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication-managed-identity |
87| Use Azure Policy to audit ACR compliance | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-azure-policy |
88| Configure Microsoft Entra Conditional Access policies for ACR | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-configure-conditional-access |
89| Enable Docker Content Trust for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-content-trust |
90| Use dedicated data endpoints to mitigate ACR data exfiltration | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-dedicated-data-endpoints |
91| Control accepted Microsoft Entra auth scopes for ACR | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-disable-authentication-as-arm |
92| Configure firewall rules to allow access to Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-firewall-access-rules |
93| Configure Private Link private endpoints for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-private-link |
94| Use Azure ABAC for fine-grained ACR repository permissions | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-rbac-abac-repository-permissions |
95| Reference for Azure Container Registry built-in RBAC roles | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-rbac-built-in-roles-directory-reference |
96| Understand and assign Azure Container Registry built-in Entra roles | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-rbac-built-in-roles-overview |
97| Create and assign custom RBAC roles for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-rbac-custom-roles |
98| Use Azure Container Registry service tags for network rules | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-service-tag |
99| Access Key Vault secrets from ACR Tasks via managed identity | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-authentication-key-vault |
100| Configure managed identity for ACR Tasks | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-authentication-managed-identity |
101| Use managed identity for cross-registry auth in ACR Tasks | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-cross-registry-authentication |
102| Configure token-based repository permissions in Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-token-based-repository-permissions |
103| Sign ACR images with CA certs via Key Vault | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-trusted-ca |
104| Enforce AKS image signature verification with Ratify | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-verify-with-ratify-aks |
105| Restrict ACR access with virtual network service endpoints | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-vnet |
106| Disable artifact export to prevent ACR data exfiltration | https://learn.microsoft.com/en-us/azure/container-registry/data-loss-prevention |
107| Manage ACR Tasks network bypass policy with trusted services | https://learn.microsoft.com/en-us/azure/container-registry/manage-network-bypass-policy-for-tasks |
108| Reference of built-in Azure Policy definitions for ACR | https://learn.microsoft.com/en-us/azure/container-registry/policy-reference |
109| Configure client tokens to pull from connected registries | https://learn.microsoft.com/en-us/azure/container-registry/pull-images-from-connected-registry |
110| Scan ACR images with Microsoft Defender for Cloud | https://learn.microsoft.com/en-us/azure/container-registry/scan-images-defender |
111| Apply Azure Policy compliance controls to ACR | https://learn.microsoft.com/en-us/azure/container-registry/security-controls-policy |
112| Secure connected registry Arc extension deployments | https://learn.microsoft.com/en-us/azure/container-registry/tutorial-connected-registry-arc |
113| Configure customer-managed encryption keys for ACR | https://learn.microsoft.com/en-us/azure/container-registry/tutorial-customer-managed-keys |
114| Enable customer-managed keys on Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/tutorial-enable-customer-managed-keys |
115| Rotate and revoke customer-managed keys for ACR | https://learn.microsoft.com/en-us/azure/container-registry/tutorial-rotate-revoke-customer-managed-keys |
116
117### Configuration
118| Topic | URL |
119|-------|-----|
120| Configure artifact cache in ACR using Azure CLI | https://learn.microsoft.com/en-us/azure/container-registry/artifact-cache-cli |
121| Configure and schedule ACR purge for tags and manifests | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auto-purge |
122| Configure delete locks on ACR images and repositories | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-image-lock |
123| Configure retention policy for untagged ACR manifests | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-retention-policy |
124| Enable and configure ACR soft delete retention policy | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-soft-delete-policy |
125| Use multi-step ACR Tasks to build, test, and patch images | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-multi-step |
126| YAML schema reference for Azure Container Registry Tasks | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-reference-yaml |
127| Schedule Azure Container Registry Tasks with timers | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-scheduled |
128| Configure multi-step ACR Tasks for build workflows | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-multistep-task |
129| Webhook payload schema for Azure Container Registry events | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-webhook-reference |
130| Configure continuous patching for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/how-to-continuous-patching |
131| Monitoring metrics and logs reference for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/monitor-container-registry-reference |
132| Configure dedicated agent pools for ACR Tasks | https://learn.microsoft.com/en-us/azure/container-registry/tasks-agent-pools |
133| Configure wildcard cache rules for Azure Container Registry | https://learn.microsoft.com/en-us/azure/container-registry/wildcards-artifact-cache |
134
135### Integrations & Coding Patterns
136| Topic | URL |
137|-------|-----|
138| Grant Azure Container Instances access to ACR with service principals | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auth-aci |
139| Create Kubernetes pull secrets for Azure Container Registry access | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auth-kubernetes |
140| Host and manage Helm chart repositories in ACR | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-helm-repos |
141| Import container images into ACR using Azure APIs | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-import-images |
142| Manage OCI and supply chain artifacts in ACR with ORAS | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-manage-artifact |
143| Build images with Buildpacks using az acr pack build | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tasks-pack-build |
144| Use ACR Transfer with Azure CLI extension | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-transfer-cli |
145| Build, push, and sign ACR images in GitHub Actions with Notation | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-github-sign-notation-artifact-signing |
146| Verify signed ACR images in GitHub Actions workflows | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-github-verify-notation-artifact-signing |
147| Sign ACR images with Notation using Azure Key Vault certificates | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push |
148| Sign and verify ACR images using Notation and Artifact Signing | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-verify-notation-artifact-signing |
149| Configure ACR webhooks for registry event notifications | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-webhook |
150
151### Deployment
152| Topic | URL |
153|-------|-----|
154| Queue ACR quick task runs with ARM templates | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-task-run-template |
155| Automate ACR Transfer using ARM templates | https://learn.microsoft.com/en-us/azure/container-registry/container-registry-transfer-arm-template |
156| Deploy the ACR connected registry Arc extension | https://learn.microsoft.com/en-us/azure/container-registry/quickstart-connected-registry-arc-cli |
majiayu000