From e35385b4c0c53afe73e0ce657a168a360efb1bf4 Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Fri, 27 Feb 2026 13:16:28 +0530 Subject: [PATCH 1/4] add Azure Queue Storage service doc --- .../docs/azure/services/queue-storage.mdx | 174 +++++++++++++++++- 1 file changed, 173 insertions(+), 1 deletion(-) diff --git a/src/content/docs/azure/services/queue-storage.mdx b/src/content/docs/azure/services/queue-storage.mdx index 182be4d5..cadefb54 100644 --- a/src/content/docs/azure/services/queue-storage.mdx +++ b/src/content/docs/azure/services/queue-storage.mdx @@ -1,11 +1,183 @@ --- title: "Queue Storage" -description: API coverage for Microsoft.QueueStorage in LocalStack for Azure. +description: Get started with Azure Queue Storage on LocalStack template: doc --- import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage"; +## Introduction + +Azure Queue Storage is a messaging service for storing large numbers of messages that can be accessed from anywhere over HTTP or HTTPS. +It is commonly used to decouple application components and build asynchronous processing workflows. +Queue Storage is useful for buffering work items between producers and consumers. + +LocalStack for Azure allows you to build and test Queue Storage workflows in your local environment. +The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Queue Storage's integration with LocalStack. + +## Getting started + +This guide is designed for users new to Queue Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script. + +Start your LocalStack container using your preferred method. +Then start CLI interception: + +```bash +azlocal start_interception +``` + +### Create a resource group + +Create a resource group to contain your storage resources: + +```bash +az group create \ + --name rg-queue-demo \ + --location westeurope +``` + +```bash title="Output" +{ + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-queue-demo", + "location": "westeurope", + "managedBy": null, + "name": "rg-queue-demo", + "properties": { + "provisioningState": "Succeeded" + }, + "tags": null, + "type": "Microsoft.Resources/resourceGroups" +} +``` + +### Create a storage account + +Create a storage account for Queue Storage: + +```bash +az storage account create \ + --name stqueuedemols \ + --resource-group rg-queue-demo \ + --location westeurope \ + --sku Standard_LRS +``` + +```bash title="Output" +{ + ... + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-queue-demo/providers/Microsoft.Storage/storageAccounts/stqueuedemols", + ... + "name": "stqueuedemols", + ... + "placement": null, + "primaryEndpoints": { + "blob": "https://stqueuedemolsblob.localhost.localstack.cloud:4566", + ... + "queue": "https://stqueuedemolsqueue.localhost.localstack.cloud:4566", + ... + }, + .... +} +``` + +### Configure the connection string + +Use the storage account connection string for queue operations: + +```bash +CONNECTION_STRING=$(az storage account show-connection-string \ + --name stqueuedemols \ + --resource-group rg-queue-demo \ + --query connectionString -o tsv) +``` + +### Create and inspect a queue + +Create a queue: + +```bash +az storage queue create \ + --name app-queue \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +{ + "created": true +} +``` + +Verify the queue exists: + +```bash +az storage queue exists \ + --name app-queue \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +{ + "exists": true +} +``` + +List queues in the storage account: + +```bash +az storage queue list \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +[ + { + "approximateMessageCount": null, + "metadata": null, + "name": "app-queue" + } +] +``` + +### Put and read a message + +Add a message to the queue: + +```bash +az storage message put \ + --queue-name app-queue \ + --content "hello-from-localstack" \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +{ + "content": "hello-from-localstack", + ... + "id": "a253ff4a-7b9c-434e-9c33-deae3070193c", + ... +} +``` + +Peek messages without consuming them: + +```bash +az storage message peek \ + --queue-name app-queue \ + --connection-string "$CONNECTION_STRING" +``` + +```bash title="Output" +[ + { + "content": "hello-from-localstack", + ... + "id": "a253ff4a-7b9c-434e-9c33-deae3070193c", + "insertionTime": "2026-02-27T07:45:14+00:00", + ... + } +] +``` + ## API Coverage From 748034442da52f93c65c7dfe856b88faf0a7bcc7 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Mon, 2 Mar 2026 11:06:00 +0100 Subject: [PATCH 2/4] Extend article with features, limitations, differences with Azure, and additional authentication mechanisms --- .../docs/azure/services/queue-storage.mdx | 127 +++++++++++++++--- 1 file changed, 107 insertions(+), 20 deletions(-) diff --git a/src/content/docs/azure/services/queue-storage.mdx b/src/content/docs/azure/services/queue-storage.mdx index cadefb54..254467a6 100644 --- a/src/content/docs/azure/services/queue-storage.mdx +++ b/src/content/docs/azure/services/queue-storage.mdx @@ -10,28 +10,65 @@ import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureF Azure Queue Storage is a messaging service for storing large numbers of messages that can be accessed from anywhere over HTTP or HTTPS. It is commonly used to decouple application components and build asynchronous processing workflows. -Queue Storage is useful for buffering work items between producers and consumers. +Queue Storage is useful for buffering work items between producers and consumers. For more information, see [What is Azure Queue Storage?](https://learn.microsoft.com/en-us/azure/storage/queues/storage-queues-introduction). -LocalStack for Azure allows you to build and test Queue Storage workflows in your local environment. +LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Queue Storage. The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Queue Storage's integration with LocalStack. +## Features + +The Queue Storage emulator supports the following features: + +- **Queue CRUD operations**: Create, list, delete, and check existence of queues. +- **Message operations**: Send (put), peek, get (dequeue), and delete messages. +- **Queue metadata**: Set and retrieve custom metadata on queues. +- **Stored access policies**: Create, list, update, show, and delete queue-level access policies. +- **SAS token generation**: Generate shared access signatures for queue-level access. +- **Control plane (ARM) APIs**: Create and get queues, get and set queue service properties via Azure Resource Manager. +- **Multiple authentication modes**: Storage account key, login credentials, and connection strings. + +## Known limitations + +- **No data persistence across restarts**: Queue data is not persisted and is lost when the LocalStack emulator is stopped or restarted. +- **Loose header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. +- **API version is not enforced**: The emulator does not validate the `x-ms-version` header against supported versions. + + +## Differences with the cloud service + +| Aspect | Azure | LocalStack emulator | +|--------|-------|---------------------| +| **Queue endpoint URL** | `{account}.queue.core.windows.net` | `{account}queue.localhost.localstack.cloud:{port}`: The service type is appended to the account name rather than used as a subdomain. | +| **Queue service properties** | CORS, logging, and metrics settings are persisted and applied | `set_service_properties` is a no-op; `get_service_properties` returns empty defaults | +| **Storage account keys** | Managed by Azure and unique per account | Keys are emulator-generated | +| **Header validation** | Strict: Unsupported headers produce errors. | Loose: Unsupported headers are silently ignored. | +| **API version enforcement** | Enforced per documented version history. | Skipped: All API versions are accepted. | + +## Emulator customization + +The following environment variables can be set on the LocalStack container to customize Queue Storage behavior: + +| Variable | Default | Description | +|----------|---------|-------------| +| `STORAGE_EXPOSE_AZURITE_PORTS` | `true` | When set to `false`, internal storage ports are not mapped to the host, disabling direct connectivity to the storage backend. | + + ## Getting started -This guide is designed for users new to Queue Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script. +This guide is designed for users new to Queue Storage and assumes basic knowledge of the Azure CLI and our [`azlocal` wrapper script](../azlocal). Start your LocalStack container using your preferred method. -Then start CLI interception: -```bash -azlocal start_interception -``` +> [!NOTE] +> All commands in this guide use `azlocal`, our wrapper around the Azure CLI that routes requests to LocalStack. +Once parity between `az` and `azlocal` for storage commands is complete, the commands can be used interchangeably. ### Create a resource group Create a resource group to contain your storage resources: ```bash -az group create \ +azlocal group create \ --name rg-queue-demo \ --location westeurope ``` @@ -52,10 +89,10 @@ az group create \ ### Create a storage account -Create a storage account for Queue Storage: +Create an [Azure storage account](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview) for Queue Storage: ```bash -az storage account create \ +azlocal storage account create \ --name stqueuedemols \ --resource-group rg-queue-demo \ --location westeurope \ @@ -80,23 +117,52 @@ az storage account create \ } ``` -### Configure the connection string +### Authentication + +There are three ways to authenticate storage queue commands against the emulator: + +**1. 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 stqueuedemols \ + --resource-group rg-queue-demo \ + --query "[0].value" \ + --output tsv) + +azlocal storage queue list \ + --account-name stqueuedemols \ + --account-key "$ACCOUNT_KEY" +``` + +**2. Login credentials**: Use `--auth-mode login` to authenticate with the current session credentials: -Use the storage account connection string for queue operations: +```bash +azlocal storage queue list \ + --account-name stqueuedemols \ + --auth-mode login +``` + +**3. Connection string**: Bundle the account name and key into a single value: ```bash -CONNECTION_STRING=$(az storage account show-connection-string \ +CONNECTION_STRING=$(azlocal storage account show-connection-string \ --name stqueuedemols \ --resource-group rg-queue-demo \ --query connectionString -o tsv) + +azlocal storage queue list \ + --connection-string "$CONNECTION_STRING" ``` +The remaining examples in this guide use connection strings for brevity. + ### Create and inspect a queue Create a queue: ```bash -az storage queue create \ +azlocal storage queue create \ --name app-queue \ --connection-string "$CONNECTION_STRING" ``` @@ -110,7 +176,7 @@ az storage queue create \ Verify the queue exists: ```bash -az storage queue exists \ +azlocal storage queue exists \ --name app-queue \ --connection-string "$CONNECTION_STRING" ``` @@ -124,7 +190,7 @@ az storage queue exists \ List queues in the storage account: ```bash -az storage queue list \ +azlocal storage queue list \ --connection-string "$CONNECTION_STRING" ``` @@ -138,12 +204,12 @@ az storage queue list \ ] ``` -### Put and read a message +### Put, peek, and get messages Add a message to the queue: ```bash -az storage message put \ +azlocal storage message put \ --queue-name app-queue \ --content "hello-from-localstack" \ --connection-string "$CONNECTION_STRING" @@ -158,10 +224,10 @@ az storage message put \ } ``` -Peek messages without consuming them: +Peek at messages without consuming them: ```bash -az storage message peek \ +azlocal storage message peek \ --queue-name app-queue \ --connection-string "$CONNECTION_STRING" ``` @@ -178,6 +244,27 @@ az storage message peek \ ] ``` +Get (dequeue) a message from the queue, which makes it invisible to other consumers for the visibility timeout period: + +```bash +azlocal storage message get \ + --queue-name app-queue \ + --connection-string "$CONNECTION_STRING" \ + --output json +``` + +```bash title="Output" +[ + { + "content": "hello-from-localstack", + ... + "id": "a253ff4a-7b9c-434e-9c33-deae3070193c", + "popReceipt": "...", + ... + } +] +``` + ## API Coverage From e24529dc48a7b3ce63fe7f3bc58a61ace3caccae Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Mon, 2 Mar 2026 11:35:24 +0100 Subject: [PATCH 3/4] Fix azlocal link --- src/content/docs/azure/services/queue-storage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/azure/services/queue-storage.mdx b/src/content/docs/azure/services/queue-storage.mdx index 254467a6..2801031e 100644 --- a/src/content/docs/azure/services/queue-storage.mdx +++ b/src/content/docs/azure/services/queue-storage.mdx @@ -55,7 +55,7 @@ The following environment variables can be set on the LocalStack container to cu ## Getting started -This guide is designed for users new to Queue Storage and assumes basic knowledge of the Azure CLI and our [`azlocal` wrapper script](../azlocal). +This guide is designed for users new to Queue Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script. Start your LocalStack container using your preferred method. From 73d22a9cbe0e076afbcc3c558abeb21b85b2a159 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Mon, 2 Mar 2026 15:00:28 +0100 Subject: [PATCH 4/4] Implement Harsh suggestions --- .../docs/azure/services/queue-storage.mdx | 79 +++++++++---------- 1 file changed, 38 insertions(+), 41 deletions(-) diff --git a/src/content/docs/azure/services/queue-storage.mdx b/src/content/docs/azure/services/queue-storage.mdx index 2801031e..110fbf4a 100644 --- a/src/content/docs/azure/services/queue-storage.mdx +++ b/src/content/docs/azure/services/queue-storage.mdx @@ -15,44 +15,6 @@ Queue Storage is useful for buffering work items between producers and consumers LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Queue Storage. The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Queue Storage's integration with LocalStack. -## Features - -The Queue Storage emulator supports the following features: - -- **Queue CRUD operations**: Create, list, delete, and check existence of queues. -- **Message operations**: Send (put), peek, get (dequeue), and delete messages. -- **Queue metadata**: Set and retrieve custom metadata on queues. -- **Stored access policies**: Create, list, update, show, and delete queue-level access policies. -- **SAS token generation**: Generate shared access signatures for queue-level access. -- **Control plane (ARM) APIs**: Create and get queues, get and set queue service properties via Azure Resource Manager. -- **Multiple authentication modes**: Storage account key, login credentials, and connection strings. - -## Known limitations - -- **No data persistence across restarts**: Queue data is not persisted and is lost when the LocalStack emulator is stopped or restarted. -- **Loose header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. -- **API version is not enforced**: The emulator does not validate the `x-ms-version` header against supported versions. - - -## Differences with the cloud service - -| Aspect | Azure | LocalStack emulator | -|--------|-------|---------------------| -| **Queue endpoint URL** | `{account}.queue.core.windows.net` | `{account}queue.localhost.localstack.cloud:{port}`: The service type is appended to the account name rather than used as a subdomain. | -| **Queue service properties** | CORS, logging, and metrics settings are persisted and applied | `set_service_properties` is a no-op; `get_service_properties` returns empty defaults | -| **Storage account keys** | Managed by Azure and unique per account | Keys are emulator-generated | -| **Header validation** | Strict: Unsupported headers produce errors. | Loose: Unsupported headers are silently ignored. | -| **API version enforcement** | Enforced per documented version history. | Skipped: All API versions are accepted. | - -## Emulator customization - -The following environment variables can be set on the LocalStack container to customize Queue Storage behavior: - -| Variable | Default | Description | -|----------|---------|-------------| -| `STORAGE_EXPOSE_AZURITE_PORTS` | `true` | When set to `false`, internal storage ports are not mapped to the host, disabling direct connectivity to the storage backend. | - - ## Getting started This guide is designed for users new to Queue Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script. @@ -121,7 +83,9 @@ azlocal storage account create \ There are three ways to authenticate storage queue commands against the emulator: -**1. Storage account key**: Retrieve the account key and pass it with `--account-name` and `--account-key`: +#### Storage account key + +Retrieve the account key and pass it with `--account-name` and `--account-key`: ```bash ACCOUNT_KEY=$(azlocal storage account keys list \ @@ -135,7 +99,9 @@ azlocal storage queue list \ --account-key "$ACCOUNT_KEY" ``` -**2. Login credentials**: Use `--auth-mode login` to authenticate with the current session credentials: +#### Login credentials + +Use `--auth-mode login` to authenticate with the current session credentials: ```bash azlocal storage queue list \ @@ -143,7 +109,9 @@ azlocal storage queue list \ --auth-mode login ``` -**3. Connection string**: Bundle the account name and key into a single value: +#### Connection string + +Bundle the account name and key into a single value: ```bash CONNECTION_STRING=$(azlocal storage account show-connection-string \ @@ -265,6 +233,35 @@ azlocal storage message get \ ] ``` +## Features + +The Queue Storage emulator supports the following features: + +- **Data plane REST API**: Queue CRUD, message operations (put, peek, get, delete), queue metadata, stored access policies, and SAS token generation. +- **Control plane (ARM) REST API**: Create and get queues, get and set queue service properties via Azure Resource Manager. +- **Multiple authentication modes**: Storage account key, login credentials, and connection strings. + +## Limitations + +- **No data persistence across restarts**: Queue data is not persisted and is lost when the LocalStack emulator is stopped or restarted. +- **Queue endpoint URL**: The service type is appended to the account name (`{account}queue.localhost.localstack.cloud:{port}`) rather than used as a subdomain (`{account}.queue.core.windows.net`). +- **Queue 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. + +## Configuration + +The following environment variables can be set on the LocalStack container to customize Queue Storage behavior: + +- `STORAGE_EXPOSE_AZURITE_PORTS`: When set to `false`, internal storage ports are not mapped to the host, disabling direct connectivity to the storage backend. Defaults to `true`. + +## Samples + +The following sample demonstrates how to use Queue 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) + ## API Coverage