Guide

Labels and selectors

Labels are key-value metadata on sandboxes. Add labels when you create sandboxes, then use selectors to find workers by tenant, role, job, or environment.

Create sandboxes with labels

Labels are set at sandbox creation time. Use stable keys that your automation can query later.

Open the group at sandboxes.azure.com/sandbox-groups and select Sandboxes.
Select Create.
Pick a disk image, such as ubuntu.
Open Labels and add tenant, role, and any job-specific labels.
Select Create.

Bash
PowerShell
SDK

aca sandbox create --label name=worker-0 --label tenant=t42 --label role=worker
aca sandbox create --label name=worker-1 --label tenant=t42 --label role=worker
aca sandbox create --label name=control-0 --label tenant=t42 --label role=control

aca sandbox create --label name=worker-0 --label tenant=t42 --label role=worker
aca sandbox create --label name=worker-1 --label tenant=t42 --label role=worker
aca sandbox create --label name=control-0 --label tenant=t42 --label role=control

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

credential = DefaultAzureCredential()
client = SandboxGroupClient(
    endpoint_for_region(ACA_SANDBOXGROUP_REGION),
    credential,
    subscription_id=AZURE_SUBSCRIPTION_ID,
    resource_group=ACA_RESOURCE_GROUP,
    sandbox_group=ACA_SANDBOX_GROUP,
)

created = []
for index, role in enumerate(["worker", "worker", "control"]):
    sandbox = client.begin_create_sandbox(
        labels={"tenant": "t42", "role": role, "index": str(index)},
    ).result()
    created.append(sandbox)

Filter with selectors

Selectors match exact key-value pairs. Multi-label selectors use AND logic, so every label must match.

Open the group and select Sandboxes.
Use the label filter to enter tenant=t42,role=worker.
Select a sandbox to review its labels on the detail page.
Clear the filter to return to the full list.

Bash
PowerShell
SDK

aca sandbox list -l "tenant=t42,role=worker"
aca sandbox list -l "tenant=t42,role=control"

aca sandbox list -l "tenant=t42,role=worker"
aca sandbox list -l "tenant=t42,role=control"

workers = list(client.list_sandboxes(labels={"tenant": "t42", "role": "worker"}))
for sandbox in workers:
    print(sandbox.id, sandbox.labels)

controls = list(client.list_sandboxes(labels={"tenant": "t42", "role": "control"}))
print(len(controls))

Read and clean up labeled sandboxes

Use labels to clean up a tenant or job batch without tracking every sandbox ID separately.

Open the filtered Sandboxes list.
Select each matching sandbox.
Select Delete and confirm.

Bash
PowerShell
SDK

IDS=$(aca sandbox list -l "tenant=t42" -o json | jq -r '.[].id')
for id in $IDS; do
  aca sandbox delete --id "$id" --yes
done

$Ids = aca sandbox list -l "tenant=t42" -o json | ConvertFrom-Json | ForEach-Object { $_.id }
foreach ($id in $Ids) {
  aca sandbox delete --id $id --yes
}

for sandbox in client.list_sandboxes(labels={"tenant": "t42"}):
    sandbox.delete()

client.close()
credential.close()

Label conventions

Label key	Example value	Use
`name`	`worker-1`	Human-readable selector for CLI workflows
`role`	`worker`	Separate workers from control sandboxes
`tenant`	`t42`	Isolate one tenant or test run
`job-id`	`abc123`	Delete a batch after a job completes