Tutorial: Create an Azure Files volume mount in Azure Container Apps

Learn to write to permanent storage in a container app using an Azure Files storage mount. For more information about storage mounts, see Use storage mounts in Azure Container Apps.

In this tutorial, you learn how to:

Prerequisites

• Install the latest version of the Azure CLI.
• Use an Azure subscription with permissions to create resources and assign Azure role-based access control (Azure RBAC) roles. To assign roles, you need Microsoft.Authorization/roleAssignments/write permission at the storage account scope.

Set up the environment

The following commands define environment variables and ensure your Container Apps extension is up to date.

1. Sign in to the Azure CLI.

   • Bash
   • PowerShell

   az cloud set -n AzureChinaCloud
   az login
   # az cloud set -n AzureCloud   //means return to Public Azure.
   

2. Set up environment variables used in various commands to follow.

   • Bash
   • PowerShell

   RESOURCE_GROUP="my-container-apps-group"
   ENVIRONMENT_NAME="my-storage-environment"
   LOCATION="canadacentral"
   

3. Ensure you have the latest version of the Container Apps Azure CLI extension.

   • Bash
   • PowerShell

   az extension add -n containerapp --upgrade
   

4. Register the Microsoft.App namespace.

   • Bash
   • PowerShell

   az provider register --namespace Microsoft.App
   

5. Register the Microsoft.OperationalInsights provider for the Azure Monitor Log Analytics workspace if you haven't used it before.

   • Bash
   • PowerShell

   az provider register --namespace Microsoft.OperationalInsights
   

Create an environment

The following steps create a resource group and a Container Apps environment.

1. Create a resource group.

   • Bash
   • PowerShell

   az group create \
     --name $RESOURCE_GROUP \
     --location $LOCATION \
     --query "properties.provisioningState"
   

   Once created, the command returns a "Succeeded" message.

   At the end of this tutorial, you can delete the resource group to remove all the services created during this article.

2. Create a Container Apps environment.

   • Bash
   • PowerShell

   az containerapp env create \
     --name $ENVIRONMENT_NAME \
     --resource-group $RESOURCE_GROUP \
     --location "$LOCATION" \
     --mi-system-assigned \
     --query "properties.provisioningState"
   

   Once created, the command returns a "Succeeded" message.

   Use the --mi-system-assigned flag to enable the environment's system-assigned managed identity. In later steps, you grant this identity access to the file share.

   Storage mounts are associated with a Container Apps environment and configured within individual container apps.

Set up a storage account

Next, create a storage account and establish a file share to mount to the container app.

1. Define a storage account name.

   This command generates a random suffix to the storage account name to ensure uniqueness.

   • Bash
   • PowerShell

   STORAGE_ACCOUNT_NAME="myacastorageaccount$RANDOM"
   

2. Create an Azure Storage account.

   • Bash
   • PowerShell

   az storage account create \
     --resource-group $RESOURCE_GROUP \
     --name $STORAGE_ACCOUNT_NAME \
     --location "$LOCATION" \
     --kind StorageV2 \
     --sku Standard_LRS \
     --enable-large-file-share \
     --enable-smb-oauth true \
     --query provisioningState
   

   Once created, the command returns a "Succeeded" message.

   The --enable-smb-oauth true flag enables Managed Identity for SMB (SMBOAuth) on the storage account. If you use an existing storage account, enable this setting before creating the mount. For instructions, see Configure the managed identity's access property on your storage account.

   The storage account's SMB security settings must also allow Kerberos authentication. If you use a custom SMB security profile, see SMB security settings.

3. Define a file share name.

   • Bash
   • PowerShell

   STORAGE_SHARE_NAME="myfileshare"
   

4. Create the Azure Storage file share.

   • Bash
   • PowerShell

   az storage share-rm create \
     --resource-group $RESOURCE_GROUP \
     --storage-account $STORAGE_ACCOUNT_NAME \
     --name $STORAGE_SHARE_NAME \
     --quota 1024 \
     --enabled-protocols SMB \
     --output table
   

