Replicating to Azure Blob Storage

This guide will show you how to use Litestream to replicate to an Azure Blob Storage container. You will need an Azure account and to complete this guide.

Setup#

Create a container#

In the Azure Portal, use the top search bar to navigate to “Storage Accounts”. If you do not have a storage account, click the “New” button, enter your storage account name, and click “Review + create”.

Once you have a storage account, select it from the list of accounts and navigate to the Containers subsection. Click the "+" button to create a new container. Remember your storage account name and your container name as you’ll need those later.

Create an access key#

From your storage account, navigate to the Access Keys subsection. You’ll see two access keys already exist. Click the “Show keys” button to reveal them. Copy the value of one of the “Key” textboxes. This will be be your account key.

Usage#

Command line usage#

You can replicate to Azure Blob Storage from the command line by setting your account key via an environment variable:

export LITESTREAM_AZURE_ACCOUNT_KEY=...

You can then specify your replica as a replica URL on the command line. For example, you can replicate a database to your container with the following command. Replace the placeholders for your account, container, & path.

litestream replicate /path/to/db abs://STORAGEACCOUNT@CONTAINERNAME/PATH

You can later restore your database from Azure Blob Storage to a local my.db path with the following command.

litestream restore -o my.db abs://STORAGEACCOUNT@CONTAINERNAME/PATH

Configuration file usage#

Litestream is typically run as a background service which uses a configuration file. You can configure a replica for your database using the url format.

dbs:
  - path: /path/to/local/db
    replica:
      url: abs://STORAGEACCOUNT@CONTAINERNAME/PATH
      account-key:  ACCOUNTKEY

Or you can expand your configuration into multiple fields:

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      account-key:  ACCOUNTKEY
      bucket:       CONTAINERNAME
      path:         PATH

You can also use the LITESTREAM_AZURE_ACCOUNT_KEY environment variable instead of specifying the account key in your configuration file.

v0.5.0 Litestream v0.5.0+ uses Azure SDK v2, which maintains compatibility with existing authentication methods and adds support for Azure’s default credential chain including Managed Identity. See the Azure SDK v2 Migration Guide for details on new authentication options.

Authentication Methods#

Shared Key (Account Key)#

The simplest authentication method uses your storage account key:

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      account-key: ACCOUNTKEY
      bucket: CONTAINERNAME
      path: PATH

Or via environment variable:

export LITESTREAM_AZURE_ACCOUNT_KEY=your-account-key

Managed Identity (Azure Infrastructure)#

v0.5.0 When running on Azure infrastructure (VMs, App Service, Container Apps, AKS), you can use Managed Identity without any credentials:

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      bucket: CONTAINERNAME
      path: PATH
      # No account-key needed - uses Managed Identity

Ensure your Azure resource has a Managed Identity enabled and the required Storage Blob Data role assigned.

Service Principal#

v0.5.0 For non-Azure environments or when Managed Identity isn’t suitable, use a service principal via environment variables:

export AZURE_CLIENT_ID=your-app-id
export AZURE_TENANT_ID=your-tenant-id
export AZURE_CLIENT_SECRET=your-client-secret

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      bucket: CONTAINERNAME
      path: PATH

Azure CLI (Local Development)#

v0.5.0 For local development, authenticate using the Azure CLI:

az login

Litestream will automatically use your Azure CLI credentials when no other authentication method is configured.

Important: Your Azure account must have the required Storage Blob Data role assigned. Standard Azure account roles like Owner or Contributor are not sufficient for blob data access.

Required Azure Roles#

When using Microsoft Entra ID authentication (Managed Identity, Service Principal, or Azure CLI), you must assign the appropriate Storage Blob Data role. Standard Azure roles like Owner or Contributor manage the storage account itself but do not grant access to blob data.

Assigning Roles via Azure Portal#

1. Navigate to your Storage Account in the Azure Portal
2. Select Access Control (IAM) from the left menu
3. Click Add → Add role assignment
4. Search for “Storage Blob Data Contributor” (or Reader for read-only access)
5. Select the role and click Next
6. Choose User, group, or service principal (or Managed identity for Azure resources)
7. Select your identity and complete the assignment

Assigning Roles via Azure CLI#

# Assign Storage Blob Data Contributor at storage account scope
az role assignment create \
    --role "Storage Blob Data Contributor" \
    --assignee <your-email-or-object-id> \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"

# Or at container scope (more restrictive)
az role assignment create \
    --role "Storage Blob Data Contributor" \
    --assignee <your-email-or-object-id> \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default/containers/<container>"

See Also#

• Azure SDK v2 Migration - Upgrading authentication
• Troubleshooting - Common issues and solutions
• Configuration Reference - Complete configuration options