open-resource-broker/README.md at 42688a0eca7cd2db1c9e55217a3f87b01225b0e0 · finos/open-resource-broker

Unified API for orchestrating and provisioning compute capacity

Open Resource Broker (ORB) is a unified API for orchestrating and provisioning compute capacity programmatically. Define what you need in a template, request it, track it, return it — through a CLI, REST API, Python SDK, or MCP server.

Built for AWS today (EC2, Auto Scaling Groups, SpotFleet, EC2Fleet), with an extensible provider system for adding new cloud backends.

Provider support:

AWS — EC2 RunInstances, EC2Fleet, SpotFleet, Auto Scaling Groups
Kubernetes — Pod, Deployment, StatefulSet, Job (pip install "orb-py[k8s]"; see Kubernetes provider docs)
Custom — extensible via provider registry and the orb.providers entry-point group

Scheduler support:

HostFactory — runs as an IBM Spectrum Symphony provider plugin
Standalone — direct usage without an external scheduler

Quick Start

pip install orb-py
orb init
orb templates generate

1. Pick a template

orb templates list

2. Request machines

orb machines request <template-id> 3

3. Check status

orb requests status <request-id>

4. Return machines when done

orb machines return <machine-id-1> <machine-id-2> ...

Setup

Get ORB installed and configured for your environment.

Installation

Standard install (core only — no provider)

pip install orb-py

ORB boots cleanly with no provider registered. Any command that needs a provider will return a clear "no provider configured" error rather than an ImportError.

Per-provider install

pip install "orb-py[aws]"          # AWS provider (boto3 + botocore)
pip install "orb-py[k8s]"   # Kubernetes provider (kubernetes SDK)
pip install "orb-py[aws,cli]"      # AWS provider + colored CLI output
pip install "orb-py[aws,api]"      # AWS provider + REST API server
pip install "orb-py[monitoring-aws]"  # AWS provider + full monitoring stack
pip install "orb-py[all]"          # All providers + all features

Provider extras matrix

Use case	Install command
Core only (no provider)	`pip install orb-py`
AWS operator	`pip install "orb-py[aws]"`
Kubernetes operator	`pip install "orb-py[k8s]"`
AWS + Kubernetes	`pip install "orb-py[aws,k8s]"`
AWS + colored CLI	`pip install "orb-py[aws,cli]"`
AWS + REST API	`pip install "orb-py[aws,api]"`
AWS + monitoring	`pip install "orb-py[monitoring-aws]"`
Full (all providers + features)	`pip install "orb-py[all]"`

With colored CLI output

pip install "orb-py[cli]"

With REST API server

pip install "orb-py[api]"

With monitoring and observability

pip install "orb-py[monitoring]"

Full install (all extras)

pip install "orb-py[all]"

Requires Python 3.10+.

Configuration

orb init creates a config.json in a location based on your install type (virtualenv, user install, system install, or development checkout). Override with:

export ORB_CONFIG_DIR=/path/to/config

