Guide

Volumes

Create storage that survives sandbox deletion. Mount it into one or more sandboxes so producers, consumers, and agents can share files through normal filesystem calls.

A volume is group-scoped storage that can be mounted into sandboxes. Use Azure Blob to share data across sandboxes when reads dominate, and Data Disk for a fast, POSIX-compliant filesystem owned by a single sandbox.

Choose a volume type

	Azure Blob volume	Data Disk volume
Best for	Sharing large datasets across sandboxes. Read-heavy content.	A sandbox's own persistent working files such as databases, build caches, and project state.
Performance	Cold reads pay network latency to Azure Storage. A local cache absorbs repeated reads.	Reads and writes go directly to the node's local disk with no network on the I/O path.
POSIX compatibility	Partial. No hardlinks, no atomic rename() across directories, and limited fsync semantics.	Full.
Sharing	Mountable on many sandboxes for read sharing. Not suitable for concurrent writers. Writes from one sandbox aren't reliably visible to others.	Mounted by one sandbox at a time. A second mount attempt is rejected.

Create a volume

Create the volume on the sandbox group before you mount it into a sandbox.

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Volumes in the left menu.
3. Select + Create.
4. Enter a Name.
5. Choose Azure Blob for shared storage or Data Disk for block storage.
6. Add labels if you need to filter the volume list.
7. Select Create.

Bash

VOL="vol-cli-$RANDOM"

echo "==> Creating AzureBlob volume $VOL ..."
aca sandboxgroup volume create --name "$VOL" --type AzureBlob

PowerShell

$VOL = "vol-cli-$(Get-Random)"

Write-Host "==> Creating AzureBlob volume $VOL ..."
aca sandboxgroup volume create --name $VOL --type AzureBlob

SDK

import os
import uuid

from azure.identity import DefaultAzureCredential
from azure.containerapps.sandbox import SandboxGroupClient, endpoint_for_region

credential = DefaultAzureCredential()
client = SandboxGroupClient(
    endpoint_for_region(os.environ["ACA_SANDBOXGROUP_REGION"]),
    credential,
    subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"],
    resource_group=os.environ["ACA_RESOURCE_GROUP"],
    sandbox_group=os.environ["ACA_SANDBOX_GROUP"],
)

volume_name = f"vol-{uuid.uuid4().hex[:8]}"
vol = client.create_volume(volume_name, type="AzureBlob")
print(vol.name, vol.type)

Mount a volume on sandboxes

Mounting attaches a volume to a sandbox at a path you choose, so code inside the sandbox reads and writes it with normal filesystem calls.

You can mount a volume either while creating a sandbox or on an already-running sandbox.

Mount while creating a sandbox

1. In the ACA Sandboxes portal, select Sandboxes in the left menu.
2. Select Create in the top-right corner.
3. On the Create sandbox page, expand Advanced options.
4. Open the Volumes dropdown.
5. For each volume, select the volume, the mount path inside the sandbox, and whether the mount is read-only. Select Add after configuring each volume.
6. Finish configuring the sandbox and select Create in the top-right corner.

Mount on a running sandbox

1. In the ACA Sandboxes portal, select Sandboxes in the left menu.
2. Select a running sandbox to open its details.
3. Scroll down to the Volumes tile.
4. At the top right of the tile, select Add volume.
5. Select the volume, the mount path inside the sandbox, and whether the mount is read-only.
6. Select Add at the bottom of the panel. The volume is now available in the sandbox.

To mount the same Azure Blob volume into a producer and a consumer sandbox, use the following commands. Each sandbox uses normal file operations under the mount path.

Bash

echo "==> Producer sandbox..."
aca sandbox create --label name=demo-producer
aca sandbox mount -l name=demo-producer --volume "$VOL" --path /mnt/shared
aca sandbox exec -l name=demo-producer -c "echo '{\"answer\":42,\"status\":\"ok\"}' > /mnt/shared/output.json"

echo "==> Consumer sandbox..."
aca sandbox create --label name=demo-consumer
aca sandbox mount -l name=demo-consumer --volume "$VOL" --path /mnt/shared
aca sandbox exec -l name=demo-consumer -c "cat /mnt/shared/output.json"

PowerShell

Write-Host "==> Producer sandbox..."
aca sandbox create --label name=demo-producer
aca sandbox mount -l name=demo-producer --volume $VOL --path /mnt/shared
aca sandbox exec -l name=demo-producer -c 'echo ''{"answer":42,"status":"ok"}'' > /mnt/shared/output.json'

Write-Host "==> Consumer sandbox..."
aca sandbox create --label name=demo-consumer
aca sandbox mount -l name=demo-consumer --volume $VOL --path /mnt/shared
aca sandbox exec -l name=demo-consumer -c "cat /mnt/shared/output.json"

SDK

from azure.containerapps.sandbox import AddVolumeMountRequest

producer = client.begin_create_sandbox(labels={"role": "producer"}).result()
producer.add_volume_mount(AddVolumeMountRequest(
    volume_name=volume_name,
    mountpoint="/mnt/shared",
))
producer.exec("echo '{\"answer\":42,\"status\":\"ok\"}' > /mnt/shared/output.json")

consumer = client.begin_create_sandbox(labels={"role": "consumer"}).result()
consumer.add_volume_mount(AddVolumeMountRequest(
    volume_name=volume_name,
    mountpoint="/mnt/shared",
))
result = consumer.exec("cat /mnt/shared/output.json")
print(result.stdout.strip())

Inspect a volume

Check whether a volume is attached and review its usage information.

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Volumes.
3. Select a volume row to open its details.
4. Review attached sandboxes, type, state, and usage.

Bash

aca sandboxgroup volume list

PowerShell

aca sandboxgroup volume list

SDK

info = client.get_volume(volume_name)
print(info.is_attached, info.usage)

Delete a volume

Irreversible

Deleting a volume permanently removes the data stored in it.

A volume can only be deleted when no sandbox mounts it. Delete every sandbox that mounts the volume first.

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Volumes.
3. Select one or more volumes.
4. Select Delete.
5. Confirm the deletion.

Bash

aca sandbox delete -l name=demo-producer --yes
aca sandbox delete -l name=demo-consumer --yes
aca sandboxgroup volume delete --name "$VOL"

PowerShell

aca sandbox delete -l name=demo-producer --yes
aca sandbox delete -l name=demo-consumer --yes
aca sandboxgroup volume delete --name $VOL

SDK

producer.delete()
consumer.delete()
client.delete_volume(volume_name)

Related

Create sandboxes

Mount volumes when sandboxes need shared files.

Learn more →

Disk images

Bake dependencies into a reusable root filesystem.

Learn more →

Snapshots

Capture a running sandbox at one point in time.

Learn more →