File Storage

Introduction

Azure Files offers fully managed file shares in a storage account, accessible over the SMB and NFS protocols and through the Azure Files REST API. File shares are commonly mounted by containers and Kubernetes pods, used as shared configuration or content stores, and used to lift and shift applications that expect a file system. For more information, see What is Azure Files?.

LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Files. You manage file shares through the Azure Resource Manager API, and read and write their files through the Azure Files REST API. The supported APIs are available on our API Coverage section, which provides information on the extent of Azure Files’ integration with LocalStack.

Getting started

This guide is designed for users new to Azure Files and assumes basic knowledge of the Azure CLI and our lstk az proxy.

Launch LocalStack using your preferred method. For more information, see Introduction to LocalStack for Azure. Once the container is running, enable Azure CLI interception by running:

lstk az start-interception

This command points the az CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API. To revert this configuration, run:

lstk az stop-interception

This reconfigures the az CLI to send commands to the official Azure management REST API.

Create a resource group and a storage account

Create a resource group and a general-purpose v2 storage account:

az group create \
  --name rg-files-demo \
  --location westeurope

az storage account create \
  --name stfilesdemo \
  --resource-group rg-files-demo \
  --location westeurope \
  --sku Standard_LRS \
  --kind StorageV2

Create a file share

Create a file share with a quota of 10 GiB:

az storage share-rm create \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --name share-demo \
  --quota 10 \
  --enabled-protocols SMB

Output

{
  "enabledProtocols": "SMB",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-files-demo/providers/Microsoft.Storage/storageAccounts/stfilesdemo/fileServices/default/shares/share-demo",
  "leaseState": "available",
  "leaseStatus": "unlocked",
  "name": "share-demo",
  "resourceGroup": "rg-files-demo",
  "shareQuota": 10,
  "signedIdentifiers": [],
  "type": "Microsoft.Storage/storageAccounts/fileServices/shares",
  ...
}

Update and list file shares

Raise the quota to 20 GiB:

az storage share-rm update \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --name share-demo \
  --quota 20

Output

{
  "accessTier": "TransactionOptimized",
  "enabledProtocols": "SMB",
  "name": "share-demo",
  "shareQuota": 20,
  "type": "Microsoft.Storage/storageAccounts/fileServices/shares",
  ...
}

Then list the file shares of the storage account:

az storage share-rm list \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --output table

Output

AccessTier            AccessTierChangeTime         EnabledProtocols    LastModifiedTime             LeaseState    LeaseStatus    Name        ResourceGroup    ShareQuota
--------------------  ---------------------------  ------------------  ---------------------------  ------------  -------------  ----------  ---------------  ------------
TransactionOptimized  2026-10-20T10:32:01.689190Z  SMB                 2026-10-20T10:32:05.182839Z  available     unlocked       share-demo  rg-files-demo    20

Upload and download files

Retrieve the storage account’s connection string:

CONNECTION_STRING=$(az storage account show-connection-string \
  --name stfilesdemo \
  --resource-group rg-files-demo \
  --query connectionString \
  --output tsv)

The connection string points the file endpoint at LocalStack, for example FileEndpoint=https://stfilesdemo.file.core.azure.localhost.localstack.cloud:4566.

Create a directory in the share, and upload a file to it:

echo "Hello from LocalStack for Azure Files" > hello.txt

az storage directory create \
  --share-name share-demo \
  --name docs \
  --connection-string "$CONNECTION_STRING"

az storage file upload \
  --share-name share-demo \
  --source hello.txt \
  --path docs/hello.txt \
  --connection-string "$CONNECTION_STRING"

List the files in the directory:

az storage file list \
  --share-name share-demo \
  --path docs \
  --connection-string "$CONNECTION_STRING" \
  --output table

Output

Name       Content Length    Type    Last Modified
---------  ----------------  ------  -------------------------
hello.txt  38                file    2026-10-20T10:32:10+00:00

Download the file again:

az storage file download \
  --share-name share-demo \
  --path docs/hello.txt \
  --dest ./hello-copy.txt \
  --connection-string "$CONNECTION_STRING"

cat hello-copy.txt

Output

Hello from LocalStack for Azure Files

The share’s usage reflects the uploaded file:

az storage share-rm show \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --name share-demo \
  --expand stats \
  --query shareUsageBytes

Output

38

Create a share snapshot

Create a read-only snapshot of the share:

az storage share-rm snapshot \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --name share-demo

Output

{
  "name": "share-demo",
  "shareQuota": 20,
  "shareUsageBytes": 38,
  "snapshotTime": "2026-10-20T10:32:14.343070Z",
  "type": "Microsoft.Storage/storageAccounts/fileServices/shares",
  ...
}

