Use storage mounts in Azure Container Apps

Select how you want to interact with Azure

Azure CLI Azure portal ARM template

A container app has access to different types of storage. A single app can take advantage of more than one type of storage if necessary.

Note

Avoid using special characters in volume names to prevent deployment failures. For example, a volume named credentials.json contains a special character (.) which results in a deployment error.

Storage type	Description	Persistence	Usage example
Container-scoped storage	Ephemeral storage available to a running container	Data is available until container shuts down	Writing a local app cache.
Replica-scoped storage	Ephemeral storage for sharing files between containers in the same replica	Data is available until replica shuts down	The main app container writing log files that a sidecar container processes.
Azure Files	Permanent storage	Data is persisted to Azure Files	Writing files to a file share to make data accessible by other systems.

Note

Azure Container Apps does not support mounting file shares from Azure NetApp Files or Azure Blob Storage.

Ephemeral storage

A container app can read and write temporary data to ephemeral storage. Ephemeral storage can be scoped to a container or a replica. The total amount of container-scoped and replica-scoped storage available to each replica depends on the total number of vCPUs allocated to the replica.

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

Container-scoped storage

A container can write to its own file system.

Container file system storage has the following characteristics:

• The storage is temporary and disappears when the container is shut down or restarted.
• Files written to this storage are only visible to processes running in the current container.

Replica-scoped storage

You can mount an ephemeral, temporary volume that is equivalent to EmptyDir (empty directory) in Kubernetes. This storage is scoped to a single replica. Use an EmptyDir volume to share data between containers in the same replica.

Replica-scoped storage has the following characteristics:

• Files are persisted for the lifetime of the replica.
  • If a container in a replica restarts, the files in the volume remain.
• Any init or app containers in the replica can mount the same volume.
• A container can mount multiple EmptyDir volumes.

To configure replica-scoped storage, first define an EmptyDir volume in the revision. Then define a volume mount in one or more containers in the revision.

Prerequisites

Requirement	Instructions
Azure account	If you don't have one, create an account for free.
Azure Container Apps environment	Create a container apps environment.

Configuration

When configuring replica-scoped storage using the Azure CLI, you must use a YAML definition to create or update your container app.

1. To update an existing container app to use replica-scoped storage, export your app's specification to a YAML file named app.yaml.

   az containerapp show -n <APP_NAME> -g <RESOURCE_GROUP_NAME> -o yaml > app.yaml
   

2. Make the following changes to your container app specification.

   • Add a volumes array to the template section of your container app definition and define a volume. If you already have a volumes array, add a new volume to the array.
     • The name is an identifier for the volume.
     • Use EmptyDir as the storageType.
   • For each container in the template that you want to mount the volume, define a volume mount in the volumeMounts array of the container definition.
     • The volumeName is the name defined in the volumes array.
     • The mountPath is the path in the container to mount the volume.

   properties:
     managedEnvironmentId: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.App/managedEnvironments/<ENVIRONMENT_NAME>
     configuration:
       activeRevisionsMode: Single
     template:
       containers:
       - image: <IMAGE_NAME1>
         name: my-container-1
         volumeMounts:
         - mountPath: /myempty
           volumeName: myempty
       - image: <IMAGE_NAME_2>
         name: my-container-2
         volumeMounts:
         - mountPath: /myempty
           volumeName: myempty
       volumes:
       - name: myempty
         storageType: EmptyDir
   

3. Update your container app using the YAML file.

   az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP_NAME> \
       --yaml app.yaml
   

See the YAML specification for a full example.

To create a replica-scoped volume and mount it in a container, make the following changes to the container apps resource in an ARM template:

• Add a volumes array to the template section of your container app definition and define a volume. If you already have a volumes array, add a new volume to the array.
  • The name is an identifier for the volume.
  • Use EmptyDir as the storageType.
• For each container in the template that you want to mount the volume, define a volume mount in the volumeMounts array of the container definition.
  • The volumeName is the name defined in the volumes array.
  • The mountPath is the path in the container to mount the volume.