5. Define the storage mount name.

   • Bash
   • PowerShell

   STORAGE_MOUNT_NAME="mystoragemount"
   

   This value is the name used to define the storage mount link from your Container Apps environment to your Azure Storage account.

Grant the managed identity access

Assign the Storage File Data SMB MI Admin role to the environment's managed identity at the storage account scope. This role authorizes the identity to access files and directories in the SMB share.

ENVIRONMENT_PRINCIPAL_ID=$(az containerapp env show \
  --name $ENVIRONMENT_NAME \
  --resource-group $RESOURCE_GROUP \
  --query identity.principalId \
  --output tsv)

STORAGE_ACCOUNT_ID=$(az storage account show \
  --name $STORAGE_ACCOUNT_NAME \
  --resource-group $RESOURCE_GROUP \
  --query id \
  --output tsv)

az role assignment create \
  --assignee-object-id "$ENVIRONMENT_PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Storage File Data SMB MI Admin" \
  --scope "$STORAGE_ACCOUNT_ID"

$ENVIRONMENT_PRINCIPAL_ID=$(az containerapp env show `
  --name $ENVIRONMENT_NAME `
  --resource-group $RESOURCE_GROUP `
  --query identity.principalId `
  --output tsv)

$STORAGE_ACCOUNT_ID=$(az storage account show `
  --name $STORAGE_ACCOUNT_NAME `
  --resource-group $RESOURCE_GROUP `
  --query id `
  --output tsv)

az role assignment create `
  --assignee-object-id "$ENVIRONMENT_PRINCIPAL_ID" `
  --assignee-principal-type ServicePrincipal `
  --role "Storage File Data SMB MI Admin" `
  --scope "$STORAGE_ACCOUNT_ID"

Allow time for the role assignment to propagate before creating the storage mount. To assign the role in the Azure portal instead, see Assign a built-in RBAC role to the managed identity.

Create the storage mount

Now you can update the container app configuration to support the storage mount.

1. Create the storage link in the environment.

   • Bash
   • PowerShell

   az containerapp env storage set \
     --access-mode ReadWrite \
     --storage-type AzureFile \
     --azure-file-account-name $STORAGE_ACCOUNT_NAME \
     --azure-file-identity system \
     --azure-file-share-name $STORAGE_SHARE_NAME \
     --storage-name $STORAGE_MOUNT_NAME \
     --name $ENVIRONMENT_NAME \
     --resource-group $RESOURCE_GROUP \
     --output table
   

   This command creates a link between the Container Apps environment and the file share created with the az storage share-rm command. The --azure-file-identity system option authenticates to Azure Files by using the environment's system-assigned managed identity.

   For a user-assigned managed identity, assign the identity to the environment and use its full resource ID instead of system. Storage account key authentication remains supported as an alternative. Don't combine --azure-file-identity with --azure-file-account-key or --azure-file-key-vault-secret-url. For examples, see Use storage mounts in Azure Container Apps.

   Now that the storage account and environment are linked, you can create a container app that uses the storage mount.

2. Define the container app name.

   • Bash
   • PowerShell

   CONTAINER_APP_NAME="my-container-app"
   

3. Create the container app.

   • Bash
   • PowerShell

   az containerapp create \
     --name $CONTAINER_APP_NAME \
     --resource-group $RESOURCE_GROUP \
     --environment $ENVIRONMENT_NAME \
     --image nginx \
     --min-replicas 1 \
     --max-replicas 1 \
     --target-port 80 \
     --ingress external \
     --query properties.configuration.ingress.fqdn
   

   This command displays the URL of your new container app.

4. Copy the URL and paste into your web browser to navigate to the website.

   Once the page loads, you'll see the "Welcome to nginx!" message. Keep this browser tab open. You'll return to the website during the storage mount verification steps.

   Now that you've confirmed the container app is configured, you can update the app to with a storage mount definition.