Variable	Description
`ORB_ROOT_DIR`	Set base directory for all subdirs (config, work, logs, health, scripts)
`ORB_CONFIG_DIR`	Override config directory path (takes precedence over `ORB_ROOT_DIR`)
`ORB_WORK_DIR`	Override work directory path (takes precedence over `ORB_ROOT_DIR`)
`ORB_LOG_DIR`	Override logs directory path (takes precedence over `ORB_ROOT_DIR`)
`ORB_HEALTH_DIR`	Override health directory path (takes precedence over `ORB_ROOT_DIR`)
`ORB_LOG_LEVEL`	Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`

See the Configuration Guide for path resolution details, environment variables, and REST API server setup.

AWS Provider Setup

ORB uses boto3's standard credential chain — any method that works with the AWS CLI works with ORB.

# Verify your credentials are active
aws sts get-caller-identity

Supported credential methods: AWS CLI profiles, environment variables (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), IAM instance profiles, SSO (aws sso login), and credential process.

Supported resource types

Type	Description
`RunInstances`	Direct EC2 instance provisioning
`EC2Fleet`	Fleet provisioning with mixed instance types
`SpotFleet`	Cost-optimized spot instance fleets
`AutoScalingGroup`	Managed scaling groups

See the AWS Provider Guide for required IAM permissions and SpotFleet service-linked role setup.

Kubernetes Provider Setup

ORB uses the standard Kubernetes client credential chain — any context that works with kubectl works with ORB. Running in-cluster, it auto-detects the mounted service account; running outside, it reads your KUBECONFIG and current context.

# Verify your context is active
kubectl config current-context

Supported credential methods: KUBECONFIG contexts, the default ~/.kube/config, and in-cluster service accounts (auto-detected). See provider discovery for the detection order.

Supported resource types

Type	Description
`Pod`	Single-pod provisioning
`Deployment`	Replica-managed stateless workloads
`StatefulSet`	Stable-identity stateful workloads
`Job`	Run-to-completion batch workloads

Install with pip install "orb-py[k8s]". Minimum RBAC is in docs/root/providers/k8s/rbac.yaml; see the Kubernetes Provider Guide for full setup.

Interfaces

ORB provides four ways to interact with your infrastructure.

CLI Reference

All available commands and flags.

Command	Description
`orb init`	Initialize config and discover AWS infrastructure
`orb init --non-interactive`	Initialize without interactive prompts
`orb templates generate`	Generate example templates for your provider
`orb templates list`	List available templates
`orb templates list --format table`	Table view
`orb templates show <template-id>`	Show a single template
`orb templates validate --file <file>`	Validate a template file
`orb machines request <template-id> <n>`	Request n machines
`orb machines list`	List active machines
`orb machines return <machine-id> [...]`	Return one or more machines
`orb requests status <request-id>`	Check request status
`orb requests list`	List all requests
`orb infrastructure show`	Show configured infrastructure
`orb infrastructure discover`	Scan AWS for VPCs, subnets, security groups
`orb infrastructure validate`	Verify infrastructure still exists in AWS
`orb config show`	Show current configuration
`orb config validate`	Validate configuration
`orb providers list`	List configured providers
`orb system health`	System health check
`orb system health --detailed`	Detailed health check

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

See the CLI Reference for the full flag reference.

REST API

Example API calls. Requires pip install "orb-py[api]" and orb server start (add --foreground for an in-shell variant).

# Get available templates
curl -X GET "http://localhost:8000/api/v1/templates"

# Create machine request
curl -X POST "http://localhost:8000/api/v1/requests" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "my-template", "maxNumber": 5}'

# Check request status
curl -X GET "http://localhost:8000/api/v1/requests/req-12345"

Python SDK

Async-first programmatic access via ORBClient.

from orb import ORBClient as orb

async with orb(provider="aws") as sdk:
    # List templates
    templates = await sdk.list_templates(active_only=True)

    # Request machines
    request = await sdk.request_machines(
        template_id=templates[0]["template_id"],
        count=3
    )

    # Check status
    status = await sdk.get_request_status(request_id=request["created_request_id"])

See the SDK Quickstart for the full guide.

MCP Server (AI Assistant Integration)

ORB provides a Model Context Protocol (MCP) server for AI assistant integration:

# Start MCP server in stdio mode (for AI assistants)
orb mcp serve --stdio

# Start as TCP server (for development/testing)
orb mcp serve --port 3000 --host localhost

Available MCP Tools:

Provider Management: check_provider_health, list_providers, get_provider_config
Template Operations: list_templates, get_template, validate_template
Infrastructure Requests: request_machines, get_request_status, return_machines

Available MCP Resources:

templates:// — Available compute templates
requests:// — Provisioning requests
machines:// — Compute instances
providers:// — Cloud providers

Claude Desktop Configuration:

{
  "mcpServers": {
    "open-resource-broker": {
      "command": "orb",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Integrations

Connect ORB to schedulers and container platforms.

HostFactory Integration

ORB integrates with IBM Spectrum Symphony as a HostFactory provider plugin, providing full API compatibility through shell scripts:

Script	Description
`getAvailableTemplates.sh`	List available compute templates
`requestMachines.sh`	Request new compute instances
`getRequestStatus.sh`	Poll request status
`requestReturnMachines.sh`	Return instances
`getReturnRequests.sh`	Check return request status

Scripts are available for both Linux (bash) and Windows (bat). They are generated automatically by orb init and placed in your config directory.

Key features:

Full HostFactory API compatibility
Automatic CPU and RAM attribute generation from AWS instance types
Native HostFactory output format (camelCase JSON)
Drop-in replacement for existing provider plugins

Example template output:

{
  "templates": [
    {
      "templateId": "t3-medium-template",
      "maxNumber": 5,
      "attributes": {
        "type": ["String", "X86_64"],
        "ncpus": ["Numeric", "2"],
        "nram": ["Numeric", "4096"]
      }
    }
  ]
}

See the HostFactory Guide for full integration details.

Docker Deployment

Run ORB as a containerized service.

git clone https://github.com/finos/open-resource-broker.git
cd open-resource-broker
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d
curl http://localhost:8000/health

Symphony HostFactory on Kubernetes (legacy)

The k8s-legacy module is a Symphony HostFactory custom provider plugin for Kubernetes, predating the modern multi-cloud ORB architecture. It is now bundled with orb-py as an optional install extra rather than as a separate PyPI package.

Install with:

pip install "orb-py[k8s-legacy]"

Confirm the install by listing available templates:

orb k8s-legacy get-available-templates

The plugin is in maintenance mode. A modern Kubernetes provider with native ORB integration is in development; existing deployments remain fully supported.

Upgrading from open-resource-broker? See the migration guide.
Deploying the Symphony HF plugin? See the k8s-legacy deployment guide.

Project

Architecture, development, and documentation.

Architecture

ORB is built on Clean Architecture with Domain-Driven Design (DDD) and CQRS:

Domain layer — pure business logic, no infrastructure dependencies
Application layer — command/query handlers using abstract ports
Infrastructure layer — AWS adapters, DI container, storage strategies
Interface layer — CLI, REST API, MCP server

The provider system uses a Strategy/Registry pattern — each cloud provider (AWS, future providers) registers its own strategy, handlers, and template format. The scheduler system uses the same pattern — HostFactory and Default schedulers are interchangeable strategies behind a common port.

See the Architecture Guide for details.

Development

Set up a local development environment.

git clone https://github.com/finos/open-resource-broker.git
cd open-resource-broker
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run the test suite:

make test

Lint and format:

make lint
make format

See CONTRIBUTING.md for the full development guide.

Documentation & CI

Quick Start
CLI Reference
Configuration Guide
Template Management
Troubleshooting
Architecture
API Reference
Deployment
DeepWiki — AI-generated codebase documentation

Full docs: finos.github.io/open-resource-broker

License

Apache License 2.0 — see LICENSE.

Security

See SECURITY.md for responsible disclosure procedures.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Quick Start

1. Pick a template

2. Request machines

3. Check status

4. Return machines when done

Setup

Standard install (core only — no provider)

Per-provider install

Provider extras matrix

With colored CLI output

With REST API server

With monitoring and observability

Full install (all extras)

Supported resource types

Supported resource types

Interfaces

Integrations

Project

License

Security

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Quick Start

1. Pick a template

2. Request machines

3. Check status

4. Return machines when done

Setup

Standard install (core only — no provider)

Per-provider install

Provider extras matrix

With colored CLI output

With REST API server

With monitoring and observability

Full install (all extras)

Supported resource types

Supported resource types

Interfaces

Integrations

Project

License

Security