OpenStack VM Lifecycle Management API

Status: ✅ COMPLETE & PRODUCTION READY | Tests: 53/53 Passed (90% Coverage) | Build: CLEAN

A REST API for managing OpenStack virtual machine lifecycle operations, built with FastAPI as a proof-of-concept demonstrating API design, Python best practices, and software engineering principles.

Overview

This project provides a comprehensive REST API for managing virtual machine lifecycle in an OpenStack environment. It implements core CRUD operations plus advanced lifecycle management (start, stop, restart, pause, resume) with proper state management and validation.

Note: This is a proof-of-concept implementation using mock OpenStack integration. It demonstrates API design and architecture patterns suitable for production use.

Features

Core Operations

✅ Create VM - Provision new virtual machine instances
✅ List VMs - Retrieve all VMs with pagination and filtering
✅ Get VM Details - Fetch specific VM information
✅ Delete VM - Remove VM instances

Lifecycle Management

✅ Start VM - Boot stopped VMs
✅ Stop VM - Shutdown running or paused VMs
✅ Restart VM - Reboot running VMs
✅ Pause VM - Suspend running VMs to RAM
✅ Resume VM - Restore paused VMs to running state

Additional Features

✅ VM Status Check - Query current VM state
✅ Health Check - API health monitoring endpoint
✅ State Validation - Enforces valid state transitions
✅ Request Validation - Pydantic-based input validation
✅ Auto-generated Documentation - Interactive Swagger/ReDoc UI
✅ Comprehensive Error Handling - Proper HTTP status codes

Architecture

This project follows a layered architecture pattern:

Client → API Layer → Service Layer → Repository Layer → Data Layer

API Layer (app/routes/) - FastAPI endpoints, request/response handling
Service Layer (app/services/) - Business logic and validation
Repository Layer (app/repositories/) - Data access and mock OpenStack integration
Model Layer (app/models/) - Pydantic schemas and data structures

For detailed architecture information, see ARCHITECTURE.md.

Prerequisites

Python 3.11 or higher
pip (Python package manager)
Virtual environment (recommended)

Installation

1. Clone the Repository

git clone <repository-url>
cd intuitive-assessment

2. Create Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment (Optional)

# Copy example environment file
cp .env.example .env

# Edit .env with your settings (if needed)

Running the Application

Start the API Server

# Development mode with auto-reload
uvicorn main:app --reload

# Production mode
uvicorn main:app --host 0.0.0.0 --port 8000

The API will be available at: http://localhost:8000

Verify Installation

# Check health endpoint
curl http://localhost:8000/api/v1/health

Expected response:

{
  "status": "healthy",
  "version": "v1",
  "timestamp": "2026-02-25T10:30:00Z"
}

API Documentation

Interactive Documentation

FastAPI automatically generates interactive API documentation:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Complete API Specification

For detailed endpoint documentation, see API_SPECIFICATION.md.

Usage Examples

Create a VM

curl -X POST http://localhost:8000/api/v1/vms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "flavor": "m1.medium",
    "image": "ubuntu-22.04"
  }'

List All VMs

# List all VMs
curl http://localhost:8000/api/v1/vms

# With pagination
curl http://localhost:8000/api/v1/vms?page=1&page_size=10

# Filter by status
curl http://localhost:8000/api/v1/vms?status=RUNNING

Get VM Details

curl http://localhost:8000/api/v1/vms/{vm_id}

VM Lifecycle Operations

# Start a VM
curl -X POST http://localhost:8000/api/v1/vms/{vm_id}/start

# Stop a VM
curl -X POST http://localhost:8000/api/v1/vms/{vm_id}/stop

# Restart a VM
curl -X POST http://localhost:8000/api/v1/vms/{vm_id}/restart

# Pause a VM
curl -X POST http://localhost:8000/api/v1/vms/{vm_id}/pause

# Resume a VM
curl -X POST http://localhost:8000/api/v1/vms/{vm_id}/resume

Check VM Status

curl http://localhost:8000/api/v1/vms/{vm_id}/status

Delete a VM

curl -X DELETE http://localhost:8000/api/v1/vms/{vm_id}

Complete Workflow Example

# 1. Create a VM
VM_ID=$(curl -s -X POST http://localhost:8000/api/v1/vms \
  -H "Content-Type: application/json" \
  -d '{"name":"test-vm","flavor":"m1.small","image":"ubuntu-22.04"}' \
  | jq -r '.id')

echo "Created VM: $VM_ID"

# 2. Start the VM
curl -X POST http://localhost:8000/api/v1/vms/$VM_ID/start

# 3. Check status
curl http://localhost:8000/api/v1/vms/$VM_ID/status

# 4. Pause the VM
curl -X POST http://localhost:8000/api/v1/vms/$VM_ID/pause

# 5. Resume the VM
curl -X POST http://localhost:8000/api/v1/vms/$VM_ID/resume

# 6. Stop the VM
curl -X POST http://localhost:8000/api/v1/vms/$VM_ID/stop

# 7. Delete the VM
curl -X DELETE http://localhost:8000/api/v1/vms/$VM_ID

Testing

Run All Tests

# Run all tests with coverage
pytest --cov=app --cov-report=html

# Run specific test file
pytest tests/test_vm_service.py