Example ARM template snippet:

{
  "apiVersion": "2022-03-01",
  "type": "Microsoft.App/containerApps",
  "name": "[parameters('containerappName')]",
  "location": "[parameters('location')]",
  "properties": {

    ...

    "template": {
      "revisionSuffix": "myrevision",
      "containers": [
        {
          "name": "main",
          "image": "[parameters('container_image')]",
          "resources": {
            "cpu": 0.5,
            "memory": "1Gi"
          },
          "volumeMounts": [
            {
              "mountPath": "/myempty",
              "volumeName": "myempty"
            }
          ]
        },
        {
          "name": "sidecar",
          "image": "[parameters('sidecar_image')]",
          "resources": {
            "cpu": 0.5,
            "memory": "1Gi"
          },
          "volumeMounts": [
            {
              "mountPath": "/myempty",
              "volumeName": "myempty"
            }
          ]
        }
      ],
      "scale": {
        "minReplicas": 1,
        "maxReplicas": 3
      },
      "volumes": [
        {
          "name": "myempty",
          "storageType": "EmptyDir"
        }
      ]
    }
  }
}

See the ARM template API specification for a full example.

To create a replica-scoped volume and mount it in a container, deploy a new revision of your container app using the Azure portal.

1. In the Azure portal, navigate to your container app.

2. Select Revision management in the left menu.

3. Select Create new revision.

4. Select the container where you want to mount the volume.

5. In the Edit a container context pane, select the Volume mounts tab.

6. Under the Ephemeral storage section, create a new volume with the following information.

   • Volume name: A name for the ephemeral volume.
   • Mount path: The absolute path in the container to mount the volume.

7. Select Save to save changes and exit the context pane.

8. Select Create to create the new revision.

Azure Files volume

You can mount a file share from Azure Files as a volume in a container.

Azure Files storage has the following characteristics:

• Files written under the mount location are persisted to the file share.
• Files in the share are available via the mount location.
• Multiple containers can mount the same file share, including ones that are in another replica, revision, or container app.
• All containers that mount the share can access files written by any other container or method.
• More than one Azure Files volume can be mounted in a single container.

Azure Files supports both SMB (Server Message Block) and NFS (Network File System) protocols. You can mount an Azure Files share using either protocol. The file share you define in the environment must be configured with the same protocol used by the file share in the storage account.

Note

Support for mounting NFS shares in Azure Container Apps is in preview.

To enable Azure Files storage in your container, you need to set up your environment and container app as follows:

• Create a storage definition in the Container Apps environment.
• If you're using NFS, your environment must be configured with a custom VNet and the storage account must be configured to allow access from the VNet. For more information, see NFS file shares in Azure Files .
• If your environment is configured with a custom VNet, you must allow ports 445 and 2049 in the network security group (NSG) associated with the subnet.
• Define a volume of type AzureFile (SMB) or NfsAzureFile (NFS) in a revision.
• Define a volume mount in one or more containers in the revision.
• The Azure Files storage account used must be accessible from your container app's virtual network. For more information, see Grant access from a virtual network.
  • If you're using NFS, you must also disable secure transfer. For more information, see NFS file shares in Azure Files and the Create an NFS Azure file share section in this tutorial.

Prerequisites

Requirement	Instructions
Azure account	If you don't have one, create an account for free.
Azure Storage account	Create a storage account.
Azure Container Apps environment	Create a container apps environment.

Configuration

When configuring a container app to mount an Azure Files volume using the Azure CLI, you must use a YAML definition to create or update your container app.

For a step-by-step tutorial on mounting an SMB file share, refer to Create an Azure Files storage mount in Azure Container Apps.

