An ACR retention policy is a registry-level cleanup rule for untagged manifests in Azure Container Registry. When enabled on a supported registry, it schedules untagged manifests for deletion after the configured number of days, helping control storage growth while requiring care because deleted image data cannot be recovered.
An ACR retention policy is a registry-level cleanup rule for untagged manifests in Azure Container Registry. When enabled on a supported registry, it schedules untagged manifests for deletion after the configured number of days, helping control storage growth while requiring care because deleted image data cannot be recovered.
In Azure architecture, this term sits in the container artifact lifecycle: source code becomes an image or OCI artifact, the registry stores it, deployment platforms such as AKS and Azure Container Apps pull it, and operators use metadata to prove what was built, promoted, scanned, or removed. The control plane includes the ACR resource, repository settings, token or scope-map objects, task definitions, webhook definitions, and policy settings. The data plane includes pushes, pulls, tags, manifests, layers, and credential use by clients. A safe design treats registry content as production supply-chain evidence, not just files in a private Docker store. For ACR retention policy, the critical behavior is that only untagged manifests after the policy is enabled are scheduled for deletion. The setting is registry-level, works with the configured day window, and can remove image data that systems pulling by digest might still need.
Why it matters
This matters because container mistakes travel quickly. A wrong repository name, overly broad token, accidental tag deletion, missed rebuild, noisy webhook, or blind retention rule can break deployments, expose private images, raise storage cost, or hide the evidence needed during an incident. The practical habit is to ask what artifact boundary the term controls, who owns that boundary, which workload consumes it, what command proves the current state, and what rollback evidence must be preserved before a cleanup, credential, or automation change is made. For ACR retention policy, the most useful evidence is not the product label; it is the concrete output that shows current state, ownership, scope, and the next safe action.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
ACR retention settings
Signal 02
registry cleanup runbooks
Signal 03
image lifecycle governance
Signal 04
container storage cost reviews
Signal 05
az acr config retention commands
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Delete untagged manifests after a waiting period.
Reduce registry storage consumed by orphaned image data.
Pair cleanup policy with safe tagging and rollback standards.
Verify retention behavior before deleting image tags in production.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
ACR retention policy in action
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
BrightTrail Logistics pushed hundreds of CI images every week and discovered that untagged manifests were consuming registry storage long after release tags were deleted.
🎯Business/Technical Objectives
Reduce registry storage growth by at least 35% without deleting deployable images.
Keep rollback tags for 45 days after production release.
Avoid breaking systems that pull by manifest digest.
Create a repeatable cleanup policy owned by the platform team.
✅Solution Using ACR retention policy
The platform team enabled the ACR retention policy for untagged manifests in the Premium registry with a 30-day retention window. Before enabling it, they audited pipelines to confirm production workloads pulled by unique tags rather than untagged digests. Critical release images were protected by keeping approved tags and documenting when tags could be removed. Operators used `az acr config retention show` to confirm status and `az acr manifest list-metadata` to sample repositories after cleanup. The policy was paired with a tagging standard so cleanup removed orphaned manifests instead of valid rollback candidates.
📈Results & Business Impact
Monthly ACR storage growth fell 42% after the first cleanup cycle.
No production image pulls failed during the 90-day rollout period.
Manual registry cleanup work dropped from 12 hours per month to less than 2.
Finance attributed $18,000 in annualized savings to registry storage reduction.
💡Key Takeaway for Glossary Readers
An ACR retention policy is valuable when cleanup is tied to a tagging and rollback strategy, not used as a blind delete switch.
Case study 02
ACR retention policy in action
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
Aurelia Bank ran secure build pipelines for microservices, but developers frequently deleted tags during retesting, leaving hidden untagged manifests in the registry.
🎯Business/Technical Objectives
Remove stale untagged manifests after a controlled waiting period.
Protect golden base images and compliance-approved release images.
Lower storage cost without increasing deployment risk.
Give auditors evidence that container cleanup was governed.
✅Solution Using ACR retention policy
The container platform group enabled retention for untagged manifests with a 60-day value because the bank required two monthly release cycles of rollback evidence. They first locked critical base image manifests, verified the `delete-enabled` setting for protected artifacts, and changed pipelines to use unique release tags. The cleanup policy was documented as applying only after a manifest became untagged and after the retention window elapsed. Azure CLI checks were added to show the registry policy, list manifest metadata, and confirm candidate repositories. The team treated deletion as unrecoverable, so emergency rollback images stayed tagged until release management approved removal. The runbook also recorded the owner, scope, verification command, rollback contact, and evidence to save after the change so operators could repeat the pattern safely.
📈Results & Business Impact
Registry storage dropped 29% without deleting any approved rollback image.
Container cleanup evidence was added to quarterly control testing.
Build-agent cleanup tickets decreased by 63%.
The policy reduced hidden orphaned artifacts across 112 repositories.
💡Key Takeaway for Glossary Readers
Retention works best when teams understand that untagged image data can still matter to production.
Case study 03
ACR retention policy in action
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
MetroLearn Education operated a shared registry for online learning services and wanted a low-maintenance way to stop experimental images from accumulating indefinitely.
🎯Business/Technical Objectives
Keep developer experiment images from filling the registry.
Limit cleanup changes to untagged manifests only.
Keep production tags and long-term support images untouched.
Create a monthly storage dashboard for the registry owner.
✅Solution Using ACR retention policy
The team moved all experimental images into clearly named repositories and trained developers to remove only experiment tags when work ended. They then enabled the ACR retention policy for untagged manifests with a 14-day period. Production images used stable release tags and were excluded from cleanup by process because they remained tagged. The registry owner scheduled a monthly check that compared ACR usage before and after retention activity, reviewed failed pulls, and sampled manifest metadata in repositories with heavy churn. Developers were warned that once an untagged manifest was deleted, it could not be recovered from the registry.
📈Results & Business Impact
Experiment-related storage fell by 51% within two months.
No production repository required manual cleanup during the pilot.
Registry usage reporting became a 15-minute monthly task.
Developer image cleanup complaints dropped after the tagging rule was clarified.
💡Key Takeaway for Glossary Readers
ACR retention policy turns image cleanup into a governed lifecycle rule instead of occasional emergency deletion. The release team also kept the evidence reusable for the next review.
Why use Azure CLI for this?
Azure CLI is useful for ACR retention policy because it turns portal-visible configuration into repeatable evidence. Operators can list the target, inspect IDs and state, confirm whether the command is read-only or mutating, and save sanitized output for release or incident records. For this term, CLI work should start with context checks such as tenant, subscription, resource group, registry, database, role scope, or resource ID. Use JSON output when tags, digests, receiver lists, token permissions, assignment scopes, metrics, or replica links matter. Treat commands that delete manifests, disable tokens, update scope maps, create alerts, or fail over databases as approval-required changes, not casual inspection.
CLI use cases
Inventory the current ACR retention policy configuration before a release, access change, cleanup, alert update, or database operation so the operator can prove the target is correct.
Troubleshoot production behavior by comparing live Azure output for ACR retention policy with the expected architecture, owner, scope, tag, permission, metric, or replica state.
Automate a repeatable verification check around ACR retention policy in a pipeline or runbook so drift is caught before users, workloads, or auditors discover it.
Create sanitized post-change evidence for ACR retention policy, keeping IDs, state, timestamps, digests, run IDs, metrics, or links while redacting secrets and sensitive endpoints.
Before you run CLI
Confirm the active tenant and subscription with `az account show`; many ACR retention policy mistakes are wrong-context mistakes that look like product failures.
Identify the exact resource boundary before running commands: registry, repository, scope map, token, task, webhook, action group, role scope, database, or replica link.
Classify the command as read-only, security-impacting, cost-impacting, destructive, or availability-impacting; approval is required before mutating ACR retention policy in production.
Decide how sensitive output will be handled before the command runs, especially token passwords, webhook URIs, object IDs, connection details, and registry metadata.
What output tells you
The output confirms whether Azure returned the intended ACR retention policy target by name, resource ID, subscription, region, repository, database, role scope, or alert group.
State fields show what Azure will actually use: tags, digests, retention status, repository actions, token status, task triggers, receivers, session metrics, or replica links.
Nested JSON often contains the important evidence; table output can hide permissions, timestamps, action lists, credential status, endpoint scope, or metric dimensions.
The output also tells you whether the next action should be inspection, approval, rollback, scale, cleanup, failover, credential rotation, or a safer design review.
Mapped Azure CLI commands
ACR retention policy commands
direct
az acr config retention show --registry <registry-name>
az acr repository untag --name <registry-name> --image <repository>:<tag>
az acr repositoryremoveContainers
az acr manifest list-metadata --registry <registry-name> --name <repository>
az acr manifestdiscoverContainers
Architecture context
Treat retention as part of artifact lifecycle design. Decide which tags preserve rollback, which repositories are experimental, which manifests are protected, and how long audit or recovery evidence must exist. Enable retention only after pipelines use unique tags and teams understand that deletion is unrecoverable from the registry.
Security
Security depends on treating the registry as part of the software supply chain. Verify who can push, pull, delete, update metadata, trigger automation, or read event payloads. Prefer managed identity or Microsoft Entra integration for Azure workloads where it fits, use repository-scoped tokens only when needed, avoid registry admin credentials, and keep secrets out of command lines and logs. For ACR retention policy, save evidence that proves the repository, token, scope, trigger, task, or policy affects only the intended image boundary.
Cost
Cost is usually indirect but real. Registry storage grows through repeated tags, orphaned manifests, large layers, retained rollback images, and build artifacts. Tasks can add build/run consumption, webhooks and scanners can trigger downstream cost, and over-segmentation can create unnecessary registries. For ACR retention policy, cost control comes from clear image lifecycle rules, unique tagging, retention reviewed against rollback needs, and evidence that cleanup is removing waste rather than deleting still-needed production artifacts.
Reliability
Reliability depends on preserving the artifacts and automation that workloads actually consume. A missing tag, deleted manifest, disabled token, broken webhook endpoint, failed task, or wrong repository name can stop AKS, Container Apps, or CI/CD even when the compute platform is healthy. For ACR retention policy, operators should verify the current state before change, keep rollback images available, test automation paths, and record the digest, tag, trigger, run ID, or permission output that proves the release can still recover.
Performance
Performance usually appears through pull speed, build duration, automation latency, and deployment reliability rather than user-request latency. Large images, remote regions, excessive layers, broken caching, slow build tasks, or webhook delays can lengthen rollout windows. For ACR retention policy, performance review should check image size, tag and digest choice, regional registry strategy, task duration, endpoint response time, and whether deployment platforms can pull the required artifact without waiting on avoidable registry or network bottlenecks.
Operations
Operational excellence means the registry is inspectable from scripts, not only from portal memory. Use Azure CLI to list repositories, show tags, inspect manifest metadata, check retention, view token and scope-map settings, run tasks, read logs, ping webhooks, and export evidence. For ACR retention policy, a good runbook names the owner, intended repository path, safe command, destructive command, expected output, rollback contact, and what evidence can be saved without exposing credentials or private image details.
Common mistakes
Treating ACR retention policy as a label instead of a boundary with owner, scope, evidence, and rollback consequences.
Running mutating commands from the wrong subscription, resource group, registry, role scope, database, or region because the Azure CLI context was not checked first.
Saving raw secrets, token passwords, webhook URLs, or sensitive identity details in tickets instead of sanitized operational evidence.
Assuming a successful command proves the design is correct; it only proves Azure accepted the request or returned the current state.