Guide

Disk images

A disk image defines the root filesystem a sandbox boots from. Start from a prebuilt public image, build a custom image from OCI, or commit a running sandbox to a new image.

You can create or use disk images in three ways:

	Public image	Custom image	Committed image
Source	Prebuilt and maintained by the platform.	Built by you from a remote OCI container image.	Built by you from a running sandbox's filesystem at commit time.
Best for	Getting started, or when a stock base OS or runtime is all you need.	Baking dependencies into an image you already publish to a registry.	Capturing setup that's easier to do interactively inside a sandbox than to script.
Referenced by	Name, via --disk.	ID, via --disk-id.	ID, via --disk-id.

Discover public disk images

Reference public disk images by simple name when you create a sandbox. To discover available public disk images:

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Disk images in the left menu.
3. Select the Public tab.
4. Review the image names. These public images appear in the Public Disk Image dropdown when you create a sandbox.

Bash

echo "==> Public disk images (valid --disk values):"
aca sandboxgroup disk list-public

PowerShell

Write-Host "==> Public disk images (valid --disk values):"
aca sandboxgroup disk list-public

SDK

import os

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"],
)

for img in client.list_public_disk_images():
    print(img.name)

Build a disk image from a container image

Custom disk images are built from a remote OCI container image, so any dependencies baked into that image are available as soon as a sandbox boots. To build a custom disk image:

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Disk images.
3. Select + Create.
4. Optionally add identifying Labels for the image.
5. Enter the Base Image URL. This remote OCI image is used to build your custom disk image. For example, docker.io/library/alpine:3.19.
6. Configure authentication under Registry Authentication if the source registry is private. Choose No authentication, Username and token, or Managed identity.
7. Select Create and wait for the image state to show Ready.

Bash

DISK_NAME="alpine-build-example-$RANDOM"

echo "==> Building custom disk image '$DISK_NAME' from alpine:3.19..."
aca sandboxgroup disk create --image docker.io/library/alpine:3.19 --name "$DISK_NAME"

PowerShell

$DISK_NAME = "alpine-build-example-$(Get-Random)"

Write-Host "==> Building custom disk image '$DISK_NAME' from alpine:3.19..."
aca sandboxgroup disk create --image docker.io/library/alpine:3.19 --name $DISK_NAME

SDK

import uuid

BASE_IMAGE = "docker.io/library/alpine:3.19"
disk_name = f"alpine-build-{uuid.uuid4().hex[:8]}"

disk = client.begin_create_disk_image(
    BASE_IMAGE,
    name=disk_name,
    polling_timeout=900,
).result()
print(disk.id, disk.status.state if disk.status else "?")

List and inspect private disk images

Disk images you create through a remote registry or by committing from a running sandbox are private and scoped to your sandbox group. To view private disk images:

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Disk images.
3. Select the Private tab.
4. Select a disk image row to open its details.
5. Use filters or labels to find a specific image.

Bash

echo "==> Listing your private disk images:"
aca sandboxgroup disk list

echo "==> Get details for the first private disk image:"
DISK_IMAGE_ID=$(aca sandboxgroup disk list -o json | jq -r '.[0].id')
aca sandboxgroup disk get --id "$DISK_IMAGE_ID"

PowerShell

Write-Host "==> Listing your private disk images:"
aca sandboxgroup disk list

Write-Host "==> Get details for the first private disk image:"
$DISK_IMAGE_ID = (aca sandboxgroup disk list -o json | ConvertFrom-Json)[0].id
aca sandboxgroup disk get --id $DISK_IMAGE_ID

SDK

for img in client.list_disk_images():
    marker = "  <-- just created" if img.id == disk.id else ""
    print(f"{img.id}  name={img.name or img.labels.get('name', '')}{marker}")

detail = client.get_disk_image(disk.id)
print(detail.status.state if detail.status else "?")
print(detail.image.base if detail.image else "?")

Boot a sandbox from a private disk image

Sandboxes booted from custom or committed images use the disk image ID (--disk-id), not a name.

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Disk images.
3. Open the Private tab.
4. Select + from the disk image row under the Actions column.
5. Confirm CPU, memory, labels, and environment settings.
6. Select Create.

Bash

echo "==> Booting sandbox from disk-id $DISK_IMAGE_ID..."
aca sandbox create --disk-id "$DISK_IMAGE_ID"

PowerShell

Write-Host "==> Booting sandbox from disk-id $DISK_IMAGE_ID..."
aca sandbox create --disk-id $DISK_IMAGE_ID

SDK

