open-resource-broker

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

open-resource-broker

★ 18 Open GitHub ↗

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.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![FINOS - Incubating](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-incubating.svg)](https://community.finos.org/docs/governance/Software-Projects/stages/incubating)

<p align="center">
  <strong>Unified API for orchestrating and provisioning compute capacity</strong>
</p>

---

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, MCP server, or native SDKs in six languages (Python, Go, TypeScript, Java, Kotlin, .NET).

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

**Provider support:**
- **AWS** — EC2 RunInstances, EC2Fleet, SpotFleet, Auto Scaling Groups, Lambda MicroVMs
- **Kubernetes** — Pod, Deployment, StatefulSet, Job (`pip install "orb-py[k8s]"`; see [Kubernetes provider docs](docs/root/providers/k8s/index.md))
- **Custom** — extensible via [provider registry](docs/root/developer_guide/architecture.md) and the [`orb.providers` entry-point group](docs/root/providers/k8s/plugin-authoring.md)

**Scheduler support:**
- **HostFactory** — runs as an [IBM Spectrum Symphony provider plugin](#hostfactory-integration)
- **Standalone** — direct usage without an external scheduler

![ORB](https://raw.githubusercontent.com/finos/open-resource-broker/main/ORB.gif)

## Quick Start

```bash
pip install orb-py
orb init
orb templates generate
```

### 1. Pick a template

```bash
orb templates list
```

### 2. Request machines

```bash
orb machines request <template-id> 3
```

### 3. Check status

```bash
orb requests status <request-id>
```

### 4. Return machines when done

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

### 5. Check the return status

`machines return` prints a return-request id; check it the same way as step 3:

```bash
orb requests status <return-request-id>
```

## Setup

Get ORB installed and configured for your environment.

<details>
<summary>Installation</summary>

### Standard install (core only — no provider)

```bash
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

```bash
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

```bash
pip install "orb-py[cli]"
```

### With REST API server

```bash
pip install "orb-py[api]"
```

### With monitoring and observability

```bash
pip install "orb-py[monitoring]"
```

### Full install (all extras)

```bash
pip install "orb-py[all]"
```

Requires Python 3.10+.

</details>

<details>
<summary>Configuration</summary>

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

```bash
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](docs/root/user_guide/configuration.md) for path resolution details, environment variables, and REST API server setup.

</details>

<details>
<summary>AWS Provider Setup</summary>

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

```bash
# 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 |
| `MicroVM` | Isolated Lambda MicroVM sandboxes for untrusted code |

See the [AWS Provider Guide](docs/root/user_guide/configuration.md) for required IAM permissions and SpotFleet service-linked role setup. See the [MicroVM Provider Guide](docs/root/providers/aws/microvm.md) for Lambda MicroVM setup.

</details>

<details>
<summary>Kubernetes Provider Setup</summary>

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.

```bash
# 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](docs/root/providers/k8s/discovery.md) 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`](docs/root/providers/k8s/rbac.yaml); see the [Kubernetes Provider Guide](docs/root/providers/k8s/index.md) for full setup.

</details>

## Interfaces

ORB provides multiple ways to interact with your infrastructure — a CLI, a REST API, an MCP server, and native SDKs in six languages.

<details>
<summary>CLI Reference</summary>

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](docs/root/cli/cli-reference.md) for the full flag reference.

</details>

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

```bash
# 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"
```

</details>

<details>
<summary>SDKs (Python, Go, TypeScript, Java, Kotlin, .NET)</summary>

Native client libraries in six languages. Python is async-first and in-process; the other five drive a managed `orb` server over a local socket, so they share one OpenAPI contract and behave identically.

| Language | Install | Entry point |
|---|---|---|
| Python | `pip install orb-py` | `orb.ORBClient` |
| Go | `go get github.com/finos/open-resource-broker/sdk/go` | `orb.Client` |
| TypeScript / Node | `npm install @finos/open-resource-broker` | `OrbClient` |
| Java | `org.finos.openresourcebroker:open-resource-broker-java` | `OrbClient` |
| Kotlin | `org.finos.openresourcebroker:open-resource-broker-kotlin` | `OrbClient` |
| .NET / C# | `dotnet add package FINOS.OpenResourceBroker` | `OrbClient` |

```python
from orb import ORBClient as orb

async with orb(provider="aws") as sdk:
    templates = await sdk.list_templates(active_only=True)
    request = await sdk.request_machines(
        template_id=templates["templates"][0]["template_id"],
        count=3,
    )
    status = await sdk.get_request_status(request_id=request["request_id"])
```

See the [SDK documentation](docs/root/sdk/index.md) for per-language install and usage guides, the [Python SDK Quickstart](docs/root/sdk/quickstart.md), and [Generate Your Own SDK](docs/root/sdk/generating-sdks.md).

</details>

<details>
<summary>MCP Server (AI Assistant Integration)</summary>

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

```bash
# 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:**
```json
{
  "mcpServers": {
    "open-resource-broker": {
      "command": "orb",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}
```

</details>

## Integrations

Connect ORB to schedulers and container platforms.

<details>
<summary>HostFactory Integration</summary>

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:

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

See the [HostFactory Guide](docs/root/hostfactory/integration_guide.md) for full integration details.

</details>

<details>
<summary>Docker Deployment</summary>

Run ORB as a containerized service.

```bash
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
```

</details>

<details>
<summary>Symphony HostFactory on Kubernetes (legacy)</summary>

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:

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

Confirm the install by listing available templates:

```bash
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](docs/root/operational/from-open-resource-broker.md).
- **Deploying the Symphony HF plugin?** See the [k8s-legacy deployment guide](k8s-legacy/README.md).

</details>

## Project

Architecture, development, and documentation.

<details>
<summary>Architecture</summary>

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](docs/root/developer_guide/architecture.md) for details.

</details>

<details>
<summary>Development</summary>

Set up a local development environment.

```bash
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:

```bash
make test
```

Lint and format:

```bash
make lint
make format
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.

</details>

<details>
<summary>Documentation & CI</summary>

- [Quick Start](docs/root/getting_started/quick_start.md)
- [CLI Reference](docs/root/cli/cli-reference.md)
- [Configuration Guide](docs/root/user_guide/configuration.md)
- [Template Management](docs/root/user_guide/templates.md)
- [Troubleshooting](docs/root/user_guide/troubleshooting.md)
- [Architecture](docs/root/developer_guide/architecture.md)
- [API Reference](docs/root/api/readme.md)
- [Deployment](docs/root/deployment/readme.md)
- [DeepWiki](https://deepwiki.com/finos/open-resource-broker) — AI-generated codebase documentation

Full docs: [finos.github.io/open-resource-broker](https://finos.github.io/open-resource-broker/)

</details>

---

## License

Apache License 2.0 — see [LICENSE](LICENSE).

## Security

See [SECURITY.md](SECURITY.md) for responsible disclosure procedures.

open-resource-broker

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README