Skip to content

PROJECT_PLAN.md

Latest commit

 

History

History
229 lines (179 loc) · 7.32 KB

PROJECT_PLAN.md

File metadata and controls

229 lines (179 loc) · 7.32 KB

OpenStack VM Lifecycle Management API - Project Plan

Project Overview

Project Name: OpenStack VM Lifecycle Management REST API Objective: Design and implement REST API endpoints for managing OpenStack VM lifecycle operations Timebox: 2-4 hours Type: Proof-of-Concept / Technical Assessment

Scope

In Scope

  • REST API endpoints for VM lifecycle operations (CRUD + lifecycle management)
  • Mock OpenStack integration for demonstration purposes
  • Comprehensive documentation and architecture design
  • Unit and integration tests
  • Best practices implementation (error handling, logging, validation)
  • API versioning strategy
  • Working prototype with FastAPI

Out of Scope (See BACKLOG.md)

  • Real OpenStack cloud integration
  • Authentication and authorization
  • Database persistence
  • Containerization (Docker)
  • CI/CD pipeline
  • Production deployment configuration
  • Rate limiting and API throttling
  • Monitoring and observability tools

Implementation Roadmap

Phase 1: Foundation & Documentation (45 minutes)

1.1 Project Structure Setup (10 minutes)

  • Create directory structure (/app, /tests, /docs)
  • Set up Python virtual environment
  • Configure dependencies in requirements.txt
  • Create .gitignore for Python project
  • Create .env.example for configuration template

1.2 Documentation Creation (35 minutes)

  • PROJECT_PLAN.md - This document (10 min)
  • ARCHITECTURE.md - System design and decisions (10 min)
  • API_SPECIFICATION.md - Complete API documentation (10 min)
  • FEATURE_TRACKER.md - Implementation checklist (5 min)
  • README.md - Project overview and setup (7 min)
  • BACKLOG.md - Future enhancements (3 min)

Phase 2: Core Architecture (45 minutes)

2.1 Application Models (10 minutes)

  • Create app/models/vm.py
    • VMCreateRequest schema
    • VMResponse schema
    • VMStatus enum
    • VMListResponse schema

2.2 Repository Layer (15 minutes)

  • Create app/repositories/vm_repository.py
    • Mock in-memory VM storage
    • CRUD operations
    • Lifecycle state management
    • UUID generation

2.3 Service Layer (10 minutes)

  • Create app/services/vm_service.py
    • Business logic for VM operations
    • Validation rules
    • State transition logic

2.4 Configuration & Utilities (10 minutes)

  • Create app/config.py - Environment configuration
  • Create app/exceptions.py - Custom exception classes
  • Create app/__init__.py - Module initialization

Phase 3: API Implementation (60 minutes)

3.1 Core CRUD Endpoints (25 minutes)

  • Create app/routes/vm_routes.py
    • POST /api/v1/vms - Create new VM (8 min)
    • GET /api/v1/vms - List all VMs with pagination (7 min)
    • GET /api/v1/vms/{vm_id} - Get VM details (5 min)
    • DELETE /api/v1/vms/{vm_id} - Delete VM (5 min)

3.2 Lifecycle Management Endpoints (25 minutes)

  • POST /api/v1/vms/{vm_id}/start - Start VM (5 min)
  • POST /api/v1/vms/{vm_id}/stop - Stop VM (5 min)
  • POST /api/v1/vms/{vm_id}/restart - Restart VM (5 min)
  • POST /api/v1/vms/{vm_id}/pause - Pause VM (5 min)
  • POST /api/v1/vms/{vm_id}/resume - Resume VM (5 min)

3.3 Status & Health Endpoints (10 minutes)

  • GET /api/v1/vms/{vm_id}/status - Get VM status (5 min)
  • GET /api/v1/health - API health check (5 min)

Phase 4: Testing & Quality (45 minutes)

4.1 Unit Tests (20 minutes)

  • Create tests/test_vm_service.py
    • Test VM creation logic
    • Test lifecycle transitions
    • Test validation rules

4.2 Integration Tests (20 minutes)

  • Create tests/test_vm_routes.py
    • Test all API endpoints
    • Test error scenarios
    • Test edge cases

4.3 Code Quality (5 minutes)

  • Add type hints throughout
  • Add docstrings
  • Format code with black

Phase 5: Polish & Finalization (15 minutes)

  • Update main.py with final application structure
  • Verify all documentation is complete
  • Test API with sample requests
  • Final git commit with clean history
  • Verify README instructions work

Time Allocation Summary

Phase Duration Percentage
Foundation & Documentation 45 min 22.5%
Core Architecture 45 min 22.5%
API Implementation 60 min 30%
Testing & Quality 45 min 22.5%
Polish & Finalization 15 min 7.5%
Total 210 min 100%
Equivalent 3.5 hours (within timebox)

Technology Stack

Core Framework

  • FastAPI - Modern, fast web framework with automatic API documentation
  • Uvicorn - ASGI server for running FastAPI
  • Python 3.11+ - Latest Python features and performance

Data Validation

  • Pydantic v2 - Data validation and settings management

Testing

  • pytest - Testing framework
  • httpx - Async HTTP client for testing FastAPI

Development Tools

  • python-dotenv - Environment variable management
  • black - Code formatter
  • mypy - Static type checker

OpenStack Integration (Mock)

  • Custom mock implementation (real OpenStack SDK would be openstacksdk)

Risk Assessment

High Risk

  • Time Constraint - 2-4 hour timebox is aggressive
    • Mitigation: Focus on core features, mock OpenStack integration

Medium Risk

  • OpenStack Complexity - Real OpenStack integration requires infrastructure
    • Mitigation: Use mock repository pattern for demonstration

Low Risk

  • API Design - Well-understood REST patterns
  • Technology Choice - FastAPI is well-documented and stable

Success Criteria

Must Have (MVP)

  • ✅ All core CRUD endpoints functional
  • ✅ All lifecycle management endpoints functional
  • ✅ Comprehensive documentation (6 documents)
  • ✅ Unit and integration tests with >80% coverage
  • ✅ Working prototype that can be run locally
  • ✅ Clear README with setup instructions

Should Have

  • ✅ Proper error handling with meaningful messages
  • ✅ Request/response validation
  • ✅ API versioning strategy
  • ✅ Structured logging
  • ✅ Type hints throughout

Nice to Have

  • Code formatting with black
  • Static type checking with mypy
  • OpenAPI documentation (auto-generated by FastAPI)

Key Design Decisions

  1. Mock vs Real OpenStack: Using mock implementation to avoid infrastructure requirements
  2. In-Memory Storage: No database for simplicity and timebox constraints
  3. Layered Architecture: Separation of concerns (routes → services → repositories)
  4. FastAPI Choice: Modern framework with excellent async support and auto-docs
  5. API Versioning: URL-based versioning (/api/v1/) for future compatibility

Deliverables Checklist

  • Public GitHub repository with complete code
  • README.md with setup and usage instructions
  • Complete set of documentation (6 files)
  • Working API prototype
  • Unit and integration tests
  • requirements.txt with pinned versions
  • .gitignore for Python
  • Example API requests (test_main.http or similar)

Future Roadmap (Beyond Timebox)

See BACKLOG.md for detailed future enhancements including:

  • Real OpenStack SDK integration
  • Database persistence (PostgreSQL)
  • Authentication & authorization (OAuth2/JWT)
  • Containerization (Docker + Docker Compose)
  • CI/CD pipeline (GitHub Actions)
  • Production readiness features

Last Updated: 2026-02-25 Status: In Progress Version: 1.0