sandbox = client.begin_create_sandbox(
    disk_id=disk.id,
    labels={"guide": "disks-a"},
).result()

result = sandbox.exec("cat /etc/alpine-release")
print(result.stdout.strip())

Commit a running sandbox

note

A sandbox is briefly paused while its filesystem is committed, then resumes after the disk image is created.

You can also create a disk image by committing the filesystem of a running sandbox. This captures runtime changes, such as package installs, downloads, and generated files, so any sandbox booted from the resulting image starts with that state already in place.

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Sandboxes.
3. Select the running sandbox that you want to commit.
4. In the upper-right corner, select the overflow menu (⋮).
5. Select Commit Image from the dropdown.
6. Select Commit to commit the sandbox to a new disk image.

Bash

PRIMER_LABEL="disks-commit-primer-$RANDOM"
echo "==> Booting primer sandbox (default disk)..."
aca sandbox create --disk-id "$DISK_IMAGE_ID" --label name="$PRIMER_LABEL"

echo "==> Looking up primer sandbox ID by label..."
SANDBOX_ID=$(aca sandbox list -l name="$PRIMER_LABEL" -o json | jq -r '.[0].id')

echo "==> Priming: write /example.txt..."
aca sandbox exec --id "$SANDBOX_ID" -c "echo 'hello world!' >> /example.txt"

COMMITTED_DISK_NAME="committed-disk-image-$RANDOM"
echo "==> Committing primer sandbox to disk image '$COMMITTED_DISK_NAME'..."
COMMITTED_DISK_ID=$(aca sandbox commit --id "$SANDBOX_ID" --name "$COMMITTED_DISK_NAME" -o json | jq -r '.diskImage.id')
echo "==> Committed disk image id: $COMMITTED_DISK_ID"

PowerShell

$PRIMER_LABEL = "disks-commit-primer-$(Get-Random)"
Write-Host "==> Booting primer sandbox (default disk)..."
aca sandbox create --disk-id $DISK_IMAGE_ID --label name=$PRIMER_LABEL

Write-Host "==> Looking up primer sandbox ID by label..."
$SANDBOX_ID = (aca sandbox list -l "name=$PRIMER_LABEL" -o json | ConvertFrom-Json)[0].id

Write-Host "==> Priming: write /example.txt..."
aca sandbox exec --id $SANDBOX_ID -c "echo 'hello world!' >> /example.txt"

$COMMITTED_DISK_NAME = "committed-disk-image-$(Get-Random)"
Write-Host "==> Committing primer sandbox to disk image '$COMMITTED_DISK_NAME'..."
$COMMITTED_DISK_ID = (aca sandbox commit --id $SANDBOX_ID --name $COMMITTED_DISK_NAME -o json | ConvertFrom-Json).diskImage.id
Write-Host "==> Committed disk image id: $COMMITTED_DISK_ID"

SDK

import uuid

primer = client.begin_create_sandbox().result()
primer.exec("echo 'hello world!' >> /example.txt")

disk_name = f"committed-disk-image-{uuid.uuid4().hex[:8]}"
disk = primer.begin_commit(name=disk_name, polling_timeout=1200).result()
print(disk.id, disk.status.state if disk.status else "?")

Delete a disk image

A disk image can only be deleted after all dependent sandboxes and child (committed) disk images are deleted.

1. In the ACA Sandboxes portal, open your sandbox group.
2. Select Disk images.
3. Select the Private tab.
4. Locate the row for the disk image you want to delete, and select the bin under the Actions column.
5. Confirm the deletion.

Bash

echo "==> Deleting the source sandbox..."
aca sandbox delete --id "$SANDBOX_ID" --yes

echo "==> Deleting the committed (child) disk image first..."
aca sandboxgroup disk delete --id "$COMMITTED_DISK_ID"

echo "==> Deleting the base disk image..."
aca sandboxgroup disk delete --id "$DISK_IMAGE_ID"

PowerShell

Write-Host "==> Deleting the source sandbox..."
aca sandbox delete --id $SANDBOX_ID --yes

Write-Host "==> Deleting the committed (child) disk image first..."
aca sandboxgroup disk delete --id $COMMITTED_DISK_ID

Write-Host "==> Deleting the base disk image..."
aca sandboxgroup disk delete --id $DISK_IMAGE_ID

SDK

sandbox.delete()
client.delete_disk_image(disk.id)

Related

Create sandboxes

Boot from public and private disk images.

Learn more →

Snapshots

Capture a running sandbox and restore from it.

Learn more →

Volumes

Mount persistent storage into sandboxes.

Learn more →