1. Add a storage definition to your Container Apps environment.

   az containerapp env storage set --name my-env --resource-group my-group \
       --storage-name mystorage \
       --storage-type AzureFile \
       --azure-file-account-name <STORAGE_ACCOUNT_NAME> \
       --azure-file-account-key <STORAGE_ACCOUNT_KEY> \
       --azure-file-share-name <STORAGE_SHARE_NAME> \
       --access-mode ReadWrite
   

   Replace <STORAGE_ACCOUNT_NAME> and <STORAGE_ACCOUNT_KEY> with the name and key of your storage account. Replace <STORAGE_SHARE_NAME> with the name of the file share in the storage account.

   Valid values for --access-mode are ReadWrite and ReadOnly.

   az containerapp env storage set --name my-env --resource-group my-group \
       --storage-name mystorage \
       --storage-type NfsAzureFile \
       --server <NFS_SERVER> \
       --azure-file-share-name <STORAGE_SHARE_NAME> \
       --azure-file-account-name <STORAGE_ACCOUNT_NAME> \
       --azure-file-account-key <STORAGE_ACCOUNT_KEY> \
       --access-mode ReadWrite
   

   Replace <NFS_SERVER> with the NFS server address in the format <STORAGE_ACCOUNT_NAME>.file.core.windows.net. For example, if your storage account name is mystorageaccount, the NFS server address is mystorageaccount.file.core.windows.net.

   Replace <STORAGE_SHARE_NAME> with the name of the file share in the format /<STORAGE_ACCOUNT_NAME>/<STORAGE_SHARE_NAME>. For example, if your storage account name is mystorageaccount and the file share name is myshare, the share name is /mystorageaccount/myshare.

   Replace <STORAGE_ACCOUNT_NAME> with the name of your Azure Storage account and <STORAGE_ACCOUNT_KEY> with the key for your Azure Storage account, which can be found in the Azure portal.

   Valid values for --access-mode are ReadWrite and ReadOnly.

   Note

   To mount NFS Azure Files, you must use a Container Apps environment with a custom VNet. The Storage account must be configured to allow access from the VNet.

2. To update an existing container app to mount a file share, export your app's specification to a YAML file named app.yaml.

   az containerapp show -n <APP_NAME> -g <RESOURCE_GROUP_NAME> -o yaml > app.yaml
   

3. Make the following changes to your container app specification.

   • Add a volumes array to the template section of your container app definition and define a volume. If you already have a volumes array, add a new volume to the array.
     • The name is an identifier for the volume.
     • For storageType, use AzureFile for SMB, or NfsAzureFile for NFS. This value must match the storage type you defined in the environment.
     • For storageName, use the name of the storage you defined in the environment.
     • The mountOptions is a comma-separated string of mount options. For more information see Use mountOptions settings in Azure Files.
     • The secrets list is a list of secrets to mount in the volume. For more information see Mounting secrets in a volume.
   • For each container in the template that you want to mount Azure Files storage, define a volume mount in the volumeMounts array of the container definition.
     • The volumeName is the name defined in the volumes array.
     • The mountPath is the path in the container to mount the volume.
     • The subPath (optional) is the path in the volume to mount. If not specified, the volume root is mounted. For more information see using subPath.

   properties:
     managedEnvironmentId: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.App/managedEnvironments/<ENVIRONMENT_NAME>
     configuration:
     template:
       containers:
       - image: <IMAGE_NAME>
         name: my-container
         volumeMounts:
         - volumeName: azure-files-volume
           mountPath: /my-files
           subPath: my-sub-path
       volumes:
       - name: azure-files-volume
         storageType: AzureFile
         storageName: mystorage
   

   properties:
     managedEnvironmentId: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.App/managedEnvironments/<ENVIRONMENT_NAME>
     configuration:
     template:
       containers:
       - image: <IMAGE_NAME>
         name: my-container
         volumeMounts:
         - volumeName: azure-files-volume
           mountPath: /my-files
           subPath: my-sub-path
       volumes:
       - name: azure-files-volume
         storageType: NfsAzureFile
         storageName: mystorage
   

4. Update your container app using the YAML file.

   az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP_NAME> \
       --yaml app.yaml
   

