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

Set labels when you create a sandbox. Use stable keys that your automation can query later.

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

Bash

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

PowerShell

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

SDK

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 in the portal and with selectors

In the portal Sandboxes list, the search box does substring matching across the sandbox ID, label keys, and label values. It is not an exact key-value selector and does not require multiple labels to match together.

1. Open the group and select Sandboxes.
2. Use the search box to enter text from a sandbox ID, label key, or label value, such as t42 or worker.
3. Select a sandbox to review its labels on the detail page.
4. Clear the search box to return to the full list.

Bash

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

PowerShell

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

SDK

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 each sandbox ID separately.

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

Bash

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

PowerShell

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

SDK

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

Related

Create sandboxes

Add labels while you create sandbox instances.

Learn more →

Interactive shell

Connect to a labeled sandbox for live debugging.

Learn more →

Lifecycle

Suspend, resume, and delete matching sandboxes.

Learn more →