
This guide explains the three storage scopes in Azure Container Apps, shows how to mount Azure Files with CLI and YAML, and covers infrastructure as code. It closes with production checks for security, performance, scaling, and recovery. Verify CLI syntax, API versions, and Preview features against current Microsoft documentation before you deploy.
Key Takeaways
- The container filesystem and
EmptyDirstorage are not durable storage. - Azure Files is the main option when files must outlive a replica.
- Pick storage based on durability, sharing, latency, protocol, cost, and recovery needs.
- Recheck docs for API versions, quotas, and authentication before production.
How Storage Works in Azure Container Apps
A Container Apps environment holds container apps. Each app runs containers in replicas, which are running instances.
Revisions are immutable snapshots of an app version. Changes under properties.template create a new revision. Volumes are defined in the revision template, and containers attach them through volume mounts.
Container filesystem
Files written inside a container are temporary. Per Microsoft's storage mounts documentation, they disappear when the container shuts down or restarts.
That works for recreatable data such as a thumbnail cache or a build artifact. It does not work for user uploads or anything you cannot regenerate.
Temporary storage
An EmptyDir volume is shared by all containers in one replica, including init containers. It survives a container restart within that replica, but its lifetime is the replica's lifetime. Other replicas don't see it.
Total ephemeral storage per replica depends on vCPU allocation:
| vCPUs | Total ephemeral storage |
|---|---|
| 0.25 or lower | 1 GiB |
| 0.5 or lower | 2 GiB |
| 1 or lower | 4 GiB |
| Over 1 | 8 GiB |
Scale-in, revision changes, and rescheduling all end a replica. Ephemeral storage limits can change, so verify the current figures in Microsoft's documentation.
Azure Files
An Azure file share lives outside your containers. Files written under the mount persist in the share and can be reached across containers, replicas, revisions, and even separate container apps.
The configuration chain has four links:
- Storage account and file share
- Environment-level storage registration
- Volume definition in the app template
- Volume mount in the container

Azure Container Storage is a different service
Azure Container Storage handles persistent-volume orchestration for Kubernetes, and works with AKS and self-managed clusters. It is not the mechanism for mounting Azure Files into a Container App. Check Microsoft's Azure Container Storage introduction for the exact capabilities.
Choosing the Right Storage Option
| Container filesystem | EmptyDir | Azure Files | |
|---|---|---|---|
| Lifetime | Container shutdown or restart | Replica lifetime | External share |
| Sharing | One container | Containers in one replica | Replicas, revisions, apps |
| Best for | Disposable cache | Scratch space shared in a replica | Durable shared files |
| Operational burden | None | None | Auth, network, backup |
Map your workload to the right row:
- Disposable cache or scratch files: container filesystem
- Files shared by sidecars in one replica:
EmptyDir - User-generated files or shared content: Azure Files
- Transactional state: a managed database. Microsoft's reliability guidance points to Cosmos DB and Azure SQL Database for state that needs cross-zone replication.
- Images, documents, media, archives accessed over HTTP: Blob Storage through its API. Container Apps does not support Blob mounts.
Tier and protocol
Container Apps documents both SMB and NFS, so "SMB-only" advice is outdated. Premium (SSD) shares suit I/O-intensive, low-latency workloads, while Standard (HDD) shares suit cost-sensitive general use. NFS is documented as SSD-only in the protocol documentation, so don't assume HDD NFS works.

Also weigh file sizes, sequential versus random I/O, concurrency, region, and transaction costs. Use current numbers from the Azure Files pricing page rather than benchmarks from old blog posts. Published scale targets describe storage accounts, not your app's measured results.
How to Configure Azure Files for an Azure Container App
Prerequisites and architecture
Have these ready:
- Azure subscription and resource group
- Container Apps environment
- Storage account and file share
- Azure CLI with the Container Apps extension
- Permissions to create and update these resources
- A test image with shell utilities
Names must line up across steps:
- Environment
--storage-namemaps to volumestorageName - Volume
namemaps to mountvolumeName mountPathis the path your app reads and writes
Create the storage account and file share
Use the portal or az storage commands. When you create the account and share, set:
- A region that matches your Container Apps environment
- A performance tier and quota sized for your workload
- Redundancy: LRS or ZRS for SSD; GRS or GZRS only for HDD
Security notes:
- Account keys grant broad access. Keep them out of YAML, shell history, source control, and images.
- Store required keys in Key Vault and plan rotation.
- Restrict public access and use private endpoints where possible. A private endpoint doesn't disable the public one, and it needs correct DNS.
- NFS requires a custom VNet. Network security groups must allow ports 445 (SMB) and 2049 (NFS).
Register the share with the environment
This step links the share to the environment. It does not mount anything yet.
az containerapp env storage set -g "$RG" -n "$ENV" \
--storage-name files --azure-file-account-name "$ACCOUNT" \
--azure-file-account-key "$KEY" --azure-file-share-name "$SHARE" \
--access-mode ReadWrite
Key options for this step:
- Access mode:
ReadOnlyorReadWrite - Managed identity and Key Vault flags (
--azure-file-identity,--azure-file-key-vault-secret-url) are Preview at the environment level - Identity mode and account-key mode are mutually exclusive
- For NFS, use
--storage-type NfsAzureFile(CLI reference labels this Preview)
Define the volume and volume mount
This is a schema fragment, not a full deployment:
properties:
template:
containers:
- name: app
image: <image>
volumeMounts:
- volumeName: shared
mountPath: /mnt/data
volumes:
- name: shared
storageType: AzureFile
storageName: files
mountOptions: "<optional,comma-separated,mount-options>"
Common mistakes:
volumeNamedoesn't match the volume'snamestorageNamedoesn't match the environment registration- Wrong YAML indentation
- The app writes to a path other than
mountPath
Use NfsAzureFile as the storage type for NFS and EmptyDir for temporary volumes. subPath is optional.
Deploy with CLI or infrastructure as code
Export the current config before editing it:
az containerapp show -g "$RG" -n "$APP" -o yaml > app.yaml
az containerapp update -g "$RG" -n "$APP" --yaml app.yaml
With --yaml, the CLI reference says other parameters are ignored. Use az containerapp create the same way for new apps.
For IaC:
- Bicep/ARM:
Microsoft.App/managedEnvironments/storages, with stable2025-01-01and current2026-07-01versions - Terraform:
azurerm_container_app_environment_storagefor the registration andazurerm_container_appfor thevolumeandvolume_mountsblocks. The environment storage resource lists account key arguments but not identity or Key Vault ones. - AzAPI:
azapi_resourcewith the same storages type, which exposesaccountKeyVaultProperties

