Skip to content

Quick Start Guide

Get up and running with the Open Resource Broker in minutes.

Prerequisites

  • Python 3.10 or higher
  • AWS credentials configured (~/.aws/credentials or an IAM instance profile)
  • IAM permissions for EC2, EC2Fleet, SpotFleet, and Auto Scaling — see the README for the full policy

Installation

Standard install

pip install orb-py

Development install

pip install -e ".[dev]"

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:

orb init

For CI/CD pipelines or scripted environments, skip interactive discovery with --non-interactive:

orb init --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:

orb templates generate

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:

orb templates list

For a more readable view:

orb templates list --format table

Step 4: Request machines

Copy a template ID from the output of orb templates list, then request machines:

orb machines request <template-id> 3

Or using flags:

orb machines request --template-id <template-id> --count 3

The command returns a request ID. Use --wait to block until machines are ready:

orb machines request aws-ec2fleet-basic 3 --wait --timeout 600

Step 5: Check request status

orb requests status req-abc123

Request status values: pending, in_progress, completed, failed, cancelled, partial, timeout.

Step 6: View infrastructure

Show what infrastructure ORB is configured to use:

orb infrastructure show

To scan your AWS account for available VPCs, subnets, and security groups:

orb infrastructure discover

Step 7: View configuration

orb config show

Returning machines

When you're done with machines, return them:

orb machines return i-0abc1234def567890 i-0def5678abc123456

Troubleshooting

AWS permissions error — verify your credentials are active:

aws sts get-caller-identity

No templates loaded — re-run generate and check your provider config:

orb templates generate
orb config show

System health check:

orb system health --detailed

Next steps