open-hostfactory-plugin

Open Host Factory Plugin

A cloud provider integration plugin for IBM Spectrum Symphony Host Factory, enabling dynamic provisioning of compute resources with a REST API interface and structured architecture implementation.

Overview

The Open Host Factory Plugin provides integration between IBM Spectrum Symphony Host Factory and cloud providers, implementing industry-standard patterns including Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and structured architecture principles.

Currently Supported Providers:

Key Features

Core Functionality

Key Architecture Features

Output Formats and Compatibility

Quick Start

# Clone repository
git clone https://github.com/awslabs/open-hostfactory-plugin.git
cd open-hostfactory-plugin

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start services
docker-compose up -d

# Verify deployment
curl http://localhost:8000/health

Package Installation

# Install from PyPI
pip install open-hostfactory-plugin

# Verify installation
ohfp --version
ohfp --help

For faster dependency resolution and installation, use uv:

# Install uv (if not already installed)
pip install uv

# Clone repository
git clone https://github.com/awslabs/open-hostfactory-plugin.git
cd open-hostfactory-plugin

# Fast development setup with uv
make dev-install-uv

# Or manually with uv
uv pip install -e ".[dev]"

# Generate lock files for reproducible builds
make uv-lock

# Sync with lock files (fastest)
make uv-sync-dev

Traditional Development Setup

# Clone repository
git clone https://github.com/awslabs/open-hostfactory-plugin.git
cd open-hostfactory-plugin

# Traditional setup with pip
make dev-install-pip

# Or manually
pip install -e ".[dev]"

Usage Examples

MCP Server Mode (AI Assistant Integration)

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

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

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

# Configure logging level
ohfp mcp serve --stdio --log-level DEBUG

Available MCP Tools

The MCP server exposes all CLI functionality as tools for AI assistants:

Available MCP Resources

Access domain objects via MCP resource URIs:

AI Assistant Prompts

Pre-built prompts for common infrastructure tasks:

Integration Examples

Claude Desktop Configuration:

{
  "mcpServers": {
    "open-hostfactory": {
      "command": "ohfp",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Python MCP Client:

import asyncio
from mcp import ClientSession, StdioServerParameters

async def use_hostfactory():
    server_params = StdioServerParameters(
        command="ohfp", 
        args=["mcp", "serve", "--stdio"]
    )

    async with ClientSession(server_params) as session:
        # List available tools
        tools = await session.list_tools()

        # Request infrastructure
        result = await session.call_tool(
            "request_machines",
            {"template_id": "EC2FleetInstant", "count": 3}
        )

Command Line Interface

Template Management (Full CRUD Operations)

# List available templates
ohfp templates list
ohfp templates list --long                    # Detailed information
ohfp templates list --format table           # Table format

# Show specific template
ohfp templates show TEMPLATE_ID

# Create new template
ohfp templates create --file template.json
ohfp templates create --file template.yaml --validate-only

# Update existing template
ohfp templates update TEMPLATE_ID --file updated-template.json

# Delete template
ohfp templates delete TEMPLATE_ID
ohfp templates delete TEMPLATE_ID --force    # Force without confirmation

# Validate template configuration
ohfp templates validate --file template.json

# Refresh template cache
ohfp templates refresh
ohfp templates refresh --force               # Force complete refresh

Machine and Request Management

# Request machines
ohfp requests create --template-id my-template --count 5

# Check request status
ohfp requests status --request-id req-12345

# List active machines
ohfp machines list

# Return machines
ohfp requests return --request-id req-12345

Storage Management

ohfp storage list                    # List available storage strategies
ohfp storage show                    # Show current storage configuration
ohfp storage health                  # Check storage health
ohfp storage validate                # Validate storage configuration
ohfp storage test                    # Test storage connectivity
ohfp storage metrics                 # Show storage performance metrics

REST API

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

Architecture

The plugin implements Clean Architecture principles with the following layers:

Design Patterns

Configuration

Environment Configuration

# Provider configuration
PROVIDER_TYPE=aws
AWS_REGION=us-east-1
AWS_PROFILE=default

# API configuration
API_HOST=0.0.0.0
API_PORT=8000

# Storage configuration
STORAGE_TYPE=dynamodb
STORAGE_TABLE_PREFIX=hostfactory

Provider Configuration

# config/providers.yml
providers:
  - name: aws-primary
    type: aws
    config:
      region: us-east-1
      profile: default
      handlers:
        default: ec2_fleet
        spot_fleet:
          enabled: true
        auto_scaling_group:
          enabled: true
    template_defaults:

Development

Prerequisites

Development Setup

# Clone repository
git clone https://github.com/awslabs/open-hostfactory-plugin.git
cd open-hostfactory-plugin

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Install in development mode
pip install -e .

# Run tests
make test

# Format code (Ruff replaces Black + isort)
make format

# Check code quality
make lint

# Run before committing (replaces pre-commit hooks)
make pre-commit

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run integration tests
make test-integration

# Run performance tests
make test-performance

Release Workflow

The project uses semantic-release for automated version management:

# Create a new release (automatic version calculation)
make release

# Test release process (dry run)
make release-dry-run

# Create historical release
make release-historical COMMIT=abc123 VERSION=0.0.5

# Analyze RC readiness
make release-analysis

Release Process:

Releases automatically trigger PyPI publishing, container builds, and documentation deployment.

See Release Management Guide for complete documentation.

Documentation

Comprehensive documentation is available at:

HostFactory Integration

The plugin is designed for seamless integration with IBM Spectrum Symphony Host Factory:

Resource Specifications

The plugin generates HostFactory attributes based on AWS instance types:

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

Supported Instance Types: Common AWS instance types with appropriate CPU and RAM mappings

Support and Contributing

Getting Help

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Security

For security concerns, please see our Security Policy for responsible disclosure procedures.

This site is open source. Improve this page.