See the YAML specification for a full example.

The following ARM template snippets demonstrate how to add an Azure Files share to a Container Apps environment and use it in a container app.

1. Add a storages child resource to the Container Apps environment.

   {
     "type": "Microsoft.App/managedEnvironments",
     "apiVersion": "2022-03-01",
     "name": "[parameters('environment_name')]",
     "location": "[parameters('location')]",
     "properties": {
       "daprAIInstrumentationKey": "[parameters('dapr_ai_instrumentation_key')]",
       "appLogsConfiguration": {
         "destination": "log-analytics",
         "logAnalyticsConfiguration": {
           "customerId": "[parameters('log_analytics_customer_id')]",
           "sharedKey": "[parameters('log_analytics_shared_key')]"
         }
       }
     },
     "resources": [
       {
         "type": "storages",
         "name": "myazurefiles",
         "apiVersion": "2022-03-01",
         "dependsOn": [
           "[resourceId('Microsoft.App/managedEnvironments', parameters('environment_name'))]"
         ],
         "properties": {
           "azureFile": {
             "accountName": "[parameters('storage_account_name')]",
             "accountKey": "[parameters('storage_account_key')]",
             "shareName": "[parameters('storage_share_name')]",
             "accessMode": "ReadWrite"
           }
         }
       }
     ]
   }
   

   {
     "type": "Microsoft.App/managedEnvironments",
     "apiVersion": "2023-05-01",
     "name": "[parameters('environment_name')]",
     "location": "[parameters('location')]",
     "properties": {
       "daprAIInstrumentationKey": "[parameters('dapr_ai_instrumentation_key')]",
       "appLogsConfiguration": {
         "destination": "log-analytics",
         "logAnalyticsConfiguration": {
           "customerId": "[parameters('log_analytics_customer_id')]",
           "sharedKey": "[parameters('log_analytics_shared_key')]"
         }
       },
       "workloadProfiles": [
         {
           "name": "Consumption",
           "workloadProfileType": "Consumption"
         }
       ],
       "vnetConfiguration": {
         "infrastructureSubnetId": "[parameters('custom_vnet_subnet_id')]",
         "internal": false
       },
     },
     "resources": [
       {
         "type": "storages",
         "name": "myazurefiles",
         "apiVersion": "2023-11-02-preview",
         "dependsOn": [
           "[resourceId('Microsoft.App/managedEnvironments', parameters('environment_name'))]"
         ],
         "properties": {
           "nfsAzureFile": {
             "server": "[concat(parameters('storage_account_name'), '.file.core.windows.net')]",
             "shareName": "[concat('/', parameters('storage_account_name'), '/', parameters('storage_share_name'))]",
             "accessMode": "ReadWrite"
           }
         }
       }
     ]
   }
   

   Note

   To mount NFS Azure Files, you must use a Container Apps environment with a custom VNet. The Storage account must be configured to allow access from the VNet.

