Skip to content

Latest commit

 

History

History
330 lines (233 loc) · 13.4 KB

INDEX.md

File metadata and controls

330 lines (233 loc) · 13.4 KB

Lightstack Documentation Index

Complete guide to Lightstack - OpenStack 3 Kubernetes-style

This documentation covers everything from getting started to production deployment, architecture deep-dives, and API compatibility.


📖 Table of Contents

🚀 Getting Started

Start here if you're new to Lightstack or want to quickly evaluate it.

  1. README - Project overview and quick links
  2. QUICKSTART - Get Lightstack running in 5 minutes
  3. UNIFIED_DEPLOYMENT - Deploy Lightstack + Horizon in one command
  4. QUICK_REFERENCE - Command cheat sheet

Recommended Path: README → QUICKSTART → UNIFIED_DEPLOYMENT


🛠️ Installation & Deployment

Choose your deployment strategy based on your use case.

Development & Testing

Demonstration & POC

  • SINGLE_NODE_DEPLOYMENT ⭐ NEW
    • Single Linux host with real KVM hypervisor
    • Full Horizon dashboard with noVNC console
    • Perfect for demos showing actual VM creation
    • Hardware requirements and setup guide
    • 6 demonstration scenarios included

Production

  • SCALING ⭐ NEW
    • Multi-node production architecture (3-node to 10+ nodes)
    • High availability (HAProxy + Keepalived + Patroni)
    • Shared storage with Ceph (RBD pools)
    • VXLAN multi-node networking
    • Load balancing, monitoring, backup, disaster recovery
    • Complete production operations guide
  • UPGRADING - Upgrade an existing install (incl. nodes installed under the previous product name)

Kubernetes

  • KUBERNETES_DEPLOYMENT ⭐ NEW
    • Manual manifests and Helm chart guide
    • ConfigMap, Secret, Deployment, Service, Ingress
    • Health checks, scaling, monitoring
    • Production considerations

Decision Matrix:

Use Case Guide Features Hardware
Quick eval QUICKSTART Stub mode, no KVM Laptop (any OS)
Development DOCKER_DEPLOYMENT Containers, easy setup 8 GB RAM
Demo/POC SINGLE_NODE_DEPLOYMENT Real KVM, full features 16-32 GB RAM (Linux)
Production SCALING HA, multi-node, Ceph 8+ nodes
Kubernetes KUBERNETES_DEPLOYMENT Single binary, all services K8s cluster

🌐 Horizon Dashboard Integration