# Run with verbose output
pytest -v

View Coverage Report

# Generate HTML coverage report
pytest --cov=app --cov-report=html

# Open report in browser
open htmlcov/index.html  # macOS
# or
xdg-open htmlcov/index.html  # Linux

Test Structure

tests/test_vm_service.py - Unit tests for business logic
tests/test_vm_routes.py - Integration tests for API endpoints

Coverage achieved: 90% (Target: >80%) ✅

Project Structure

intuitive-assessment/
├── app/
│   ├── __init__.py           # Application initialization
│   ├── models/
│   │   └── vm.py             # Pydantic data models
│   ├── services/
│   │   └── vm_service.py     # Business logic
│   ├── repositories/
│   │   └── vm_repository.py  # Data access layer
│   ├── routes/
│   │   └── vm_routes.py      # API endpoints
│   ├── config.py             # Configuration management
│   └── exceptions.py         # Custom exceptions
├── tests/
│   ├── __init__.py
│   ├── test_vm_service.py    # Service unit tests
│   └── test_vm_routes.py     # API integration tests
├── docs/
│   ├── PROJECT_PLAN.md       # Implementation roadmap
│   ├── ARCHITECTURE.md       # System architecture
│   ├── API_SPECIFICATION.md  # Complete API docs
│   ├── FEATURE_TRACKER.md    # Feature status tracking
│   └── BACKLOG.md            # Future enhancements
├── main.py                   # Application entry point
├── requirements.txt          # Python dependencies
├── .env.example             # Environment variables template
├── .gitignore               # Git ignore rules
└── README.md                # This file

Documentation

Comprehensive documentation is available in the /docs directory:

Document	Description
PROJECT_PLAN.md	Complete project roadmap with timebox breakdown
ARCHITECTURE.md	System architecture and design decisions
API_SPECIFICATION.md	Detailed API endpoint documentation
FEATURE_TRACKER.md	Feature implementation status and checklist
BACKLOG.md	Future enhancements and roadmap

Technology Stack

Component	Technology	Purpose
Web Framework	FastAPI	HTTP routing, validation, auto-docs
Web Server	Uvicorn	ASGI server
Data Validation	Pydantic v2	Request/response validation
Testing	pytest	Unit and integration testing
HTTP Client	httpx	API testing
Configuration	python-dotenv	Environment management
Type Checking	mypy	Static type analysis
Code Formatting	black	Code style consistency

Development

Code Quality

# Format code with black
black app/ tests/

# Type checking with mypy
mypy app/

# Run linter
flake8 app/ tests/

Adding New Features

Define feature in docs/FEATURE_TRACKER.md
Create/update models in app/models/
Implement business logic in app/services/
Add repository methods in app/repositories/
Create API endpoints in app/routes/
Write tests in tests/
Update documentation

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Update documentation
Submit a pull request

VM Flavors

Flavor	vCPUs	RAM	Description
m1.tiny	1	512 MB	Minimal instance
m1.small	1	2 GB	Small workloads
m1.medium	2	4 GB	General purpose
m1.large	4	8 GB	Larger workloads
m1.xlarge	8	16 GB	High-performance

VM Status Values

Status	Description
STOPPED	VM is shut down
RUNNING	VM is active and running
PAUSED	VM is paused (suspended to RAM)
DELETED	VM has been deleted
ERROR	VM is in error state

Future Enhancements

See BACKLOG.md for complete roadmap. Key items include:

Real OpenStack Integration - Replace mock with actual SDK
Database Persistence - PostgreSQL with SQLAlchemy
Authentication & Authorization - OAuth2/JWT implementation
Containerization - Docker and Docker Compose
CI/CD Pipeline - GitHub Actions
Monitoring & Observability - Prometheus, Grafana, Jaeger
Rate Limiting - API throttling
Caching Layer - Redis integration
Message Queue - Async task processing with Celery

Troubleshooting

Port Already in Use

If port 8000 is already in use:

# Use a different port
uvicorn main:app --reload --port 8001

Module Not Found Errors

Ensure virtual environment is activated and dependencies are installed:

source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

Tests Failing

Ensure you're in the project root directory:

# Run from project root
cd /path/to/intuitive-assessment
pytest

License

This project is for assessment purposes.

Contact

For questions or feedback, please open an issue in the repository.

Development Methodology

This project was developed using a "Human-in-the-loop" AI approach. Claude (via PyCharm) was utilized to accelerate the generation of FastAPI boilerplate, Pydantic schemas, and Pytest scaffolding. All architectural decisions, core logic, and SDK integrations were manually reviewed, refactored, and validated to ensure compliance with the PFB requirements.

Built with FastAPI | Version 1.0 | Last Updated: 2026-02-25

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
app		app
docs		docs
tests		tests
.env.example		.env.example
.gitignore		.gitignore
ENDPOINTS_STATUS.md		ENDPOINTS_STATUS.md
FINAL_STATUS.md		FINAL_STATUS.md
README.md		README.md
TEST_RESULTS.md		TEST_RESULTS.md
main.py		main.py
requirements.txt		requirements.txt
test_main.http		test_main.http

ibmgeniuz/openstack-vm-lifecycle-api

Folders and files

Latest commit

History

Repository files navigation