2. Update the container app resource to add a volume and volume mount.

   {
     "apiVersion": "2023-05-01",
     "type": "Microsoft.App/containerApps",
     "name": "[parameters('containerappName')]",
     "location": "[parameters('location')]",
     "properties": {
   
       ...
   
       "template": {
         "revisionSuffix": "myrevision",
         "containers": [
           {
             "name": "main",
             "image": "[parameters('container_image')]",
             "resources": {
               "cpu": 0.5,
               "memory": "1Gi"
             },
             "volumeMounts": [
               {
                 "mountPath": "/myfiles",
                 "volumeName": "azure-files-volume",
                 "subPath": "my-sub-path"
               }
             ]
           }
         ],
         "scale": {
           "minReplicas": 1,
           "maxReplicas": 3
         },
         "volumes": [
           {
             "name": "azure-files-volume",
             "storageType": "AzureFile",
             "storageName": "myazurefiles"
           }
         ]
       }
     }
   }
   

   {
     "apiVersion": "2023-11-02-preview",
     "type": "Microsoft.App/containerApps",
     "name": "[parameters('containerappName')]",
     "location": "[parameters('location')]",
     "properties": {
   
       ...
   
       "template": {
         "revisionSuffix": "myrevision",
         "containers": [
           {
             "name": "main",
             "image": "[parameters('container_image')]",
             "resources": {
               "cpu": 0.5,
               "memory": "1Gi"
             },
             "volumeMounts": [
               {
                 "mountPath": "/myfiles",
                 "volumeName": "azure-files-volume",
                 "subPath": "my-sub-path"
               }
             ]
           }
         ],
         "scale": {
           "minReplicas": 1,
           "maxReplicas": 3
         },
         "volumes": [
           {
             "name": "azure-files-volume",
             "storageType": "NfsAzureFile",
             "storageName": "myazurefiles"
           }
         ]
       }
     }
   }
   

   • Add a volumes array to the template section of your container app definition and define a volume. If you already have a volumes array, add a new volume to the array.
     • The name is an identifier for the volume.
     • For storageType, use AzureFile for SMB, or NfsAzureFile for NFS. This value must match the storage type you defined in the environment.
     • For storageName, use the name of the storage you defined in the environment.
     • The mountOptions is a comma-separated string of mount options. For more information see Use mountOptions settings in Azure Files.
     • The secrets list is a list of secrets to mount in the volume. For more information see Mounting secrets in a volume.
   • For each container in the template that you want to mount Azure Files storage, define a volume mount in the volumeMounts array of the container definition.
     • The volumeName is the name defined in the volumes array.
     • The mountPath is the path in the container to mount the volume.
     • The subPath (optional) is the path in the volume to mount. If not specified, the volume root is mounted. For more information see using subPath.

See the ARM template API specification for a full example.

To configure a volume mount for Azure Files storage in the Azure portal, add a file share to your Container Apps environment and then add a volume mount to your container app by creating a new revision.

1. In the Azure portal, navigate to your Container Apps environment.

2. In the navigation pane, under Settings, select Azure Files.

3. Select Add.

4. Select Server Message Block (SMB) or Network File System (NFS), depending on the protocol used by your file share.

5. In the Add file share context pane, enter the following information:

   SMB

   • Name: A name for the file share.
   • Storage account name: The name of the storage account that contains the file share.
   • Storage account key: The access key for the storage account.
   • File share: The name of the file share.
   • Access mode: The access mode for the file share. Valid values are Read/Write and Read only.

   NFS

   • Name: A name for the file share.
   • Server: The name of the server that contains the file share. This has the form <STORAGE_ACCOUNT_NAME>.file.core.windows.net.
   • File share name: The name of the file share. This has the form /<STORAGE_ACCOUNT_NAME>/<FILE_SHARE_NAME>.
   • Access mode: The access mode for the file share. Valid values are Read/Write and Read only.

6. Select Add to exit the context pane.

7. Select Save to commit the changes.

8. Navigate to your container app.

9. In the navigation pane, under Application, select Revisions and replicas.

10. Select Create new revision.

11. In the Create and deploy new revision page, select the Volumes tab.

12. Select Add.

13. In the Add volume context pane, set the following.

    • Volume type: Azure file volume.
    • Name: Enter a volume name.
    • File share name: Select the file share you created previously.
    • Mount options: Optionally, enter a comma-separated string of mount options. For more information see Use mountOptions settings in Azure Files.

14. Select Add to exit the context pane.

15. In the Create and reploy new revision page, select the Container tab.

16. Select the container that you want to mount the volume in.

17. In the Edit a container context pane, select the Volume mounts tab.

18. Under Volume name, select the volume you created previously.

19. In Mount path, enter the absolute path in the container to mount the volume.

20. In Sub path (optional), enter the path in the volume to mount. If not specified, the volume root is mounted. For more information see using subPath.

21. Select Save to save changes and exit the context pane.

22. Select Create to create the new revision.