Guide

Sandbox groups

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

Create a group

A sandbox group is the security and configuration boundary for the sandboxes inside it. Choose 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 (2–63 characters, lowercase letters, numbers, and hyphens; it must start with a letter and end with a letter or number).
4. Pick a region that supports sandbox groups.
5. (Optional) configure networking, identity, and labels.
6. Select Create. The group transitions from Creating to 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

Use create, list, and get to manage sandbox groups.

The list at sandboxes.azure.com/sandbox-groups shows every sandbox group across your selected subscriptions, including name, location, subscription, resource group, and row actions. Search by name, or filter by subscription, resource group, or region. 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 sandbox group. The data plane — aca sandbox …, SandboxGroupClient — needs the Container Apps SandboxGroup Data Owner role assigned at the group scope. RBAC changes can take time to propagate, so retry the first data call if access was just granted.

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 sandbox group removes all sandboxes, disk images, snapshots, volumes, secrets, identity assignments, and connector attachments inside it. Export snapshots or volumes first.

Open the sandbox group, 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

Start sandboxes 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 →