Skip to content

Commit f75af16

Browse files
paolosalvatoripaolosalvatori
authored
Add Azure Blob Storage service doc (#476)
1 parent 6efe0cc commit f75af16

File tree

1 file changed

+268
-1
lines changed

1 file changed

+268
-1
lines changed

‎src/content/docs/azure/services/blob-storage.mdx‎

Lines changed: 268 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,278 @@
11
---
22
title: "Blob Storage"
3-
description: API coverage for Microsoft.BlobStorage in LocalStack for Azure.
3+
description: Get started with Azure Blob Storage on LocalStack
44
template: doc
55
---
66

77
import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage";
88

9+
## Introduction
10+
11+
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).
12+
13+
LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Blob Storage.
14+
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.
15+
16+
## Getting started
17+
18+
This guide is designed for users new to Blob Storage and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script.
19+
20+
Launch LocalStack using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). Once the container is running, enable Azure CLI interception by running:
21+
22+
```bash
23+
azlocal start-interception
24+
```
25+
26+
:::note
27+
As an alternative to using the `azlocal` CLI, users can run:
28+
29+
`azlocal start-interception`
30+
31+
This command points the `az` CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator REST API.
32+
To revert this configuration, run:
33+
34+
`azlocal stop-interception`
35+
36+
This reconfigures the `az` CLI to send commands to the official Azure management REST API
37+
:::
38+
39+
### Create a resource group
40+
41+
Create a resource group to contain your storage resources:
42+
43+
```bash
44+
az group create \
45+
--name rg-blob-demo \
46+
--location westeurope
47+
```
48+
49+
```bash title="Output"
50+
{
51+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-blob-demo",
52+
"location": "westeurope",
53+
"managedBy": null,
54+
"name": "rg-blob-demo",
55+
"properties": {
56+
"provisioningState": "Succeeded"
57+
},
58+
"tags": null,
59+
"type": "Microsoft.Resources/resourceGroups"
60+
}
61+
```
62+
63+
### Create a storage account
64+
65+
Create a storage account in the resource group:
66+
67+
```bash
68+
az storage account create \
69+
--name stblobdemols \
70+
--resource-group rg-blob-demo \
71+
--location westeurope \
72+
--sku Standard_LRS \
73+
--only-show-errors
74+
```
75+
76+
```bash title="Output"
77+
{
78+
...
79+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-blob-demo/providers/Microsoft.Storage/storageAccounts/stblobdemols",
80+
...
81+
"name": "stblobdemols",
82+
...
83+
"placement": null,
84+
"primaryEndpoints": {
85+
"blob": "https://stblobdemols.blob.core.azure.localhost.localstack.cloud:456",
86+
...
87+
},
88+
....
89+
}
90+
```
91+
92+
### Authentication
93+
94+
There are three ways to authenticate storage container commands against the emulator:
95+
96+
#### Storage account key
97+
98+
Retrieve the account key and pass it with `--account-name` and `--account-key`:
99+
100+
```bash
101+
ACCOUNT_KEY=$(az storage account keys list \
102+
--account-name stblobdemols \
103+
--resource-group rg-blob-demo \
104+
--query "[0].value" \
105+
--output tsv)
106+
107+
az storage container list \
108+
--account-name stblobdemols \
109+
--account-key "$ACCOUNT_KEY"
110+
```
111+
112+
#### Login credentials
113+
114+
Use `--auth-mode login` to authenticate with the current session credentials:
115+
116+
```bash
117+
az storage container list \
118+
--account-name stblobdemols \
119+
--auth-mode login
120+
```
121+
122+
#### Connection string
123+
124+
Bundle the account name and key into a single value:
125+
126+
```bash
127+
CONNECTION_STRING=$(az storage account show-connection-string \
128+
--name stblobdemols \
129+
--resource-group rg-blob-demo \
130+
--query connectionString -o tsv)
131+
132+
az storage container list \
133+
--connection-string "$CONNECTION_STRING"
134+
```
135+
136+
The remaining examples in this guide use connection strings for brevity.
137+
138+
### Create and inspect a blob container
139+
140+
Create a container in the storage account:
141+
142+
```bash
143+
az storage container create \
144+
--name documents \
145+
--connection-string "$CONNECTION_STRING"
146+
```
147+
148+
```bash title="Output"
149+
{
150+
"created": true
151+
}
152+
```
153+
154+
Verify the container exists:
155+
156+
```bash
157+
az storage container exists \
158+
--name documents \
159+
--connection-string "$CONNECTION_STRING"
160+
```
161+
162+
```bash title="Output"
163+
{
164+
"exists": true
165+
}
166+
```
167+
168+
List containers in the storage account:
169+
170+
```bash
171+
az storage container list \
172+
--connection-string "$CONNECTION_STRING"
173+
```
174+
175+
```bash title="Output"
176+
[
177+
{
178+
...
179+
"name": "documents",
180+
"properties": {
181+
...
182+
"lease": {
183+
...
184+
},
185+
...
186+
},
187+
...
188+
}
189+
]
190+
```
191+
192+
### Upload, list, and download blobs
193+
194+
Upload a local file as a block blob:
195+
196+
```bash
197+
echo "Hello from LocalStack" > /tmp/hello.txt
198+
199+
az storage blob upload \
200+
--container-name documents \
201+
--name hello.txt \
202+
--file /tmp/hello.txt \
203+
--connection-string "$CONNECTION_STRING"
204+
```
205+
206+
```bash title="Output"
207+
{
208+
"client_request_id": "...",
209+
"content_md5": "...",
210+
"date": "...",
211+
"etag": "...
212+
...
213+
}
214+
```
215+
216+
List blobs in the container:
217+
218+
```bash
219+
az storage blob list \
220+
--container-name documents \
221+
--connection-string "$CONNECTION_STRING" \
222+
--output table
223+
```
224+
225+
Download the blob to a local file:
226+
227+
```bash
228+
az storage blob download \
229+
--container-name documents \
230+
--name hello.txt \
231+
--file /tmp/hello-downloaded.txt \
232+
--connection-string "$CONNECTION_STRING"
233+
```
234+
235+
```bash title="Output"
236+
Finished[#############################################################] 100.0000%
237+
{
238+
"container": "documents",
239+
...
240+
}
241+
```
242+
243+
Delete the blob:
244+
245+
```bash
246+
az storage blob delete \
247+
--container-name documents \
248+
--name hello.txt \
249+
--connection-string "$CONNECTION_STRING"
250+
```
251+
252+
## Features
253+
254+
The Blob Storage emulator supports the following features:
255+
256+
- **Data plane REST API**: Blob CRUD, message operations (put, peek, get, delete), container metadata, stored access policies, and SAS token generation.
257+
- **Control plane REST API**: Create, update, delete, and get containers, get and set container service properties via Azure Resource Manager.
258+
- **Multiple authentication modes**: Storage account key, login credentials, and connection strings.
259+
260+
## Limitations
261+
262+
- **No data persistence across restarts**: Blob data is not persisted and is lost when the LocalStack emulator is stopped or restarted.
263+
- **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.
264+
- **Storage account keys**: Keys are emulator-generated rather than managed by Azure.
265+
- **Header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected.
266+
- **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted.
267+
268+
## Samples
269+
270+
The following samples demonstrate how to use Blob Storage with LocalStack for Azure:
271+
272+
- [Azure Functions Sample with LocalStack for Azure](https://github.com/localstack/localstack-azure-samples/tree/main/samples/function-app-storage-http/dotnet)
273+
- [Azure Functions App with Managed Identity](https://github.com/localstack/localstack-azure-samples/tree/main/samples/function-app-managed-identity/python)
274+
- [Azure Web App with Managed Identity](https://github.com/localstack/localstack-azure-samples/tree/main/samples/web-app-managed-identity/python)
275+
9276
## API Coverage
10277
11278
<AzureFeatureCoverage service="Microsoft.BlobStorage" client:load />

0 commit comments

Comments
 (0)