Guide

Sandbox groups

A sandbox group is the regional, top-level resource that holds sandboxes and the configuration they share — VNet, identity, disk images, volumes, secrets, connectors. Create one, grant data-plane access, then run sandboxes inside it.

Create a group

A group is the security and configuration boundary for the sandboxes inside it. Pick a subscription, resource group, name, and region.

1. Open sandboxes.azure.com/sandbox-groups and select Create.
2. Choose a subscription and resource group.
3. Enter a unique name (3–64 chars, lowercase, hyphens).
4. Pick a region that supports sandbox groups.
5. (Optional) configure networking, identity, and labels.
6. Select Create. The group transitions from Creating → Succeeded.

Bash

aca sandboxgroup create --name my-group --location westus2 --set-config

PowerShell

aca sandboxgroup create --name my-group --location westus2 --set-config

SDK

from azure.identity import DefaultAzureCredential
from azure.containerapps.sandbox import SandboxGroupManagementClient

mgmt = SandboxGroupManagementClient(
    DefaultAzureCredential(),
    subscription_id=SUBSCRIPTION_ID,
    resource_group=RESOURCE_GROUP,
)
mgmt.create_group("my-group", location="westus2")

List and get groups

The standard create / list / get triad.

The list at sandboxes.azure.com/sandbox-groups shows every group across your selected subscriptions, with name, region, state, and sandbox count. Filter by subscription, resource group, or state. Select a row to open the group overview.

Bash

aca sandboxgroup list
aca sandboxgroup get --name my-group

PowerShell

aca sandboxgroup list
aca sandboxgroup get --name my-group

SDK

for g in mgmt.list_groups():
    print(g.name, g.location)

detail = mgmt.get_group("my-group")
print(detail.location, detail.properties.get("provisioningState"))

Grant data-plane access

The control plane creates the group. The data plane — aca sandbox …, SandboxGroupClient — needs the Container Apps SandboxGroup Data Owner role assigned at the group scope. Role propagation takes ~30–60s; both the CLI and SDK auto-retry 403s for ~100s so the first data call still succeeds.

1. Open the group, then Access control (IAM) → Add role assignment.
2. Pick Container Apps SandboxGroup Data Owner.
3. Assign it to the user, group, or service principal that will call the data plane.

Bash

PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)

aca sandboxgroup role create \
  --group my-group \
  --role "Container Apps SandboxGroup Data Owner" \
  --principal-id "$PRINCIPAL_ID"

PowerShell

$PrincipalId = az ad signed-in-user show --query id -o tsv

aca sandboxgroup role create `
  --group my-group `
  --role "Container Apps SandboxGroup Data Owner" `
  --principal-id $PrincipalId

SDK

import uuid
from azure.mgmt.authorization import AuthorizationManagementClient

ROLE = "Container Apps SandboxGroup Data Owner"
scope = (
    f"/subscriptions/{SUBSCRIPTION_ID}"
    f"/resourceGroups/{RESOURCE_GROUP}"
    f"/providers/Microsoft.App/sandboxGroups/my-group"
)

auth = AuthorizationManagementClient(credential, SUBSCRIPTION_ID)
role_def = next(auth.role_definitions.list(scope, filter=f"roleName eq '{ROLE}'"))
auth.role_assignments.create(
    scope,
    str(uuid.uuid4()),
    {
        "role_definition_id": role_def.id,
        "principal_id": PRINCIPAL_ID,
        "principal_type": "User",  # or "ServicePrincipal"
    },
)

Delete a group

Irreversible

Deleting a group removes all sandboxes, disk images, snapshots, volumes, secrets, identity assignments, and connector attachments inside it. Export snapshots or volumes first.

Open the group, then select Delete in the overview header and confirm.

Bash

aca sandboxgroup delete --name my-group --yes

PowerShell

aca sandboxgroup delete --name my-group --yes

SDK

mgmt.delete_group("my-group")

Lifecycle states

State	Description
Creating	Resources are being provisioned
Succeeded	The group is ready for use
Updating	Configuration changes are being applied
Failed	Provisioning or update failed; check the Azure activity log
Deleting	Teardown in progress

Related

Create sandboxes

Boot VMs inside the group: basic, advanced, parallel, YAML.

Learn more →

Disk images

Import OCI images as sandbox root filesystems.

Learn more →

Identity

Attach managed identities at the group level.

Learn more →