API Reference¶
The Open Host Factory Plugin provides a command-line interface that integrates with IBM Spectrum Symphony Host Factory. This reference covers all available commands and their usage.
Command Line Interface¶
Basic Usage¶
# Direct Python execution
python run.py <command> [options]
# Via shell scripts (Symphony integration)
./scripts/<command>.sh [input]
Input Methods¶
The application supports multiple input methods:
- Command line arguments (for simple commands)
- JSON data via --data flag
- JSON file via --file flag
- Standard input (when using shell scripts)
Global Options¶
Option | Description | Example |
---|---|---|
--data |
JSON string input | --data '{"template_id": "test"}' |
--file |
Path to JSON file | --file input.json |
--all |
Apply to all items | --all |
--long |
Include detailed information | --long |
--clean |
Clean up resources | --clean |
--config |
Configuration file path | --config config/prod.json |
--log-level |
Logging level | --log-level DEBUG |
Available Commands¶
getAvailableTemplates¶
Get list of available VM templates.
Usage¶
# Basic usage
python run.py getAvailableTemplates
# Via shell script
./scripts/getAvailableTemplates.sh
# With filter
python run.py getAvailableTemplates --provider-api RunInstances
Input Format¶
Output Format¶
{
"templates": [
{
"template_id": "SymphonyOnDemand",
"provider_api": "RunInstances",
"max_number": 5,
"attributes": {
"type": ["String", "X86_64"],
"ncores": ["Numeric", "2"],
"ncpus": ["Numeric", "1"],
"nram": ["Numeric", "4096"]
},
"vm_type": "t2.micro",
"image_id": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64"
}
]
}
requestMachines¶
Request new virtual machines based on a template.
Usage¶
# With command line arguments (optional)
python run.py requestMachines [template_id] [machine_count]
# With JSON data
python run.py requestMachines --data '{"template_id": "test", "machine_count": 3}'
# With JSON file
python run.py requestMachines --file request.json
# Via shell script
echo '{"template_id": "test", "machine_count": 3}' | ./scripts/requestMachines.sh
Input Format¶
{
"template_id": "SymphonyOnDemand",
"machine_count": 3,
"tags": {
"Environment": "test",
"Project": "symphony"
},
"priority": 5
}
Output Format¶
{
"request_id": "req-12345678-1234-1234-1234-123456789012",
"template_id": "SymphonyOnDemand",
"machine_count": 3,
"status": "PENDING",
"created_at": "2025-06-30T12:00:00Z",
"machines": []
}
getRequestStatus¶
Get the status of a machine request.
Usage¶
# With request ID
python run.py getRequestStatus --request-id req-12345678-1234-1234-1234-123456789012
# With JSON data
python run.py getRequestStatus --data '{"request_id": "req-123..."}'
# Via shell script
echo '{"request_id": "req-123..."}' | ./scripts/getRequestStatus.sh
Input Format¶
Output Format¶
{
"request_id": "req-12345678-1234-1234-1234-123456789012",
"template_id": "SymphonyOnDemand",
"machine_count": 3,
"status": "COMPLETED",
"created_at": "2025-06-30T12:00:00Z",
"updated_at": "2025-06-30T12:05:00Z",
"completed_at": "2025-06-30T12:05:00Z",
"machines": [
{
"machine_id": "machine-i-1234567890abcdef0",
"name": "symphony-instance-1",
"status": "RUNNING",
"instance_type": "t2.micro",
"private_ip": "10.0.1.100",
"public_ip": null,
"provider_instance_id": "i-1234567890abcdef0"
}
]
}
getReturnRequests¶
Get list of return requests (machines to be terminated).
Usage¶
# Get all return requests
python run.py getReturnRequests
# Get active requests only
python run.py getReturnRequests --active-only
# Get return requests only
python run.py getReturnRequests --return-only
# Via shell script
./scripts/getReturnRequests.sh
Input Format¶
Output Format¶
{
"return_requests": [
{
"request_id": "ret-12345678-1234-1234-1234-123456789012",
"machine_ids": ["machine-i-1234567890abcdef0"],
"status": "PENDING",
"created_at": "2025-06-30T12:00:00Z"
}
]
}
requestReturnMachines¶
Request machines to be returned (terminated).
Usage Methods¶
Primary Method - Positional Arguments:
# Machine IDs as command line arguments (recommended for simple cases)
python run.py requestReturnMachines machine-id-1 machine-id-2 machine-id-3
Alternative Method - JSON Data:
# JSON data via --data flag (recommended for complex cases or scripting)
python run.py requestReturnMachines --data '{"machine_ids": ["machine-id-1", "machine-id-2"]}'
# JSON data via file (recommended for large lists)
echo '{"machine_ids": ["machine-id-1", "machine-id-2"]}' > return_request.json
python run.py requestReturnMachines --file return_request.json
Symphony Integration Method:
# Via shell script (used by Symphony Host Factory)
echo '{"machine_ids": ["machine-id-1"]}' | ./scripts/requestReturnMachines.sh
When to Use Each Method¶
- Positional Arguments: Best for simple cases with few machine IDs
- JSON Data: Best for scripting, automation, or large lists of machines
- Shell Scripts: Used by Symphony Host Factory integration
Input Format¶
Output Format¶
{
"request_id": "ret-12345678-1234-1234-1234-123456789012",
"machine_ids": [
"machine-i-1234567890abcdef0",
"machine-i-0987654321fedcba0"
],
"status": "PENDING",
"created_at": "2025-06-30T12:00:00Z"
}
migrateRepository¶
Migrate data between storage strategies.
Usage¶
# Basic migration
python run.py migrateRepository --source-type json --target-type sqlite
# With options
python run.py migrateRepository \
--source-type json \
--target-type sqlite \
--batch-size 100 \
--create-backup \
--validate-after
Options¶
Option | Description | Default |
---|---|---|
--source-type |
Source storage type (json, sqlite, dynamodb) | Required |
--target-type |
Target storage type (json, sqlite, dynamodb) | Required |
--batch-size |
Records per batch | 100 |
--create-backup |
Create backup before migration | true |
--validate-after |
Validate after migration | true |
--cleanup-source |
Remove source data after migration | false |
Output Format¶
{
"migration_id": "migration-12345678",
"source_type": "json",
"target_type": "sqlite",
"status": "COMPLETED",
"records_migrated": 1500,
"duration_seconds": 45.2,
"backup_created": "/path/to/backup.json"
}
Shell Script Integration¶
Symphony Integration Flow¶
graph LR
Symphony[Symphony Host Factory] --> Script[Shell Script]
Script --> Wrapper[invoke_provider.sh]
Wrapper --> Python[run.py]
Python --> AWS[AWS Services]
AWS --> Python
Python --> Wrapper
Wrapper --> Script
Script --> Symphony
Shell Script Usage¶
Input via Standard Input¶
# Symphony passes JSON data via stdin
echo '{"template_id": "test", "machine_count": 2}' | ./scripts/requestMachines.sh
Environment Variables¶
# Set Host Factory environment variables
export HF_PROVIDER_CONFDIR=/etc/hostfactory
export HF_PROVIDER_WORKDIR=/var/lib/hostfactory
export HF_PROVIDER_LOGDIR=/var/log/hostfactory
# Execute script
./scripts/getAvailableTemplates.sh
Available Shell Scripts¶
Script | Purpose | Symphony Command |
---|---|---|
getAvailableTemplates.sh |
Get available templates | getAvailableTemplates |
requestMachines.sh |
Request new machines | requestMachines |
getRequestStatus.sh |
Check request status | getRequestStatus |
getReturnRequests.sh |
Get return requests | getReturnRequests |
requestReturnMachines.sh |
Return machines | requestReturnMachines |
Error Handling¶
Error Response Format¶
{
"error": "Template not found",
"error_code": "TEMPLATE_NOT_FOUND",
"timestamp": "2025-06-30T12:00:00Z",
"request_id": "req-12345678-1234-1234-1234-123456789012",
"details": {
"template_id": "invalid-template"
}
}
Common Error Codes¶
Error Code | Description | Resolution |
---|---|---|
TEMPLATE_NOT_FOUND |
Template doesn't exist | Check template ID and configuration |
INVALID_REQUEST |
Invalid request format | Validate JSON input format |
PROVIDER_ERROR |
Cloud provider error | Check AWS credentials and permissions |
CONFIGURATION_ERROR |
Configuration issue | Validate configuration file |
RESOURCE_LIMIT_EXCEEDED |
Resource limits exceeded | Check template max_number setting |
Exit Codes¶
Exit Code | Description |
---|---|
0 | Success |
1 | General error |
2 | Configuration error |
3 | Provider error |
4 | Validation error |
Examples¶
Complete Request Flow¶
# 1. Get available templates
python run.py getAvailableTemplates
# 2. Request machines
python run.py requestMachines --data '{
"template_id": "SymphonyOnDemand",
"machine_count": 2
}'
# 3. Check request status
python run.py getRequestStatus --request-id req-12345678-1234-1234-1234-123456789012
# 4. Return machines when done
python run.py requestReturnMachines --data '{
"machine_ids": ["machine-i-1234567890abcdef0"]
}'
Symphony Integration Example¶
# Symphony calls shell scripts with JSON input
echo '{
"template_id": "SymphonyOnDemand",
"machine_count": 3,
"tags": {
"Environment": "production",
"Project": "symphony"
}
}' | ./scripts/requestMachines.sh
Batch Operations¶
# Process multiple requests
for template in template1 template2 template3; do
echo "{\"template_id\": \"$template\", \"machine_count\": 1}" | \
python run.py requestMachines --data '{}'
done
Next Steps¶
- Templates: Learn about template configuration
- Requests: Understand request management
- Configuration: Configure the application
- Deployment: Deploy in production environments