Provider System¶
ORB's provider system lets AWS, Azure, Google Cloud, and Kubernetes plug into
the same core (CLI, REST API, scheduler integration, DI container) without
that core importing any provider-specific code. Each provider is a
self-contained package under src/orb/providers/<name>/ that registers its
behaviour with shared registries at startup.
For how registration, discovery, and provider selection work internally, see Multi-Provider Design. This page is a developer-facing overview of how a provider package is structured and what each piece is responsible for. For a step-by-step checklist to add a new provider, see Adding a Provider.
Common package layout¶
Every provider mirrors the same skeleton:
src/orb/providers/<name>/
provider_plugin.py # ProviderPlugin subclass — the single registration entry point
registration.py # Factory functions used by the plugin (strategy, config, resolver, validator)
defaults_loader.py # ProviderDefaultsLoaderPort — bundled config defaults
exceptions* # Provider-specific exception types
strategy/
<name>_provider_strategy.py # ProviderStrategy implementation
configuration/
config.py # Provider's BaseSettings config class
domain/
template/
<name>_template_aggregate.py # Provider-specific Template subclass
cli/
<name>_cli_spec.py # ProviderCLISpecPort implementation for `orb providers add/update`
scheduler/
hostfactory_field_mapping.py # FieldMappingPort — HostFactory field translation
infrastructure/
<name>_client.py # Thin SDK client wrapper
<name>_handler_factory.py # Per-API-type handler creation
handlers/ # Concrete handlers (one per provider API/operation family)
services/ # Provider-scoped domain services (health checks, provisioning, capability checks, ...)
AWS and Kubernetes additionally expose a <name>_template_dto_config.py under
domain/template/; Azure and Google Cloud expose the equivalent extension model as
TemplateExtensionConfig in configuration/template_extension.py. Either
shape is returned from the plugin's template_dto_config() accessor and
registered with TemplateExtensionRegistry so TemplateDTO can parse
provider-specific template fields.
The pieces, and what registers them¶
provider_plugin.py— aProviderPluginsubclass (seesrc/orb/providers/base/provider_plugin.py). Declaresprovider_nameand implements the satellite accessors (strategy_factory,config_factory,template_dto_config,cli_spec,field_mapping,defaults_loader,template_example_generator, plus optional hooks). This is the only file wired intopyproject.toml's[project.entry-points."orb.providers"]group — nothing else needs the entry point declared.registration.py— holds the factory functions the plugin exposes (create_<name>_strategy,create_<name>_config, and optionallycreate_<name>_resolver/create_<name>_validator), plus any provider-specific registration helpers (for example AWS registers IAM/Cognito auth strategies and DynamoDB/Aurora storage backends from here).strategy/<name>_provider_strategy.py— theProviderStrategyimplementation (AWSProviderStrategy,AzureProviderStrategy,GCPProviderStrategy,K8sProviderStrategy). All provisioning, termination, status, validation, and health-check operations are dispatched through itsexecute_operation(ProviderOperation) -> ProviderResultmethod. It is registered with the globalProviderRegistry(type-level) or as a named instance, and is whatProviderSelectionServiceresolves a template or CLI call to.configuration/config.py— apydantic_settings.BaseSettingssubclass holding the provider's typed configuration (credentials, region/project/ cluster, handler toggles, and so on), with automatic environment-variable mapping. Registered withProviderSettingsRegistryvia the plugin'sprovider_settings_class().domain/template/<name>_template_aggregate.py— a provider-specific subclass of the domainTemplateaggregate. Registered withTemplateFactoryvia the plugin'stemplate_class()when atemplate_factoryis supplied during initialization.cli/<name>_cli_spec.py— implementsProviderCLISpecPort(add_arguments,extract_config,extract_partial_config,validate_add,generate_name,format_display). Registered withCLISpecRegistry, and used by theorb providers add/updatecommands to collect and validate provider-specific configuration interactively or via flags.scheduler/hostfactory_field_mapping.py— implementsFieldMappingPort, translating HostFactory's camelCase template fields (for example AWS'ssubnetId,fleetRole) to ORB's internal snake_case fields on top of the mappings shared by every provider. Registered withFieldMappingRegistry.defaults_loader.py— implementsProviderDefaultsLoaderPort. Itsload_defaults()reads a bundled JSON file (for example AWS'sconfig/aws_defaults.json) and returns a dict in the same shape asdefault_config.json, merged in byConfigurationLoaderat startup. Registered withDefaultsLoaderRegistry.infrastructure/<name>_handler_factory.pyandinfrastructure/handlers/— the provider's internal dispatch from a template/API type to a concrete handler implementation (for example AWS'sEC2Fleet,ASG,SpotFleet,RunInstances, and MicroVM handlers). This layer is internal to the provider; the strategy is the only thing the rest of ORB calls.services/— provider-scoped domain services the strategy and handlers delegate to, such as health checks, capability/template validation, provisioning orchestration, and infrastructure discovery. Contents vary by provider since each cloud's operational model differs.
Provider notes¶
AWS (src/orb/providers/aws/)¶
The most complete provider package, with dedicated handlers for EC2 Fleet,
Auto Scaling Groups, Spot Fleet, RunInstances, and Lambda-based MicroVMs under
infrastructure/handlers/, plus its own auth/ (IAM, Cognito), resilience/,
storage/ (DynamoDB and Aurora backends registered in the plugin's
_do_initialize), and persistence/ modules. boto3/botocore currently
ship in ORB's core dependencies for backward compatibility, with
pip install orb-py[aws] as the forward-compatible explicit install path.
Azure (src/orb/providers/azure/)¶
Wraps Azure Compute, Network, and Resource management SDKs behind
infrastructure/azure_client.py and infrastructure/azure_handler_factory.py,
with a dedicated managers/azure_resource_manager.py for higher-level
resource operations (such as VMSS capacity) and infrastructure/
cyclecloud_session*.py for CycleCloud-based session handling. Install with
pip install orb-py[azure].
Google Cloud (src/orb/providers/gcp/)¶
Uses infrastructure/compute_client.py and infrastructure/
gcp_handler_factory.py to drive Compute Engine, with factories.py
centralizing the shared factory protocols used by both registration.py and
provider_plugin.py. Install with pip install orb-py[gcp].
Kubernetes (src/orb/providers/k8s/)¶
Structurally the most distinct provider: in addition to the standard
strategy/, infrastructure/, and services/ layout, it has dedicated
watch/ (node and pod watchers, event watching, multi-namespace support) and
reconciliation/ (startup reconciliation, orphan and timeout garbage
collection) packages supporting its reconciler-based operating model, plus a
native_spec_resolver.py for resolving native Kubernetes manifests from
templates. Install with pip install orb-py[k8s].
Where to go next¶
- Multi-Provider Design — the
full plugin architecture: entry points, the
ProviderPluginandProviderStrategycontracts, provider selection and load balancing, and the template-extension/defaults/field-mapping registries. - Adding a Provider — a concrete checklist for implementing a new provider package.
- Resilience Patterns — error handling and retry logic shared across providers.
- Data Models — the domain validation architecture providers extend via template DTOs.