Azure Container App Persistent Storage Guide Azure Container Apps handle containerized workloads well. Persistence is where teams get burned. A log file, an uploaded image, or a generated report written to the default container filesystem disappears when that container shuts down or restarts.

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 EmptyDir storage 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:

  1. Storage account and file share
  2. Environment-level storage registration
  3. Volume definition in the app template
  4. Volume mount in the container

Four-part Azure Files mounting configuration chain

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.

Azure Files tier and protocol selection comparison

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-name maps to volume storageName
  • Volume name maps to mount volumeName
  • mountPath is 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: ReadOnly or ReadWrite
  • 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:

  • volumeName doesn't match the volume's name
  • storageName doesn'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 stable 2025-01-01 and current 2026-07-01 versions
  • Terraform: azurerm_container_app_environment_storage for the registration and azurerm_container_app for the volume and volume_mounts blocks. The environment storage resource lists account key arguments but not identity or Key Vault ones.
  • AzAPI: azapi_resource with the same storages type, which exposes accountKeyVaultProperties

Azure Container Apps infrastructure as code options comparison

Check provider and API-version support before copying preview-era examples.

Validate persistence

  1. Open a shell: az containerapp exec -g "$RG" -n "$APP" --command sh
  2. Write a file: echo hello > /mnt/data/test.txt
  3. Restart or replace the revision, then reconnect.
  4. Read /mnt/data/test.txt again.
  5. Confirm the file appears in the share through the Azure portal or Storage CLI.

Five-step Azure Files persistence validation test workflow

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 the ResponseType dimension for throttling), SuccessE2ELatency, SuccessServerLatency
  • Throttling: ClientShareIopsThrottlingError and ClientAccountRequestThrottlingError
  • Mount failures: Error mounting volume <volume-name> in ContainerAppSystemLogs
  • 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.

Azure Files backup and recovery options with retention details

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:

  1. Confirm lifecycle expectations for each data type.
  2. Configure and secure the share.
  3. Test across containers, replicas, and restarts.
  4. Monitor mounts, latency, and throttling.
  5. 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.