From 1627ecbcf2080869c57b6461132f9ce2091cf908 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Wed, 4 Mar 2026 10:27:36 +0100 Subject: [PATCH 1/6] Add Azure Blob Storage service doc --- .../docs/azure/services/blob-storage.mdx | 259 +++++++++++++++++- 1 file changed, 258 insertions(+), 1 deletion(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index 32755f54..ff9f1dbb 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -1,11 +1,268 @@ --- title: "Blob Storage" -description: API coverage for Microsoft.BlobStorage in LocalStack for Azure. +description: Get started with Azure Blob Storage on LocalStack template: doc --- import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage"; +## Introduction + +Azure Blob Storage is a highly scalable object storage solution optimized for storing massive volumes of unstructured data, such as text and binary content. It supports block blobs, append blobs, and page blobs, and is commonly used for serving documents, images, and streaming media. For more information, see [Introduction to Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction). + +LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Blob Storage. +The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Blob Storage's integration with LocalStack. + +## Getting started + +This guide is designed for users new to Blob Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script. + +Start your LocalStack container using your preferred method. For more information, see [Introduction to LocalStack for Azure](../getting-started/index.mdx). + +> [!NOTE] +> As an alternative to using the `azlocal` CLI, customers can run `az start-interception`. This command points the `az` CLI away from the public Azure cloud management API and toward the local emulator API. +To revert this configuration, use `azlocal stop-interception`, which re-configures the CLI to send commands to the official Azure platform management REST API. +At this time, there is no full parity between `azlocal` commands and `az` commands after running `az start-interception`. Therefore, this technique is not fully interchangeable. + +### Create a resource group + +Create a resource group to contain your storage resources: + +```bash +azlocal group create \ + --name rg-blob-demo \ + --location westeurope +``` + +```bash title="Output" +{ + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-blob-demo", + "location": "westeurope", + "managedBy": null, + "name": "rg-blob-demo", + "properties": { + "provisioningState": "Succeeded" + }, + "tags": null, + "type": "Microsoft.Resources/resourceGroups" +} +``` + +### Create a storage account + +Create an [Azure storage account](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview) for Blob Storage: + +```bash +azlocal storage account create \ + --name stblobdemols \ + --resource-group rg-blob-demo \ + --location westeurope \ + --sku Standard_LRS \ + --only-show-errors +``` + +```bash title="Output" +{ + ... + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-blob-demo/providers/Microsoft.Storage/storageAccounts/stblobdemols", + ... + "name": "stblobdemols", + ... + "placement": null, + "primaryEndpoints": { + "blob": "https://stblobdemolsblob.localhost.localstack.cloud:4566", + ... + "container": "https://stblobdemolscontainer.localhost.localstack.cloud:4566", + ... + }, + .... +} +``` + +### Authentication + +There are three ways to authenticate storage container commands against the emulator: + +#### Storage account key + +Retrieve the account key and pass it with `--account-name` and `--account-key`: + +```bash +ACCOUNT_KEY=$(azlocal storage account keys list \ + --account-name stblobdemols \ + --resource-group rg-blob-demo \ + --query "[0].value" \ + --output tsv) + +azlocal storage container list \ + --account-name stblobdemols \ + --account-key "$ACCOUNT_KEY" +``` + +#### Login credentials + +Use `--auth-mode login` to authenticate with the current session credentials: + +```bash +azlocal storage container list \ + --account-name stblobdemols \ + --auth-mode login +``` + +#### Connection string + +Bundle the account name and key into a single value: + +```bash +CONNECTION_STRING=$(azlocal storage account show-connection-string \ + --name stblobdemols \ + --resource-group rg-blob-demo \ + --query connectionString -o tsv) + +azlocal storage container list \ + --connection-string "$CONNECTION_STRING" +``` + +The remaining examples in this guide use connection strings for brevity. + +### Create and inspect a blob container + +Create a container in the storage account: + +```bash +azlocal storage container create \ + --name documents \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +{ + "created": true +} +``` + +Verify the container exists: + +```bash +azlocal storage container exists \ + --name documents \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +{ + "exists": true +} +``` + +List containers in the storage account: + +```bash +azlocal storage container list \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +[ + { + ... + "name": "documents", + "properties": { + ... + "lease": { + ... + }, + ... + }, + ... + } +] +``` + +### Upload, list, and download blobs + +Upload a local file as a block blob: + +```bash +echo "Hello from LocalStack" > /tmp/hello.txt + +azlocal storage blob upload \ + --container-name documents \ + --name hello.txt \ + --file /tmp/hello.txt \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +{ + "client_request_id": "...", + "content_md5": "...", + "date": "...", + "etag": "... + ... +} +``` + +List blobs in the container: + +```bash +azlocal storage blob list \ + --container-name documents \ + --connection-string "$CONNECTION_STRING" \ + --output table +``` + +Download the blob to a local file: + +```bash +azlocal storage blob download \ + --container-name documents \ + --name hello.txt \ + --file /tmp/hello-downloaded.txt \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +Finished[#############################################################] 100.0000% +{ + "container": "documents", + ... +} +``` + +Delete the blob: + +```bash +azlocal storage blob delete \ + --container-name documents \ + --name hello.txt \ + --connection-string "$CONNECTION_STRING" +``` + +## Features + +The Blob Storage emulator supports the following features: + +- **Data plane REST API**: Blob CRUD, message operations (put, peek, get, delete), container metadata, stored access policies, and SAS token generation. +- **Control plane REST API**: Create, update, delete, and get containers, get and set container service properties via Azure Resource Manager. +- **Multiple authentication modes**: Storage account key, login credentials, and connection strings. + +## Limitations + +- **No data persistence across restarts**: Blob data is not persisted and is lost when the LocalStack emulator is stopped or restarted. +- **Blob service properties**: `set_service_properties` is a no-op and `get_service_properties` returns empty defaults, unlike Azure where CORS, logging, and metrics settings are persisted and applied. +- **Storage account keys**: Keys are emulator-generated rather than managed by Azure. +- **Header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. +- **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. + +## Samples + +The following sample demonstrates how to use Blob Storage with LocalStack for Azure: + +- [Azure Functions Sample with LocalStack for Azure](https://github.com/localstack/localstack-azure-samples/tree/main/samples/function-app-storage-http/dotnet) +- [Azure Functions App with Managed Identity](https://github.com/localstack/localstack-azure-samples/tree/main/samples/function-app-managed-identity/python) +- [Azure Web App with Managed Identity](https://github.com/localstack/localstack-azure-samples/tree/main/samples/web-app-managed-identity/python) + ## API Coverage From 59fecddb2be0e8108c85d94c29741449bf4304bf Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Wed, 4 Mar 2026 10:37:33 +0100 Subject: [PATCH 2/6] Fix broken link --- src/content/docs/azure/services/blob-storage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index ff9f1dbb..26509c12 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w This guide is designed for users new to Blob Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script. -Start your LocalStack container using your preferred method. For more information, see [Introduction to LocalStack for Azure](../getting-started/index.mdx). +Start your LocalStack container using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). > [!NOTE] > As an alternative to using the `azlocal` CLI, customers can run `az start-interception`. This command points the `az` CLI away from the public Azure cloud management API and toward the local emulator API. From 030f6bcafe45924fe72dcbf16973ba4d105d162d Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Wed, 4 Mar 2026 11:36:31 +0100 Subject: [PATCH 3/6] Remove storage account link --- src/content/docs/azure/services/blob-storage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index 26509c12..a5457104 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -50,7 +50,7 @@ azlocal group create \ ### Create a storage account -Create an [Azure storage account](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview) for Blob Storage: +Create a storage account in the resource group: ```bash azlocal storage account create \ From ebca82185cba0e38e31df665845c5962c012ed09 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Wed, 4 Mar 2026 15:42:44 +0100 Subject: [PATCH 4/6] Fix azlocal note --- src/content/docs/azure/services/blob-storage.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index a5457104..0bdee163 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -19,10 +19,11 @@ This guide is designed for users new to Blob Storage and assumes basic knowledge Start your LocalStack container using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). -> [!NOTE] -> As an alternative to using the `azlocal` CLI, customers can run `az start-interception`. This command points the `az` CLI away from the public Azure cloud management API and toward the local emulator API. -To revert this configuration, use `azlocal stop-interception`, which re-configures the CLI to send commands to the official Azure platform management REST API. +:::note +As an alternative to using the `azlocal` CLI, customers can run `az start-interception`. This command points the `az` CLI away from the public Azure cloud management API and toward the local emulator API. +To revert this configuration, use `azlocal stop-interception`, which re-configures the CLI to send commands to the official Azure platform management REST API. At this time, there is no full parity between `azlocal` commands and `az` commands after running `az start-interception`. Therefore, this technique is not fully interchangeable. +::: ### Create a resource group From dc7d8cc247ce1cd47f19eea258c5f5bf532d7f16 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Wed, 4 Mar 2026 15:44:21 +0100 Subject: [PATCH 5/6] Fix samples --- src/content/docs/azure/services/blob-storage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index 0bdee163..7ee5a991 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -258,7 +258,7 @@ The Blob Storage emulator supports the following features: ## Samples -The following sample demonstrates how to use Blob Storage with LocalStack for Azure: +The following samples demonstrate how to use Blob Storage with LocalStack for Azure: - [Azure Functions Sample with LocalStack for Azure](https://github.com/localstack/localstack-azure-samples/tree/main/samples/function-app-storage-http/dotnet) - [Azure Functions App with Managed Identity](https://github.com/localstack/localstack-azure-samples/tree/main/samples/function-app-managed-identity/python) From 3742ac408aaed07f6a9e9dd45e9dfc3c01ebe0e9 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Thu, 5 Mar 2026 08:29:23 +0100 Subject: [PATCH 6/6] Improve node wording --- src/content/docs/azure/services/blob-storage.mdx | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index 7ee5a991..5cf4507a 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -20,9 +20,16 @@ This guide is designed for users new to Blob Storage and assumes basic knowledge Start your LocalStack container using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). :::note -As an alternative to using the `azlocal` CLI, customers can run `az start-interception`. This command points the `az` CLI away from the public Azure cloud management API and toward the local emulator API. -To revert this configuration, use `azlocal stop-interception`, which re-configures the CLI to send commands to the official Azure platform management REST API. -At this time, there is no full parity between `azlocal` commands and `az` commands after running `az start-interception`. Therefore, this technique is not fully interchangeable. +As an alternative to using the `azlocal` CLI, users can run: + +`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: + +`azlocal stop-interception` + +This reconfigures the `az` CLI to send commands to the official Azure management REST API. At this time, there is no full parity between `azlocal` and `az` commands after running `az start-interception`. Therefore, this technique is not fully interchangeable. ::: ### Create a resource group