5. Export the container app's configuration.

   • Bash
   • PowerShell

   az containerapp show \
     --name $CONTAINER_APP_NAME \
     --resource-group $RESOURCE_GROUP \
     --output yaml > app.yaml
   

   Note

   While this application doesn't have secrets, many apps do feature secrets. By default, when you export an app's configuration, the values for secrets aren't included in the generated YAML.

   If you don't need to change secret values, then you can remove the secrets section and your secrets remain unaltered. Alternatively, if you need to change a secret's value, make sure to provide both the name and value for all secrets in the file before attempting to update the app. Omitting a secret from the secrets section deletes the secret.

6. Open app.yaml in a code editor.

7. Replace the volumes: null definition in the template section with a volumes: definition referencing the storage volume. The template section should look like the following:

   template:
     containers:
     - image: nginx
       imageType: ContainerImage
       name: my-container-app
       resources:
         cpu: 0.5
         ephemeralStorage: 2Gi
         memory: 1Gi
       volumeMounts:
       - volumeName: my-azure-file-volume
         mountPath: /var/log/nginx
     initContainers: null
     revisionSuffix: ''
     scale:
       cooldownPeriod: 300
       maxReplicas: 1
       minReplicas: 1
       pollingInterval: 30
       rules: null
     serviceBinds: null
     terminationGracePeriodSeconds: null
     volumes:
     - name: my-azure-file-volume
       storageName: mystoragemount
       storageType: AzureFile
   

   The new template.volumes section includes the following properties.

   Property	Description
   name	This value identifies the app-level volume and is referenced by volumeName in the container's volume mount.
   storageName	This value matches the storage definition name created by calling the az containerapp env storage set command.
   storageType	This value determines the type of storage volume defined for the environment. In this case, an Azure Files mount is declared.

   The volumes section defines volumes at the app level that your application container or sidecar containers can reference via a volumeMounts section associated with a container.

   Managed identity authentication doesn't change the app-level volume configuration. Continue to use storageType: AzureFile for SMB mounts.

8. Add a volumeMounts section to the nginx container in the containers section.

   containers:
     - image: nginx
       name: my-container-app
       volumeMounts:
       - volumeName: my-azure-file-volume
         mountPath: /var/log/nginx
   

   The new volumeMounts section includes the following properties:

   Property	Description
   volumeName	This value must match the name defined in the volumes definition.
   mountPath	This value defines the path in your container where the storage is mounted.

9. Update the container app with the new storage mount configuration.

   • Bash
   • PowerShell

   az containerapp update \
     --name $CONTAINER_APP_NAME \
     --resource-group $RESOURCE_GROUP \
     --yaml app.yaml \
     --output table
   

Verify the storage mount

Now that the storage mount is established, you can manipulate files in Azure Storage from your container. Use the following commands to observe the storage mount at work.

1. Open an interactive shell inside the container app to execute commands inside the running container.

   • Bash
   • PowerShell

   az containerapp exec \
     --name $CONTAINER_APP_NAME \
     --resource-group $RESOURCE_GROUP
   

   This command may take a moment to open the remote shell. Once the shell is ready, you can interact with the storage mount via file system commands. For more information see Connect to a container console in Azure Container Apps.

2. Change into the nginx /var/log/nginx folder.

   cd /var/log/nginx
   

3. Return to the browser and navigate to the website and refresh the page a few times.

   The requests made to the website create a series of log stream entries.

4. Return to your terminal and list the values of the /var/log/nginx folder.

   ls
   

   Note how the access.log and error.log files appear in this folder. These files are written to the Azure Files mount in your Azure Storage share created in the previous steps.

5. View the contents of the access.log file.

   cat access.log
   

6. Exit out of the container's interactive shell to return to your local terminal session.

   exit
   

7. Now, you can view the files in the Azure portal to verify they exist in your Azure Storage account. Print the name of your randomly generated storage account.

   • Bash
   • PowerShell

   echo $STORAGE_ACCOUNT_NAME
   

8. Navigate to the Azure portal and open up the storage account created in this procedure.

9. Under Data Storage select File shares.

10. Select myfileshare to view the access.log and error.log files.

Clean up resources

If you're not going to continue to use this application, run the following command to delete the resource group along with all the resources created in this article.

az group delete \
  --name $RESOURCE_GROUP

az group delete `
  --name $RESOURCE_GROUP

Next steps