Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
122 lines (97 loc) · 3.87 KB

ARCHITECTURE.md

File metadata and controls

122 lines (97 loc) · 3.87 KB
Raw

Ghost Cloud Architecture

Overview

Ghost Cloud is a lightweight private cloud platform for managing VMs on local infrastructure using KVM/Libvirt and Terraform.

Design Principles

  1. Simplicity - Easy to understand and operate
  2. Modularity - Clean separation of concerns
  3. Production-ready - Suitable for real workloads (small scale)
  4. Multi-environment - Separate dev/staging/prod

Technology Stack

  • Virtualization: KVM/QEMU/Libvirt
  • Infrastructure as Code: Terraform
  • VM Configuration: Cloud-init
  • CLI: Bash scripts

Component Architecture

┌─────────────────────────────────────────┐
│         Ghost Cloud CLI                 │
│    (Interactive + Direct Commands)      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│          Terraform                      │
│    (Infrastructure as Code)             │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│         Libvirt/KVM                     │
│    (Virtualization Layer)               │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│      Physical Host (Your Machine)       │
└─────────────────────────────────────────┘

Directory Structure

  • bootstrap/ - One-time setup scripts
  • cloud - Main CLI entry point
  • environments/ - Environment-specific configs
  • terraform/ - Infrastructure definitions
  • terraform/modules/ - Reusable Terraform modules
  • templates/ - VM provisioning scripts
  • scripts/ - Operational scripts
  • data/ - Runtime state and logs

Instance Lifecycle

  1. User runs: ./ghost create web-1 --flavor compute.medium --template nginx
  2. CLI reads flavor from flavors.yaml
  3. CLI calls Terraform with parameters
  4. Terraform creates VM using instance module
  5. Cloud-init runs template script on first boot
  6. VM boots and gets IP via DHCP
  7. Terraform outputs VM details
  8. User can SSH: ./ghost ssh web-1

Network Architecture

  • Default Network: NAT mode (192.168.122.0/24)
  • DHCP: Automatic IP assignment
  • DNS: Local resolution via libvirt
  • SSH: Direct access from host

Security Model

  • SSH key-based authentication
  • No password authentication
  • Sudo access for ubuntu user
  • Firewalls configured per template
  • AppArmor disabled for libvirt (compatibility)

Scaling Considerations

Current design supports:

  • 10-50 VMs comfortably
  • Single physical host
  • 1-5 administrators

To scale beyond:

  • Add load balancer module
  • Implement shared storage (Ceph/NFS)
  • Add multiple compute nodes
  • Centralized monitoring

Design Decisions

Why Terraform?

  • Declarative infrastructure
  • State management
  • Modular and reusable
  • Industry standard

Why KVM/Libvirt?

  • Production-grade hypervisor
  • Same technology as AWS/GCP
  • Native Linux support
  • No licensing costs

Why Cloud-init?

  • Standard VM configuration method
  • Same as AWS EC2
  • Flexible and extensible
  • Well-documented

Limitations

  • Single host (no HA)
  • Manual scaling
  • Basic networking
  • Local state storage