Soft delete and restore a share

Enable soft delete for file shares, with a retention period of 7 days:

az storage account file-service-properties update \
  --account-name stfilesdemo \
  --resource-group rg-files-demo \
  --enable-delete-retention true \
  --delete-retention-days 7

Output

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-files-demo/providers/Microsoft.Storage/storageAccounts/stfilesdemo/fileServices/default",
  "name": "default",
  "shareDeleteRetentionPolicy": {
    "allowPermanentDelete": null,
    "days": 7,
    "enabled": true
  },
  "type": "Microsoft.Storage/storageAccounts/fileServices",
  ...
}

Delete the share together with its snapshots, then list the shares including the deleted ones:

az storage share-rm delete \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --name share-demo \
  --include snapshots \
  --yes

az storage share-rm list \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --include-deleted \
  --query "[].{name:name,deleted:deleted,version:version,remainingRetentionDays:remainingRetentionDays}"

Output

[
  {
    "deleted": true,
    "name": "share-demo",
    "remainingRetentionDays": 7,
    "version": "01DD607E47B092C0"
  }
]

Restore the deleted share by its version:

DELETED_VERSION=$(az storage share-rm list \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --include-deleted \
  --query "[?deleted].version" \
  --output tsv)

az storage share-rm restore \
  --storage-account stfilesdemo \
  --resource-group rg-files-demo \
  --name share-demo \
  --deleted-version "$DELETED_VERSION"

Note

LocalStack restores the share itself, but not the files it held when it was deleted: the restored share is empty.

Check storage account usage

Show how many storage accounts the subscription uses in a region, against the limit:

az storage account show-usage \
  --location westeurope

Output

{
  "currentValue": 1,
  "limit": 250,
  "name": {
    "localizedValue": "Storage Accounts",
    "value": "StorageAccounts"
  },
  "unit": "Count"
}

Clean up

Delete the resource group and everything in it:

az group delete \
  --name rg-files-demo \
  --yes

Features

The Azure Files emulator supports the following features:

• File shares: Create, get, update, list, and delete file shares, with quota, access tier, enabled protocols (SMB, or NFS on FileStorage accounts) and metadata.
• Azure Files REST API: Create and list directories, upload, download and delete files, copy files within a storage account, read file properties and manage file metadata, using the Azure CLI or the Azure Storage SDKs with a connection string, the account key or an account SAS.
• Quota enforcement: Range uploads that would exceed the share’s quota fail with ShareQuotaExceeded.
• Share snapshots: Create snapshots of a share’s contents, and delete a share together with its snapshots.
• Soft delete and restore: With shareDeleteRetentionPolicy enabled, deleted shares stay listed with --include-deleted for the retention period and can be restored.
• Leases: Acquire, renew, change, release, and break leases on a share; a leased share cannot be updated without its lease.
• Usage statistics: Get a share’s usage in bytes with --expand stats. The share’s snapshots count towards it.
• Mounting from workloads: Shares are also served over SMB 3 and NFS 4.1. AKS clusters include the Azure Files CSI driver, so pods can mount shares with the storage account key, and Container Apps environment storage can mount them as volumes.

Configuration

Variable	Default	Effect
LS_AZURE_FILES_SMB_PORT	4445	Port of the emulator’s SMB proxy, which AKS nodes reach as the standard SMB port 445. Change it if the port is already in use.
LS_AZURE_FILES_NFS_PORT	42049	Port of the emulator’s NFS proxy, which AKS nodes reach as the standard NFS port 2049.

Limitations

• Setting file properties is not supported: Set File Properties, which az storage file update and the SDKs’ set_http_headers call, fails and leaves the file empty.
• Restored shares are empty: Restoring a soft-deleted share through Azure Resource Manager brings back the share and its settings, but not its files. Undeleting a share through the Azure Files REST API is not supported.
• Soft delete is off until you enable it: Getting the file service properties always reports share soft delete as enabled for 7 days, but deleted shares are only kept after you enable it with az storage account file-service-properties update, as shown above. Until then, a deleted share is removed permanently.
• Snapshots are not listed: Creating a snapshot works, but az storage share-rm list --include-snapshot does not return it.
• Access tiers are recorded only: Changing a share’s access tier has no effect on behavior.
• Identity-based access: SMB access uses the storage account’s primary key (key1); the secondary key does not work there. Microsoft Entra and Kerberos authentication are not emulated.
• Container Instances: Azure Files volumes in container groups are not mounted.

API Coverage

12 of 12 operations implemented

Formats for tools and AIPage MarkdownCoverage MarkdownCoverage JSONCoverage catalog

Operation ▲	Implemented ▼

PreviousPage 1 of 0Next