Azure Blob

Azure Blob Storage is the Azure-native recording driver. The azure driver field configures session recordings. It cannot be used for cluster state or audit events.

Storage concern	Supported
Cluster state (name: state)	no
Audit events (name: audit-*)	no
Session recordings (name: recordings)	yes

TL;DR

1. Use Azure Blob Storage when AlmaForge runs on Azure and you want recordings to stay inside Azure-native storage and identity controls.
2. Write a StorageConfig with spec.azure for name: recordings.
3. Grant Storage Blob Data Contributor on the storage account, or an equivalent custom role, and configure container retention or replication for durability.

Prerequisites

Before you start, make sure you have:

• A storage account.
• Two containers named session and inprogress, or permission for the Auth host principal to create them.
• A principal with Storage Blob Data Contributor or an equivalent custom role.
• A retention plan for finalized recordings in the session container.

A locked time-based retention policy on the session container protects finalized recordings for the retention period. Test the policy before locking it: a locked policy cannot be removed or its retention period shortened.

Configuration

Step 1. Pick the storage account layout

Use Azure Blob Storage when AlmaForge runs on Azure and you want the recording path to stay inside Azure-native storage and identity controls.

By default, AlmaForge uses the session container for finalized recordings and inprogress for multipart upload parts.

Step 2. Write the recordings resource

Basic Azure Blob configuration:

recordings.yaml:

examples/storage/azure-blob/recordings.yaml

# Azure Blob destination for session recordings with default container names.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  azure:
    serviceURL: https://account-name.blob.core.windows.net

Override the default container names if your storage account uses a different convention:

custom-containers.yaml:

examples/storage/azure-blob/custom-containers.yaml

# Azure Blob destination with explicit finalized and in-progress containers.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  azure:
    serviceURL: https://account-name.blob.core.windows.net
    sessionContainerName: almaforge-sessions
    inprogressContainerName: almaforge-inprogress

Field	Required	Default	Notes
serviceURL	yes	none	Full Azure Blob endpoint for the storage account.
sessionContainerName	no	session	Container for finalized recordings.
inprogressContainerName	no	inprogress	Container for in-progress upload parts. This one needs delete permission.

Step 3. Restart and verify

Restart the Auth Service after updating the bootstrap file, then verify the active resource:

Terminal

sudo systemctl restart almadalma get storageconfig/recordings -o yaml

Open and end a recorded terminal session, then replay it from the Web UI. Successful replay verifies both the upload path and access to finalized recordings.

URI form

Equivalent URI string, suitable for an environment variable or a CLI flag. The URI scheme is azblob://. The host and path together form the storage account service URL. Container names may be carried either in the query string or in the URI fragment:

text

azblob://alma.blob.core.windows.net/?session_container=sessions&inprogress_container=sessions-inprogress

Canonical query keys are snake_case (session_container, inprogress_container). The typed JSON-tag form (sessionContainerName, inprogressContainerName) is accepted as an alias.

Troubleshooting

Finalized recordings are mutable

Check the time-based retention policy on the session container. An unlocked policy can be changed or removed. A locked policy protects finalized recordings for the retention period. See Azure immutable storage before locking it.

The principal can upload but cleanup fails

The inprogress container needs delete permission because AlmaForge removes multipart parts after finalization.

You want multiple recording stores inside AlmaForge

Do not add them. There is exactly one recordings instance per cluster. Use Azure object replication if you need extra copies.

Operations

Authentication

The Azure Blob driver uses the standard Azure credential chain via DefaultAzureCredential.

The preferred paths are managed identity on Azure VMs, Workload Identity for AKS and similar federated workloads, and environment variables for non-Azure hosts that still need to reach Blob Storage.

RBAC

The built-in Storage Blob Data Contributor role scoped to the storage account covers the driver's container and recording operations.

If your organization requires a custom role with the minimum surface, grant these Azure RBAC actions on the storage account:

Action	Where it applies	Why
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read	sessionContainerName and inprogressContainerName	Read recordings and in-progress upload parts.
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write	sessionContainerName and inprogressContainerName	Upload recording parts and finalized recordings.
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete	inprogressContainerName only	Clean up multipart parts after they have been finalized. The sessionContainerName does not need delete.
Microsoft.Storage/storageAccounts/blobServices/containers/read	both containers	Verify the containers exist on Auth Service startup.
Microsoft.Storage/storageAccounts/blobServices/containers/write	both containers	Create the containers automatically if they do not already exist. Drop this if you pre-create the containers out of band.

Retention and replication

Use a locked time-based retention policy on the session container if you want immutable finalized recordings. Pair that with lifecycle management if you also want eventual deletion after the retention window.

An HTTP-only variant of the endpoint exists for development and testing only. Do not use it in production.

References

• Storage backends overview.
• High availability.
• PostgreSQL.