Storage in Azure Container Apps¶

Azure Container Apps supports three storage types for different lifecycle and sharing needs. Choosing the right type prevents data loss, reduces cost, and avoids common configuration errors such as writing persistent data to ephemeral volumes.

Main Content¶

Storage Types at a Glance¶

flowchart TD
    A[Container App Replica] --> B[Container-Scoped Storage]
    A --> C[EmptyDir Volume]
    A --> D[Azure Files Volume]

    B --> B1["Lost on container restart\nOnly visible to that container"]
    C --> C1["Shared across containers\nin the same replica\nLost when replica stops"]
    D --> D1["Persisted to Azure Files\nShared across replicas\nand revisions"]

Ephemeral Storage¶

Each replica receives a total ephemeral storage budget based on its vCPU allocation. This budget is shared across container-scoped and replica-scoped storage.

flowchart TD
    subgraph Replica ["Replica (0.25 vCPU → 1 GiB total ephemeral)"]
        C1[Container A\nContainer-scoped storage]
        C2[Container B\nContainer-scoped storage]
        E[EmptyDir Volume\nShared by A and B]
    end
    C1 -- shares budget --> E
    C2 -- shares budget --> E

You can inspect the ephemeral storage limit for a running container app:

az containerapp show \
  --name $APP_NAME \
  --resource-group $RG \
  --query "properties.template.containers[0].resources" \
  --output yaml

cpu: 0.25
ephemeralStorage: 1Gi
memory: 0.5Gi

Container-Scoped Storage¶

Every container has access to its own writable filesystem. This storage:

• Is temporary and disappears when the container shuts down or restarts.
• Is visible only to the current container — not to sidecars or other replicas.
• Requires no configuration — it is always available.

Use container-scoped storage for ephemeral operations: unpacking archives, writing intermediate computation output, or storing short-lived session data.

Replica-Scoped Storage (EmptyDir)¶

An EmptyDir volume is the equivalent of a Kubernetes EmptyDir mount — a temporary directory shared across all containers in the same replica. It persists for the lifetime of the replica, surviving individual container restarts.

When to use EmptyDir:

• Main app container writes log files, sidecar container ships them.
• Multiple init containers pass data to the main container.
• Scratch space for data processing that must survive container crashes but not replica replacement.

Configure EmptyDir via YAML¶

Export your app spec, add a volume and mount, then redeploy:

az containerapp show \
  --name $APP_NAME \
  --resource-group $RG \
  --output yaml > app.yaml

Edit app.yaml to add the volume and mount:

properties:
  template:
    containers:
    - name: my-app
      image: <IMAGE>
      resources:
        cpu: 0.25
        memory: 0.5Gi
      volumeMounts:
      - mountPath: /tmp/cache
        volumeName: cache-vol
    volumes:
    - name: cache-vol
      storageType: EmptyDir

Apply the update:

az containerapp update \
  --name $APP_NAME \
  --resource-group $RG \
  --yaml app.yaml \
  --output yaml

Verify the volume is applied:

az containerapp show \
  --name $APP_NAME \
  --resource-group $RG \
  --output yaml

volumeMounts:
- mountPath: /tmp/cache
  volumeName: cache-vol
volumes:
- name: cache-vol
  storageType: EmptyDir

Verify EmptyDir Write and Read at Runtime¶

Run a Container Apps Job to write a file and read it back from the EmptyDir mount:

az containerapp job start \
  --name $JOB_NAME \
  --resource-group $RG

The job command writes a file to /mnt/cache, reads it back, lists the directory, and reports disk usage:

WRITTEN
hello-emptydir
total 12
drwxr-xr-x 2 root root 4096 May  1 12:30 .
drwxr-xr-x 1 root root 4096 May  1 12:30 ..
-rw-r--r-- 1 root root   15 May  1 12:30 test.txt
Filesystem      Size  Used Avail Use% Mounted on
overlay          148G   28G  114G  20% /mnt/cache
DONE

Azure Files (Persistent Storage)¶

Azure Files provides persistent storage that survives container restarts, replica replacements, and revision rollbacks. Multiple containers across different replicas, revisions, or container apps can mount the same file share simultaneously.

Supported protocols:

Register Azure Files with the Environment¶

Before mounting, register the file share at the environment level:

az containerapp env storage set \
  --name $ENV_NAME \
  --resource-group $RG \
  --storage-name my-files \
  --storage-type AzureFile \
  --azure-file-account-name $STORAGE_ACCOUNT \
  --azure-file-account-key $STORAGE_KEY \
  --azure-file-share-name $SHARE_NAME \
  --access-mode ReadWrite

Verify the registration:

az containerapp env storage list \
  --name $ENV_NAME \
  --resource-group $RG \
  --output table

Name            ResourceGroup
--------------  ----------------
my-files        rg-myapp

Mount Azure Files in a Container¶

Add the volume and mount to your app YAML:

properties:
  template:
    containers:
    - name: my-app
      image: <IMAGE>
      volumeMounts:
      - mountPath: /mnt/data
        volumeName: files-vol
        subPath: uploads
    volumes:
    - name: files-vol
      storageType: AzureFile
      storageName: my-files

Storage Decision Guide¶

flowchart TD
    Q1{Does data need to survive\na container restart?} -->|No| Q2{Is it shared between\ncontainers in same replica?}
    Q1 -->|Yes| Q3{Is it shared across\nreplicas or revisions?}

    Q2 -->|No| A1[Container-scoped storage\nNo config needed]
    Q2 -->|Yes| A2[EmptyDir volume\nstorageType: EmptyDir]

    Q3 -->|No| A2
    Q3 -->|Yes| Q4{High-throughput\nor Linux-native?}
    Q4 -->|No| A3[Azure Files SMB\nstorageType: AzureFile]
    Q4 -->|Yes| A4[Azure Files NFS\nstorageType: NfsAzureFile\nRequires custom VNet]

Common Mistakes¶

See Also¶

• EmptyDir Disk Full — Lab Guide
• EmptyDir Disk Full — Playbook
• Azure Files Mount Failure — Playbook
• Volume Permission Denied — Playbook

Sources¶

• Use storage mounts in Azure Container Apps — Microsoft Learn
• Create an Azure Files storage mount — Microsoft Learn
• Troubleshoot storage mount failures — Microsoft Learn