Quick Start Guide¶
Get up and running with the Open Resource Broker in minutes.
Prerequisites¶
- Python 3.10 or higher
- AWS credentials configured (
~/.aws/credentialsor an IAM instance profile) - IAM permissions for EC2, EC2Fleet, SpotFleet, and Auto Scaling — see the README for the full policy
Installation¶
Standard install¶
Development install¶
Step 1: Initialize¶
Run orb init to create the configuration directory and set up your first provider.
By default, orb init runs interactively. For AWS it discovers VPCs, subnets,
and security groups. For Azure it lists subscriptions by name and requires an
explicit subscription choice, then lists resource groups and physical locations
for that subscription. The location menu preselects eastus2 when available.
For GCP it lists accessible projects
and regions for the selected project, with the ADC project preselected when
available. Each Azure and GCP choice also allows manual entry when listing is
unavailable or the desired resource is not shown. If GCP project listing returns
403, the wizard offers the ADC project when available; if region listing returns
403, it offers common regions marked as unverified:
For CI/CD pipelines or scripted environments, skip interactive discovery with --non-interactive:
You can also pass infrastructure details directly in non-interactive mode:
orb init --non-interactive \
--region us-east-1 \
--profile my-aws-profile \
--subnet-ids subnet-0abc1234,subnet-0def5678 \
--security-group-ids sg-0abc1234 \
--fleet-role arn:aws:iam::123456789012:role/MySpotFleetRole
This guide uses AWS, but the same orb init --provider-type <type> flow sets up Azure, Google Cloud, and Kubernetes — see the Azure Provider Guide, the Google Cloud Provider Guide, and the Kubernetes Provider Guide.
Step 2: Generate templates¶
Generate example templates for your configured provider:
This writes template files to your ORB work directory. Templates are scoped to a provider type (e.g., AWS EC2Fleet, SpotFleet) and reusable across provider instances.
Step 3: List templates¶
Verify the templates loaded correctly:
For a more readable view:
Step 4: Request machines¶
Copy a template ID from the output of orb templates list, then request machines:
Or using flags:
The command returns a request ID. Use --wait to block until machines are ready:
Step 5: Check request status¶
Request status values: pending, in_progress, completed, failed, cancelled, partial, timeout.
Step 6: View infrastructure¶
Show what infrastructure ORB is configured to use:
To scan your AWS account for available VPCs, subnets, and security groups:
Step 7: View configuration¶
Returning machines¶
When you're done with machines, return them:
Troubleshooting¶
AWS permissions error — verify your credentials are active:
No templates loaded — re-run generate and check your provider config:
System health check:
Next steps¶
- CLI Reference — full command and flag reference
- Configuration Guide — advanced provider and storage config
- Template Management — creating and customizing templates