Azurite V3

Note: The latest Azurite V3 code, which supports Blob, Queue, and Table (preview) is in the main branch. The legacy Azurite V2 code is in the legacy-master branch.

• Azurite V3
  • Introduction
  • Features & Key Changes in Azurite V3
  • Getting Started
    • GitHub
    • NPM
    • Visual Studio Code Extension
    • DockerHub
      • Docker Compose
    • NuGet
    • Visual Studio
  • Supported Command Line Options
    • Listening Host Configuration
    • Listening Port Configuration
    • Workspace Path Configuration
    • Access Log Configuration
    • Debug Log Configuration
    • Loose Mode Configuration
    • Certificate Configuration (HTTPS)
    • OAuth Configuration
    • Skip API Version Check
    • Disable Product Style Url
    • Use in-memory storage
    • Command Line Options Differences between Azurite V2
  • Supported Environment Variable Options
    • Customized Storage Accounts & Keys
    • Customized Metadata Storage by External Database (Preview)
  • HTTPS Setup
    • PEM
    • PFX
  • Usage with Azure Storage SDKs or Tools
    • Default Storage Account
    • Customized Storage Accounts & Keys
    • Connection Strings
    • Azure SDKs
    • Storage Explorer
  • Workspace Structure
  • Differences between Azurite and Azure Storage
    • Storage Accounts
    • Endpoint & Connection URL
    • Scalability & Performance
    • Error Handling
    • API Version Compatible Strategy
    • RA-GRS
  • Differences between Azurite V3 and Azurite V2
    • Architecture
    • Server Code Generator
    • TypeScript
    • Features Scope
  • TypeScript Server Code Generator
  • Support Matrix
  • License
  • We Welcome Contributions!

Introduction

Azurite is an open source Azure Storage API compatible server (emulator). Based on Node.js, Azurite provides cross platform experiences for customers wanting to try Azure Storage easily in a local environment. Azurite simulates most of the commands supported by Azure Storage with minimal dependencies.

Azurite V2 is manually created with pure JavaScript, popular and active as an open source project. However, Azure Storage APIs are growing and keeping updating, manually keeping Azurite up to date is not efficient and prone to bugs. JavaScript also lacks strong type validation which prevents easy collaboration.

Compared to V2, Azurite V3 implements a new architecture leveraging code generated by a TypeScript Server Code Generator we created. The generator uses the same swagger (modified) used by the new Azure Storage SDKs. This reduces manual effort and facilitates better code alignment with storage APIs.

3.0.0-preview is the first release version using Azurite's new architecture.

Features & Key Changes in Azurite V3

• Blob storage features align with Azure Storage API version 2024-08-04 (Refer to support matrix section below)
  • SharedKey/Account SAS/Service SAS/Public Access Authentications/OAuth
  • Get/Set Blob Service Properties
  • Create/List/Delete Containers
  • Create/Read/List/Update/Delete Block Blobs
  • Create/Read/List/Update/Delete Page Blobs
• Queue storage features align with Azure Storage API version 2024-08-04 (Refer to support matrix section below)
  • SharedKey/Account SAS/Service SAS/OAuth
  • Get/Set Queue Service Properties
  • Preflight Request
  • Create/List/Delete Queues
  • Put/Get/Peek/Update/Delete/Clear Messages
• Table storage features align with Azure Storage API version 2024-08-04 (Refer to support matrix section below)
  • SharedKey/Account SAS/Service SAS/OAuth
  • Create/List/Delete Tables
  • Insert/Update/Query/Delete Table Entities
• Features NEW on V3
  • Built with TypeScript and ECMA native promise and async features
  • New architecture based on TypeScript server generator. Leverage auto generated protocol layer, models, serializer, deserializer and handler interfaces from REST API swagger
  • Flexible structure and architecture, supports customizing handler layer implementation, persistency layer implementation, HTTP pipeline middleware injection
  • Detailed debugging log support, easy bug locating and reporting
  • Works with storage .Net SDK basic and advanced sample
  • SharedKey, AccountSAS, ServiceSAS, OAuth, Public Access authentication support
  • Keep updating with latest Azure Storage API version features (Refer to support matrix)

Getting Started

Try with any of following ways to start an Azurite V3 instance.

GitHub

After cloning source code, execute following commands to install and start Azurite V3.

npm ci
npm run build
npm install -g
azurite

NPM

In order to run Azurite V3 you need Node.js installed on your system. Azurite works cross-platform on Windows, Linux, and OS X. Azurite is compatible with the current Node.Js LTS Versions in support.

After installation you can install Azurite simply with npm which is the Node.js package management tool included with every Node.js installation.

npm install -g azurite

Simply start it with the following command:

azurite -s -l c:\azurite -d c:\azurite\debug.log

or,

azurite --silent --location c:\azurite --debug c:\azurite\debug.log

This tells Azurite to store all data in a particular directory c:\azurite. If the -l option is omitted it will use the current working directory. You can also selectively start different storage services.

For example, to start blob service only:

azurite-blob -l path/to/azurite/workspace

Start queue service only:

azurite-queue -l path/to/azurite/workspace

Start table service only:

azurite-table -l path/to/azurite/workspace

Visual Studio Code Extension

Azurite V3 can be installed from Visual Studio Code extension market.

You can quickly start or close Azurite by clicking Azurite status bar item or following commands.

Extension supports following Visual Studio Code commands:

• Azurite: Start Start all Azurite services
• Azurite: Close Close all Azurite services
• Azurite: Clean Reset all Azurite services persistency data
• Azurite: Start Blob Service Start blob service
• Azurite: Close Blob Service Close blob service
• Azurite: Clean Blob Service Clean blob service
• Azurite: Start Queue Service Start queue service
• Azurite: Close Queue Service Close queue service
• Azurite: Clean Queue Service Clean queue service
• Azurite: Start Table Service Start table service
• Azurite: Close Table Service Close table service
• Azurite: Clean Table Service Clean table service

