Skip to content

blob-storage.mdx

Latest commit

 

History

History
277 lines (210 loc) · 7.54 KB

blob-storage.mdx

File metadata and controls

277 lines (210 loc) · 7.54 KB
title Blob Storage
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.

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, 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.

:::note As an alternative to using the azlocal CLI, users can run:

azlocal start-interception

This command points the az CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator REST 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

Create a resource group to contain your storage resources:

azlocal group create \
  --name rg-blob-demo \
  --location westeurope
{
  "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 a storage account in the resource group:

azlocal storage account create \
  --name stblobdemols \
  --resource-group rg-blob-demo \
  --location westeurope \
  --sku Standard_LRS \
  --only-show-errors
{
  ...
  "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:

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:

azlocal storage container list \
  --account-name stblobdemols \
  --auth-mode login

Connection string

Bundle the account name and key into a single value:

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:

azlocal storage container create \
  --name documents \
  --connection-string "$CONNECTION_STRING"
{
  "created": true
}

Verify the container exists:

azlocal storage container exists \
  --name documents \
  --connection-string "$CONNECTION_STRING"
{
  "exists": true
}

List containers in the storage account:

azlocal storage container list \
  --connection-string "$CONNECTION_STRING"
[
  {
    ...
    "name": "documents",
    "properties": {
      ...
      "lease": {
        ...
      },
      ...
    },
    ...
  }
]

Upload, list, and download blobs

Upload a local file as a block blob:

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"
{
  "client_request_id": "...",
  "content_md5": "...",
  "date": "...",
  "etag": "...
  ...
}

List blobs in the container:

azlocal storage blob list \
  --container-name documents \
  --connection-string "$CONNECTION_STRING" \
  --output table

Download the blob to a local file:

azlocal storage blob download \
  --container-name documents \
  --name hello.txt \
  --file /tmp/hello-downloaded.txt \
  --connection-string "$CONNECTION_STRING"
Finished[#############################################################]  100.0000%
{
  "container": "documents",
  ...
}

Delete the blob:

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 samples demonstrate how to use Blob Storage with LocalStack for Azure:

API Coverage