Lightstack serves the OpenStack APIs Horizon consumes, and the dashboard is usable for resource management — networks, volumes and instances can be created from the UI in stub and real mode (#532, #533). The open UI gaps, starting with the noVNC console, are listed in the report (findings F1–F18).

  • Horizon Compatibility Report ⭐ NEW - Browser-level verification: dashboard usable for resource management after #532/#533 (F1–F18)
  • HORIZON_FULL_COMPATIBILITY_REPORT - SUPERSEDED (API-endpoint coverage only; see the report above for UI verdicts)
    • API endpoint coverage (342/330), microversions, auth flow
    • Per-page API dependency matrix
    • Performance benchmarks and optimization
    • Troubleshooting guide
  • HORIZON_INTEGRATION - Integration overview and architecture
  • HORIZON_DEPLOYMENT - Deploy Horizon separately to existing Lightstack
  • HORIZON_SETUP - Configuration and troubleshooting

Related: See UNIFIED_DEPLOYMENT.md for combined Lightstack + Horizon deployment.


🔧 Configuration

Detailed configuration guides for all Lightstack modes and backends.

Core Configuration

Service Modes

Backend Configuration


🏗️ Architecture & API

Understand lightstack's design, implementation, and OpenStack compatibility.

Architecture

API Compatibility

  • BLUEPRINT ⭐ AUTHORITATIVE - Lightstack ↔ OpenStack compatibility blueprint: service map, ~330 functional operations (counting rule stated), per-service matrix, storage backends, sync-architecture trade-offs, Terraform coverage, sci-in-a-box surface, and known gaps. Pinned to OpenStack 2025.2 (Flamingo).
  • compatibility/OPENSTACK_COMPATIBILITY_REPORT - Deep per-endpoint analysis + contract-test results (BLUEPRINT's appendix)
  • API - Quick-start auth / catalog examples
  • API_COVERAGE_REPORT - ⚠️ Superseded: older "104% (342/330)" count; see BLUEPRINT for the reconciled figure
  • WHATS_LEFT - Optional enterprise features not implemented

Architecture Decisions

Key Stats: Lightstack implements ~330 functional operations across the 5 core OpenStack services (Keystone, Nova, Neutron, Cinder, Glance). See BLUEPRINT for the counting rule and per-service breakdown.


🔍 Advanced Topics

Deep dives into specific features and experimental implementations.


🧪 Testing & Quality

Test reports, strategies, and code quality reviews.

Code Review

Contract Test Reports

Code Reviews

Compatibility


📋 v0.7.0 Planning


🤝 Contributing & Development

  • CONTRIBUTING - Development guidelines and contribution process

❓ Troubleshooting & Support

For additional help:


📊 Dashboard Analysis

Analysis of dashboard compatibility and integration options.

  • ELEKTRA_INTEGRATION_ANALYSIS ⭐ NEW
    • Comprehensive analysis of SAP Elektra dashboard
    • Verdict: Not compatible with Lightstack (requires SAP infrastructure)
    • Detailed comparison with Horizon
    • Recommendation: Continue with Horizon (usable for resource management; open gaps in the compatibility report)

🗺️ Recommended Learning Paths

Path 1: Quick Evaluation (30 minutes)

  1. QUICKSTART - Get Lightstack running
  2. QUICK_REFERENCE - Try basic commands
  3. API_COVERAGE_REPORT - Understand capabilities

Path 2: Development Setup (2 hours)

  1. INSTALLATION - Understand installation options
  2. DOCKER_DEPLOYMENT - Set up dev environment
  3. CONFIGURATION - Configure services
  4. STORAGE_MODES - Choose storage backend
  5. NETWORKING_MODES - Configure networking

Path 3: Production Deployment (1-2 weeks)

  1. ARCHITECTURE - Understand system design
  2. SINGLE_NODE_DEPLOYMENT - Test on single node first
  3. SCALING - Deploy multi-node cluster
  4. OPERATIONS - Learn operational tasks
  5. TROUBLESHOOTING - Handle common issues

Path 4: Horizon Dashboard Integration (1 day)

  1. HORIZON_INTEGRATION - Understand integration
  2. UNIFIED_DEPLOYMENT - Deploy Lightstack + Horizon together
  3. HORIZON_DEPLOYMENT - Or deploy Horizon separately
  4. HORIZON_SETUP - Configure and troubleshoot

Path 5: Advanced Features (Ongoing)

  1. VXLAN_IMPLEMENTATION - Multi-node networking
  2. L3_ROUTER_IMPLEMENTATION - Routing details
  3. S3_CONFIGURATION - Object storage backend
  4. EBPF_STATUS - Experimental features
  5. CONTRIBUTING - Contribute improvements

📚 Documentation Categories

By Complexity

Beginner (Start Here):

  • QUICKSTART, README, QUICK_REFERENCE, UNIFIED_DEPLOYMENT

Intermediate (Deployment):

  • INSTALLATION, DOCKER_DEPLOYMENT, SINGLE_NODE_DEPLOYMENT, HORIZON_DEPLOYMENT, CONFIGURATION

Advanced (Production):

  • SCALING, OPERATIONS, VXLAN_IMPLEMENTATION, L3_ROUTER_IMPLEMENTATION, REAL_LIBVIRT_MODE

Expert (Deep Dives):

  • ARCHITECTURE, EBPF_STATUS, API, CONTRIBUTING

By Topic

Deployment:

  • QUICKSTART, INSTALLATION, DOCKER_DEPLOYMENT, UNIFIED_DEPLOYMENT, SINGLE_NODE_DEPLOYMENT, SCALING

Dashboard:

  • HORIZON_INTEGRATION, HORIZON_DEPLOYMENT, HORIZON_SETUP, ELEKTRA_INTEGRATION_ANALYSIS

Configuration:

  • CONFIGURATION, STORAGE_MODES, NETWORKING_MODES, S3_CONFIGURATION, REAL_LIBVIRT_MODE

Networking:

  • NETWORKING_MODES, VXLAN_IMPLEMENTATION, L3_ROUTER_IMPLEMENTATION

API & Compatibility:

  • API_COVERAGE_REPORT, API, WHATS_LEFT, ARCHITECTURE

Operations & Support:

  • OPERATIONS, TROUBLESHOOTING, QUICK_REFERENCE

🆕 Recently Added (April 2026)

  1. KUBERNETES_DEPLOYMENT - Kubernetes deployment with manifests and Helm guide
  2. v0.6.0 Code Quality Release - 39 commits fixing 32 codebase review findings
  3. testing/ - Organized test reports directory
  4. review/ - Codebase review report directory

📝 Document Status Legend

  • ⭐ NEW - Recently added or significantly updated
  • 🚀 RECOMMENDED - Start here for most users
  • 🔧 TECHNICAL - Requires advanced knowledge
  • 🧪 EXPERIMENTAL - Features in development

🔗 External Resources

OpenStack Documentation:

lightstack Project:


📧 Getting Help

Documentation Issues:

Technical Support:

Contributing:

  • Read CONTRIBUTING
  • Submit documentation improvements via pull requests
  • Help improve guides based on your deployment experience

Last Updated: April 2026 Total Documentation Files: 40 Coverage: Getting Started, Installation, Configuration, Operations, Architecture, API Reference, Testing, Code Quality