Azure handlers¶
The Azure provider ships three handler implementations behind four
provider_api values. VMSS and VMSSUniform share one handler class
(VMSSHandler), distinguished only by orchestration_mode.
provider_api |
Handler class | Native resource(s) | Selective release |
|---|---|---|---|
VMSS |
VMSSHandler |
VMSS, Flexible orchestration | yes (per VM) |
VMSSUniform |
VMSSHandler |
VMSS, Uniform orchestration | yes (per instance ID) |
SingleVM |
SingleVMHandler |
Individual Microsoft.Compute/virtualMachines |
yes (per VM name) |
CycleCloud |
CycleCloudHandler |
Nodes in an existing CycleCloud cluster | yes (per node) |
Decision tree¶
- Is the workload managed by an existing Azure CycleCloud HPC cluster?
- Yes - use
CycleCloud. - Does the workload need to be a long-lived, individually addressable VM rather than a scalable pool?
- Yes - use
SingleVM. - Otherwise - use
VMSS(Flexible orchestration is the default and supports Spot, instance mix, and zone spreading). UseVMSSUniformonly if you specifically need Uniform orchestration semantics.
VMSS (Flexible orchestration)¶
The VMSS handler creates one Microsoft.Compute/virtualMachineScaleSets
resource per ORB request, with
sku.capacity = request.requested_count. Networking defaults to
template.network_config; if that is omitted, the handler falls back to
the shared subnet_ids field and auto-builds a minimal network_config
from it.
- Acquire - submits one VMSS create/update deployment via the async Compute SDK.
- Release - for Flexible orchestration, deletes the named VM members
individually (
virtual_machines.begin_delete); if every member of the VMSS is released, the handler deletes the VMSS itself afterward instead of leaving an empty scale set behind.
Instance mix (vm_sizes or ranked vm_size_preferences with
vmss_allocation_strategy="Prioritized") is submitted as VMSS
skuProfile.vmSizes. Spot Priority Mix (spot_percentage,
base_regular_priority_count) is submitted as VMSS priorityMixPolicy
and requires Flexible orchestration with priority="Spot".
VMSSUniform¶
Same handler class as VMSS, with orchestration_mode="Uniform"
required. Release behaviour differs because Uniform VMSS members are
identified by numeric instance ID rather than VM name:
- Release - either deletes the whole VMSS (when every member is
released) or calls
virtual_machine_scale_sets.begin_delete_instanceswith the resolved instance IDs. overprovisionis only valid in Uniform orchestration mode.
SingleVM¶
The SingleVM handler provisions individual VMs via ARM deployments
(AzureDeploymentService), one deployment per requested VM, up to
request.requested_count.
- Acquire - resolves the subnet (
network_config.subnet_idorsubnet_ids), resolves SSH keys (ssh_key_namevia the Azure SSH Public Key resource API, or inlinessh_public_keys), then submits one ARM deployment per VM. If a transient allocation failure occurs (AllocationFailed,ZonalAllocationFailed,SkuNotAvailable,OverconstrainedAllocationRequest) and more than onevm_size/vm_size_preferencescandidate is configured, the handler retries with the next candidate size. - Release - deletes the named VM(s) directly;
deletion of the dependent NIC and public IP relies on Azure's
deleteOption: Deletecascade from the VM.
CycleCloud¶
The CycleCloud handler does not call Azure Compute APIs directly — it talks to a CycleCloud cluster's own REST API (see Authentication).
- Acquire - submits an "add nodes" request against
cluster_name/node_array. - Release - submits a terminate request for the given node IDs.
- Status - CycleCloud node states map to ORB machine status as follows:
| CycleCloud state | ORB status |
|---|---|
Off |
stopped |
Acquiring |
pending |
Preparing |
pending |
Starting |
pending |
Started |
running |
Software Configuration |
pending |
Ready |
running |
Deallocating |
shutting-down |
Deallocated |
stopped |
Terminated |
terminated |
Failed |
failed |
| (any other state) | unknown |
CycleCloud templates do not need image, ssh_key_name, or
ssh_public_keys — SSH access and node imaging are managed by
CycleCloud itself.
Capabilities summary¶
provider_api |
Spot | On-demand | Max instances |
|---|---|---|---|
VMSS |
yes | yes | 1000 |
VMSSUniform |
yes | yes | 1000 |
SingleVM |
yes | yes | 1000 |
CycleCloud |
no | yes | - |
None of the four handlers support ORB's start/stop operations — the
Azure provider strategy only advertises create_instances,
terminate_instances, get_instance_status,
describe_resource_instances, validate_template,
and health_check in its capabilities. To
resize a pool, release machines and acquire new ones.
Choosing a provider_api at template-generate time¶
# VMSS (default)
orb templates generate --provider-type azure --provider-api VMSS
# VMSS, Uniform orchestration
orb templates generate --provider-type azure --provider-api VMSSUniform
# SingleVM
orb templates generate --provider-type azure --provider-api SingleVM
# CycleCloud
orb templates generate --provider-type azure --provider-api CycleCloud
Existing templates can be retargeted by editing the provider_api field
in-place. Handler dispatch happens at request time, not at template-create
time.