Check provider and API-version support before copying preview-era examples.
Validate persistence
- Open a shell:
az containerapp exec -g "$RG" -n "$APP" --command sh - Write a file:
echo hello > /mnt/data/test.txt - Restart or replace the revision, then reconnect.
- Read
/mnt/data/test.txtagain. - Confirm the file appears in the share through the Azure portal or Storage CLI.

If the file isn't in the share, your test wrote to the container filesystem. Check the mount path and names. Microsoft's own tutorial mounts /var/log/nginx, so website requests produce access.log and error.log in the share.
Production Considerations: Security, Performance, and Troubleshooting
Secure access and data governance
Azure Files encrypts at rest with Microsoft-managed keys by default, and classic shares support customer-managed keys. For SMB in transit, use SMB 3.x with encryption, since SMB 2.1 lacks channel encryption. Microsoft's file share security guidance also notes that Container Apps does not support NFS encryption in transit, so requiring it can fail the mount.
Align access controls with audit requirements, pick redundancy that matches your durability needs, and confirm backups meet recovery objectives.
Performance and concurrency
Throughput and latency depend on:
- Metadata-heavy operations, which run slower than plain reads and writes
- Network distance between app and share
- File sizes and access patterns
- Concurrency and file locking
Azure Files troubleshooting guidance says a large gap between end-to-end and server latency points to client or network delay. Benchmark with your real workload and realistic file sizes.
Scaling and application behavior
Replicas can share an Azure Files mount, but EmptyDir stays replica-scoped. A shared mount doesn't guarantee conflict-free writes. SMB share modes and byte-range locks govern access, and incompatible opens cause sharing violations.
Design for stateless instances:
- Keep authoritative state in a managed data service
- Make file operations idempotent
- Never depend on local paths for durable state
- Guard against duplicate processing across replicas
Monitoring, backup, and recovery
Track these signals:
- Storage metrics:
FileCapacity,Transactions(with theResponseTypedimension for throttling),SuccessE2ELatency,SuccessServerLatency - Throttling:
ClientShareIopsThrottlingErrorandClientAccountRequestThrottlingError - Mount failures:
Error mounting volume <volume-name>inContainerAppSystemLogs - Portal diagnostics: Diagnose and solve problems, then Storage Mount Failures (24-hour events)
Persistence is not backup. Container Apps has no built-in application data backup.
Use share snapshots (up to 200 per share) or Azure Backup, test restores, set retention, and document your RPO and RTO. Soft delete is share-level, and retained capacity is still billed.

Storage optimization across the broader Azure estate
Many teams run Container Apps next to Azure managed disks. Azure Files isn't a block storage service, and managed disks aren't a Container Apps volume option. For managed disks and other block storage, Lucidity provides real-time visibility into every volume plus autonomous expansion and shrinking. It doesn't replace Azure Files or a volume mount, and it doesn't manage file storage.
Conclusion
Use the simplest storage that meets your durability, sharing, performance, security, and recovery needs. Choose Azure Files only after confirming that its protocol and concurrency behavior fit your app.
Implementation checklist:
- Confirm lifecycle expectations for each data type.
- Configure and secure the share.
- Test across containers, replicas, and restarts.
- Monitor mounts, latency, and throttling.
- Recheck Microsoft documentation for storage support changes.
Frequently Asked Questions
Does Azure Container Apps support persistent storage?
Yes. Mount Azure Files shares for persistence. The container filesystem and EmptyDir are temporary.
What is the best storage option for Azure Container Apps?
It depends on durability, sharing, I/O, cost, and recovery needs. Azure Files suits shared files, while databases suit transactional state and Blob suits object data accessed by API.
Does Azure Container Apps have a persistent file system?
Not by default. The container filesystem is temporary, so persistent files need an external mount such as Azure Files.
How do I mount Azure Files in Azure Container Apps?
Create the storage account and share, register it on the environment, add the volume and volumeMounts to your app YAML, then deploy and test a file write.
What happens to temporary storage when an Azure Container App restarts?
Container filesystem data is lost. EmptyDir data survives a container restart but not replica replacement. Data on a correctly mounted Azure Files share persists.
Can multiple Azure Container Apps share the same Azure Files share?
Yes. Multiple container apps can mount the same share. Set access mode and permissions carefully, and plan for concurrent-write conflicts and locking limits.