Following extension configurations are supported:

• azurite.blobHost Blob service listening endpoint, by default 127.0.0.1
• azurite.blobPort Blob service listening port, by default 10000
• azurite.queueHost Queue service listening endpoint, by default 127.0.0.1
• azurite.queuePort Queue service listening port, by default 10001
• azurite.tableHost Table service listening endpoint, by default 127.0.0.1
• azurite.tablePort Table service listening port, by default 10002
• azurite.location Workspace location folder path (can be relative or absolute). By default, in the VS Code extension, the currently opened folder is used. If launched from the command line, the current process working directory is the default. Relative paths are resolved relative to the default folder.
• azurite.silent Silent mode to disable access log in Visual Studio channel, by default false
• azurite.debug Output debug log into Azurite channel, by default false
• azurite.loose Enable loose mode which ignores unsupported headers and parameters, by default false
• azurite.cert Path to a PEM or PFX cert file. Required by HTTPS mode.
• azurite.key Path to a PEM key file. Required when azurite.cert points to a PEM file.
• azurite.pwd PFX cert password. Required when azurite.cert points to a PFX file.
• azurite.oauth OAuth oauthentication level. Candidate level values: basic.
• azurite.skipApiVersionCheck Skip the request API version check, by default false.
• azurite.disableProductStyleUrl Force parsing storage account name from request URI path, instead of from request URI host.
• azurite.inMemoryPersistence Disable persisting any data to disk. If the Azurite process is terminated, all data is lost.
• azurite.extentMemoryLimit When using in-memory persistence, limit the total size of extents (blob and queue content) to a specific number of megabytes. This does not limit blob, queue, or table metadata. Defaults to 50% of total memory.

DockerHub

Run Azurite V3 docker image

Note. Find more docker images tags in https://mcr.microsoft.com/v2/azure-storage/azurite/tags/list

docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite

-p 10000:10000 will expose blob service's default listening port. -p 10001:10001 will expose queue service's default listening port. -p 10002:10002 will expose table service's default listening port.

Or just run blob service:

docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite azurite-blob --blobHost 0.0.0.0

Run Azurite V3 docker image with customized persisted data location

docker run -p 10000:10000 -p 10001:10001 -v c:/azurite:/data mcr.microsoft.com/azure-storage/azurite

-v c:/azurite:/data will use and map host path c:/azurite as Azurite's workspace location.

Customize all Azurite V3 supported parameters for docker image

docker run -p 7777:7777 -p 8888:8888 -p 9999:9999 -v c:/azurite:/workspace mcr.microsoft.com/azure-storage/azurite azurite -l /workspace -d /workspace/debug.log --blobPort 7777 --blobHost 0.0.0.0 --queuePort 8888 --queueHost 0.0.0.0 --tablePort 9999 --tableHost 0.0.0.0 --loose --skipApiVersionCheck --disableProductStyleUrl

Above command will try to start Azurite image with configurations:

-l //workspace defines folder /workspace as Azurite's location path inside docker instance, while /workspace is mapped to c:/azurite in host environment by -v c:/azurite:/workspace

-d //workspace/debug.log enables debug log into /workspace/debug.log inside docker instance. debug.log will also mapped to c:/azurite/debug.log in host machine because of docker volume mapping.

--blobPort 7777 makes Azurite blob service listen to port 7777, while -p 7777:7777 redirects requests from host machine's port 7777 to docker instance.

--blobHost 0.0.0.0 defines blob service listening endpoint to accept requests from host machine.

--queuePort 8888 makes Azurite queue service listen to port 8888, while -p 8888:8888 redirects requests from host machine's port 8888 to docker instance.

--queueHost 0.0.0.0 defines queue service listening endpoint to accept requests from host machine.

--tablePort 9999 makes Azurite table service listen to port 9999, while -p 9999:9999 redirects requests from host machine's port 9999 to docker instance.

--tableHost 0.0.0.0 defines table service listening endpoint to accept requests from host machine.

--loose enables loose mode which ignore unsupported headers and parameters.

--skipApiVersionCheck skip the request API version check.

--disableProductStyleUrl force parsing storage account name from request URI path, instead of from request URI host.

If you use customized azurite parameters for docker image, --blobHost 0.0.0.0, --queueHost 0.0.0.0 are required parameters.

In above sample, you need to use double first forward slash for location and debug path parameters to avoid a known issue for Git on Windows.

Will support more release channels for Azurite V3 in the future.

Docker Compose

To run Azurite in Docker Compose, you can start with the following configuration:

---
version: "3.9"
services:
  azurite:
    image: mcr.microsoft.com/azure-storage/azurite
    container_name: "azurite"
    hostname: azurite
    restart: always
    ports:
      - "10000:10000"
      - "10001:10001"
      - "10002:10002"

NuGet

Releasing Azurite V3 to NuGet is under investigation.

Visual Studio

Integrate Azurite with Visual Studio is under investigation.

Supported Command Line Options

Listening Host Configuration

Optional. By default, Azurite V3 will listen to 127.0.0.1 as a local server. You can customize the listening address per your requirements.

Only Accept Requests in Local Machine

--blobHost 127.0.0.1
--queueHost 127.0.0.1
--tableHost 127.0.0.1

Allow Accepting Requests from Remote (potentially unsafe)

--blobHost 0.0.0.0
--queueHost 0.0.0.0
--tableHost 0.0.0.0

Listening