Skip to content

CLAUDE.md

Latest commit

 

History

History
176 lines (138 loc) · 6.44 KB

CLAUDE.md

File metadata and controls

176 lines (138 loc) · 6.44 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

BitBuilder Hypervisor is a revolutionary git-ops-native, multi-tenant hypervisor platform built on systemd's advanced virtualization capabilities. This is primarily an architecture specification project with extensive documentation, template definitions, and reference implementations rather than traditional source code.

Core Architecture & Key Concepts

SystemD-Native Design

The entire system leverages systemd ecosystem components:

  • systemd-vmspawn and systemd-nspawn for virtualization
  • systemd-networkd for network management
  • systemd-boot with UKI (Unified Kernel Images)
  • systemd-import-generator for DDI (Discoverable Disk Images)
  • Custom systemd generators for tenant discovery and unit creation

Git-Ops Native Architecture

  • Git repositories serve as single source of truth for all configuration
  • Each tenant has its own dedicated Git repository
  • All infrastructure changes must go through Git commits
  • Automatic rollback capability through Git history

Immutable Infrastructure

  • Host OS completely immutable after boot
  • All changes applied through layered overlays (sysext/confext)
  • Configuration drift eliminated by design

Template System Architecture

Repository Structure

Templates follow strict filesystem hierarchy patterns:

tenant-<name>/
├── metadata.json                 # Required tenant metadata with JSON schema
├── infrastructure/              # Infrastructure manager config
├── network/                     # systemd-networkd configurations
├── machines/                    # VM definitions (systemd-vmspawn)
├── containers/                  # Container definitions (systemd-nspawn)
├── extensions/                  # Extension images
│   ├── sysext/                  # System extensions (/usr, /opt only)
│   └── confext/                 # Config extensions (/etc only)
├── services/                    # Portable service definitions
└── scripts/                     # Lifecycle hooks

Linux Userspace API (UAPI) Compliance

Strict adherence to UAPI specifications:

  • Discoverable Partitions Specification (DPS) for partition layout
  • Discoverable Disk Image (DDI) for system images
  • Unified Kernel Image (UKI) for secure boot
  • Boot Loader Specification (BLS) for boot configuration
  • Configuration Files Specification for directory hierarchy

Key Documentation Files

Essential Reading (Priority Order)

  1. README.md - Main project overview and feature descriptions
  2. .github/copilot-instructions.md - Comprehensive AI agent instructions
  3. STACK.md - Template system and implementation details
  4. specs/ARCHITECTURE.md - System architecture and design patterns
  5. specs/DESIGN.md - Technical implementation details

Template and Configuration Examples

  • Templates are defined in documentation but runtime locations are:
    • /usr/lib/bitbuilder/templates/ - System-wide templates
    • /var/lib/tenants/<id>/ - Per-tenant runtime data
    • /etc/systemd/system/ - systemd unit templates
    • /usr/lib/systemd/system-generators/ - Custom generators

Build and Development Commands

This is primarily a specification project without traditional build processes, but key operations include:

Template Validation

# Validate filesystem hierarchy compliance
./scripts/validate-template.sh <template-directory>

# Validate tenant metadata schema
./scripts/validate-metadata.sh metadata.json

SystemD Operations

# Generate systemd units for tenant
systemctl enable --now tenant@<tenant-id>.service

# Reload systemd after generator changes
systemctl daemon-reload

# Check tenant status
systemctl status tenant@<tenant-id>
systemctl status tenant-infra@<tenant-id>
systemctl status tenant-network@<tenant-id>

Extension Management

# Create sysext extension image
mksquashfs extension-root extension-name.raw

# Mount extension for testing
systemd-sysext refresh

# List active extensions
systemd-sysext status

Git-Ops Operations

# System repository operations
git -C /var/lib/bitbuilder/system pull
systemctl reload tenant-manager

# Tenant repository sync
git -C /var/lib/tenants/<tenant>/config.git pull
systemctl restart tenant@<tenant>

Security and Isolation Model

Multi-Layer Isolation

Each tenant operates with multiple security boundaries:

  • Hardware: VT-x/AMD-V virtualization, UEFI Secure Boot
  • Kernel: Complete namespace isolation (PID, NET, MNT, UTS, IPC, USER)
  • SystemD: Capability dropping, seccomp filters, resource limits
  • Network: Dedicated bridges, VLANs, network namespaces

Communication Patterns

  • Varlink: Primary IPC protocol for service communication
  • SO_PEERCRED: Unix socket authentication
  • systemd-creds: Secure credential management

Working with Templates

When creating or modifying templates:

  1. Always include proper metadata.json with schema validation
  2. Ensure filesystem hierarchy compliance (see validation scripts)
  3. Extension images must include proper extension-release files
  4. Test systemd unit generation and dependency resolution
  5. Verify mount overlay functionality works correctly

Tenant Lifecycle

Provisioning Flow

  1. Create tenant Git repository with metadata.json
  2. systemd generators discover new tenant at boot
  3. Clone tenant repository to /var/lib/tenants/<id>/config.git/
  4. Generate systemd units dynamically
  5. Apply sysext/confext overlays
  6. Launch systemd-vmspawn or systemd-nspawn instance
  7. Execute provisioning scripts

Configuration Changes

  • All changes through Git commits
  • Automatic validation and schema checking
  • Hot-reload for config changes, restart for structural changes
  • Rollback through Git revert

Important File Locations

Runtime Directories

  • /var/lib/tenants/<id>/ - Per-tenant data
  • /var/lib/bitbuilder/ - System configuration cache
  • /usr/lib/extensions/ - System-wide extension images
  • /etc/voa/ and /usr/share/voa/ - Verification of OS Artifacts

Configuration Templates

  • /etc/systemd/network/ - Network configuration templates
  • /usr/lib/systemd/system/ - SystemD unit templates
  • /usr/lib/systemd/system-generators/ - Custom generators

This project represents a paradigm shift toward declarative, immutable infrastructure management through Git-Ops and systemd's advanced virtualization capabilities.