Time-based retention is a Blob Storage immutability rule. You set a retention period, and protected blobs cannot be changed or deleted until that period expires. This is often described as WORM: write once, read many. It is different from soft delete or backup because it blocks modification during the protected interval rather than merely offering a recovery path afterward. Teams use it for records, logs, evidence, and regulated content where someone must prove that data stayed unchanged for a required time.
Time-based retention, time based retention, Azure Time-based retention, Microsoft Learn Time-based retention, immutability policy, WORM retention, immutable blob retention, retention days, container immutability policy
Difficulty
fundamentals
CLI mappings
5
Last verified
2026-05-27
Microsoft Learn
Time-based retention in Azure Blob Storage is an immutability policy that keeps blob data in a write-once, read-many state for a specified retention interval. It can be applied at container or version scope to protect records from modification or deletion until the retention period expires.
In Azure architecture, time-based retention sits in the storage data-protection and compliance layer. It is implemented through immutable storage policies at container scope or version scope, depending on account configuration and design. It interacts with blob versioning, legal hold, lifecycle management, delete operations, replication, private endpoints, RBAC, shared keys, and operational runbooks. The control plane manages policy configuration and locking, while the data plane enforces restrictions on protected blobs. Architects must decide which containers hold immutable records and which workloads need ordinary mutable storage.
Why it matters
Time-based retention matters because some data must be protected from both accidents and insiders. Audit logs, trading records, clinical documents, inspection reports, legal evidence, and financial statements can lose value if administrators can quietly overwrite or delete them. A retention policy creates a hard boundary that ordinary cleanup scripts and compromised credentials should not bypass during the retention interval. It also changes operations: storage accounts, containers, and blobs may become harder to delete or reorganize. Teams must plan retention carefully because a locked policy is intentionally restrictive, and a mistake can preserve the wrong data for a long time. That clarity prevents rushed changes from becoming hidden platform debt.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In a storage container policy blade, time-based retention appears with retention days, locked or unlocked state, protected append-write options, and policy history. during compliance evidence review.
Signal 02
In Azure CLI immutability-policy output, immutabilityPeriodSinceCreationInDays, state, allowProtectedAppendWrites, and etag show the enforceable retention configuration. before production policy locking. during operational review. during operational review.
Signal 03
In failed blob operations, delete or overwrite attempts return errors that indicate the blob is protected by an immutable time-based policy. during storage incident review.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Protect audit logs, evidence files, or financial records from deletion for a mandated retention period.
Create WORM storage for applications that write records once and must later prove those records were unchanged.
Lock a reviewed retention policy only after testing the container contents, retention duration, and cleanup impact.
Use version-level immutability when applications create new blob versions but prior versions must remain protected.
Combine retention with lifecycle tiering so long-lived records move to lower-cost tiers without becoming deletable early.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Aircraft maintenance records protected for inspections
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
An aviation maintenance organization stored inspection PDFs and sensor extracts in Blob Storage. Regulators required proof that completed records could not be altered before the retention period ended.
🎯Business/Technical Objectives
Protect finalized maintenance records from deletion or overwrite for seven years.
Allow daily uploads from hangar systems without giving technicians policy-control permissions.
Reduce manual evidence gathering before regulatory inspections.
Move older protected records to lower-cost tiers without breaking retention.
✅Solution Using Time-based retention
The storage architects created separate containers for finalized maintenance records and ordinary work-in-progress files. Time-based retention was configured on the finalized-record containers, tested in an unlocked state, and locked only after compliance approval. Upload services wrote new blobs instead of overwriting existing reports. Azure CLI showed immutability policy state, retention days, ETag, and protected append-write settings before and after locking. Lifecycle rules moved older immutable records to cooler tiers while retaining WORM protection. Access was limited through RBAC and private endpoints, and policy-change evidence was stored with the compliance team.
📈Results & Business Impact
Regulatory evidence preparation dropped from 11 days to 36 hours.
Unauthorized overwrite attempts fell to zero after work-in-progress files were separated.
Storage cost grew only 9% year over year despite seven-year retention because lifecycle tiering was planned.
Inspection teams accepted CLI-exported policy evidence without requesting portal screenshots.
💡Key Takeaway for Glossary Readers
Time-based retention is strongest when immutable records are isolated from everyday working storage before policies are locked.
Case study 02
Media archive preserves film-rights evidence
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A media distributor needed to preserve rights contracts, delivery receipts, and localization approvals. A prior cleanup script deleted files that later became important in a licensing dispute.
🎯Business/Technical Objectives
Keep rights evidence immutable for the contractually required retention period.
Prevent cleanup automation from deleting protected contract files.
Maintain searchable metadata for legal and distribution teams.
Avoid placing large media masters under the same policy by mistake.
✅Solution Using Time-based retention
The platform team split the archive into evidence containers and media-processing containers. Time-based retention was applied only to evidence containers that held contracts, receipts, and approvals. The policy started unlocked while legal reviewed sample contents and retention days. Once confirmed, operators used Azure CLI to capture policy output and lock the policy under a change request. Metadata about title, territory, language, contract ID, and expiration date was stored separately so legal searches did not require renaming protected blobs. Cleanup scripts were changed to skip immutable containers and to log any delete attempt blocked by policy.
📈Results & Business Impact
No protected evidence files were deleted during the next four cleanup cycles.
Legal retrieval time for a rights packet dropped from 2 days to 2 hours.
The archive avoided locking 480 TB of mutable media masters under the wrong retention policy.
Blocked delete attempts were reviewed weekly and fell by 93% after automation updates.
💡Key Takeaway for Glossary Readers
Time-based retention protects business evidence best when policy scope is narrow and metadata remains usable for discovery.
Case study 03
Public research lab preserves instrument output
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A government-funded laboratory produced instrument readings that supported published environmental studies. Reviewers needed assurance that raw outputs were not altered after collection.
🎯Business/Technical Objectives
Preserve raw instrument output for ten years after ingestion.
Allow researchers to run analytics without modifying protected source files.
Keep storage spend predictable across multi-year research grants.
Prove retention controls during peer-review and public-records requests.
✅Solution Using Time-based retention
The data platform created a raw-output landing container with time-based retention and separate curated containers for transformed datasets. Instruments uploaded immutable raw files with date-based paths, while analytics jobs read from the raw container and wrote cleaned outputs elsewhere. The policy was tested with representative files, then locked after the records officer approved the ten-year period. CLI policy output, storage account IDs, and ETags were stored in the project evidence repository. Lifecycle rules moved older raw data to cooler tiers, and dashboards tracked retained bytes by grant, instrument, and collection year. Researchers could reproduce transformations without needing write access to raw records.
📈Results & Business Impact
Raw data tamper-evidence questions were resolved in one review meeting instead of weeks of emails.
Analytics jobs stopped failing from accidental raw-file overwrites after write paths were separated.
Projected ten-year storage spend was reduced 37% with planned tiering.
Public-records response packages included policy evidence and source-file hashes for every requested study.
💡Key Takeaway for Glossary Readers
Time-based retention gives research teams confidence that raw evidence remains intact while curated analysis can still evolve.
Why use Azure CLI for this?
Azure CLI is useful for time-based retention because immutable policy changes need evidence, approval, and precision. Portal clicks are risky when a wrong container or period could lock data for years. CLI commands can show the existing policy, create an unlocked policy for review, extend a period, lock a policy after approval, and export JSON proof for auditors. As an Azure engineer, I want every retention change tied to a change record, resource group, storage account, container name, policy state, ETag, and retention period. CLI also helps scan many storage accounts for containers missing required immutability controls. It also makes this review easier to repeat in pipelines.
CLI use cases
Run az storage container immutability-policy show to inspect retention days, policy state, append-write settings, and ETag.
Create an unlocked time-based retention policy on a reviewed container before requesting legal or compliance approval to lock it.
Extend a retention period when policy and regulation allow longer preservation of protected records.
Lock an immutability policy only after approval, evidence capture, and confirmation that rollback limitations are understood.
List containers and export immutability settings to prove required storage locations have compliant retention controls.
Before you run CLI
Confirm the tenant, subscription, storage account, resource group, and container because the wrong retention policy can preserve data for years.
Verify whether the policy is unlocked or locked; locked policies intentionally restrict deletion and cannot be casually reversed.
Review legal retention, data classification, lifecycle tiering, replication, and application overwrite behavior before creating or locking a policy.
Use Azure AD login or approved credentials, protect shared keys, and keep policy output in an audit-safe location.
Capture current ETag and policy state before update commands because concurrency and approval evidence matter for immutability changes.
What output tells you
immutabilityPeriodSinceCreationInDays shows how long protected blobs remain immutable based on policy configuration and creation timing.
state tells you whether a policy is unlocked for limited changes or locked for stronger WORM enforcement.
allowProtectedAppendWrites settings reveal whether append blobs can receive permitted new blocks while existing protected content remains immutable.
etag and update timestamps help operators prove which policy version was reviewed, changed, or locked during a change window.
authorization or operation errors show whether a failure came from permissions, wrong scope, or immutability enforcement.
Mapped Azure CLI commands
Blob immutability time-based retention commands
direct
az storage container immutability-policy show --account-name <storage-account> --container-name <container> --auth-mode login --output json
az storage container immutability-policydiscoverStorage
az storage container immutability-policyremoveStorage
az storage container list --account-name <storage-account> --auth-mode login --query "[].name" --output table
az storage containerdiscoverStorage
Architecture context
Time-based retention should be designed as part of a records architecture, not added casually after storage already contains mixed data. I usually separate immutable containers by record type, retention class, and owner so policies match the data inside them. Version-level immutability can be useful when applications overwrite blobs, while container-level policies fit simpler append-and-read record stores. Architects must also plan lifecycle transitions, replication, key management, network isolation, and delete restrictions. If immutable records are used by analytics, build read paths that do not require rewriting protected blobs. The policy should be documented beside legal hold, backup, and incident-response procedures.
Security
Security impact is direct because time-based retention reduces the ability of privileged users, malware, or faulty automation to destroy protected evidence. It is not a substitute for identity security: attackers with storage access can still read data unless authorization, networking, and encryption controls are strong. Use Azure RBAC, disable unnecessary shared-key access where possible, protect account keys, require private endpoints for sensitive storage, and monitor policy changes. Locking a policy raises the stakes because even administrators cannot simply undo it. Separate duties so the people writing records are not the only people approving retention policy changes. Review evidence should name the identity, boundary, and approved data exposure.
Cost
Time-based retention can increase cost because protected data cannot be deleted early to reduce storage. Long retention intervals can accumulate large volumes of hot, cool, cold, or archive data, plus replication and backup-related operational effort. Lifecycle management can move eligible blobs to cheaper tiers, but immutability rules still control deletion and modification. Cost owners should estimate daily ingest, retention days, redundancy, access tier, rehydration needs, and analytics read patterns before locking a policy. The cost tradeoff may be justified for compliance, but it must be explicit. Tag retained containers and review whether each policy still matches a real legal or business requirement.
Reliability
Reliability improves for records that must survive deletion or overwrite, but operational flexibility decreases. A locked retention policy can prevent cleanup, container deletion, or storage-account deletion until protected data ages out. Disaster-recovery plans must account for immutable containers in replicated or restored environments. Applications should handle write failures when they try to overwrite protected blobs and should use append patterns only when allowed by policy. Reliable operations include testing retention in nonproduction, documenting how protected append writes work, and validating that lifecycle rules do not conflict with immutability. Treat policy lock as a production change with rollback limits. Documented fallback steps keep failures from becoming mystery outages.
Performance
Runtime performance impact is usually indirect. A retention policy does not make reads faster, but it changes write, overwrite, delete, and lifecycle behavior. Applications that expect to replace blobs in place can fail or slow down while retrying forbidden operations. Analytics jobs may need to read from immutable historical data at large scale, so tier choice, metadata design, and partitioned blob naming still matter. Operators should watch failed write and delete operations, rehydration time for archived retained data, and list performance in very large containers. Design workloads to write new versions or append allowed records instead of fighting the policy.
Operations
Operators manage time-based retention through storage-account inventory, container policy review, policy state tracking, audit logs, and access reviews. They inspect whether policies are unlocked or locked, how many days remain, whether protected append writes are allowed, and which teams own the retained data. Before locking a policy, operators confirm container contents, retention period, legal requirement, lifecycle design, and deletion impact. During incidents, they check whether failed deletes or overwrites are expected enforcement rather than storage errors. Runbooks should include CLI show commands, ETag handling, approval evidence, monitoring for policy changes, and procedures for containers that block account cleanup. Keep the runbook linked to owners, alerts, dashboards, and validation commands.
Common mistakes
Locking a retention policy on a mixed-use container where applications still need to overwrite or delete ordinary working files.
Treating immutable retention as backup while forgetting that accidental bad data can also be preserved until the period expires.
Choosing a long retention period without estimating storage growth, replication cost, lifecycle tiering, and eventual account cleanup impact.
Assuming administrators can quickly remove a locked policy during a migration or storage-account deletion project.
Forgetting to document whether protected append writes are allowed, causing log-ingestion failures after the policy is enabled.