Director — Cluster Control Plane & Web Console

Live ComponentMulti-Node OrchestrationReact Web UI

Director (pilab-cloud/director) is the centralized cluster coordination, scheduling, and control plane daemon in the PiVirt architecture. It coordinates multi-node agent instances, orchestrates intelligent VM placement, schedules distributed asynchronous jobs, and serves the modern React-based Web Management Console.

Architecture Overview

graph TD
    Browser["React Web Console<br/>(Admin / Self-Service UI)"] -->|HTTP/2 / ConnectRPC / WS| Director["PiVirt Director<br/>(Control Plane Daemon)"]
    CLI["pvcli / Automation"] -->|ConnectRPC / mTLS| Director
    
    subgraph Cluster["PiVirt Multi-Node Cluster"]
        Director -->|gRPC / PiTrust mTLS| Agent1["Node 1 (agent + pivirtd)"]
        Director -->|gRPC / PiTrust mTLS| Agent2["Node 2 (agent + pivirtd)"]
        Director -->|gRPC / PiTrust mTLS| Agent3["Node 3 (agent + pivirtd)"]
    end

    Director --> DB[("Cluster State Store<br/>(SQLite / PostgreSQL)")]
    Director --> NATS[("NATS Event Bus<br/>(Real-Time State Streams)")]

Core Capabilities

Cluster-Wide VM Placement

Intelligent scheduling engine that evaluates node capacity (CPU, RAM, NUMA topology, storage pools, network bridges) and places VMs on optimal hypervisor nodes.

React-Based Web UI

Modern, responsive web management console providing graphical dashboards, VM console viewers, real-time telemetry graphs, and interactive topology maps.

Distributed State Sync

Reconciles cluster state across distributed agents using continuous heartbeat mechanisms, health checks, and NATS event streams.

Workflow & Job Orchestration

Coordinates complex distributed tasks including zero-downtime VM live migrations, clustered storage snapshots, and automated node evacuations.

Multi-Tenancy & RBAC

Enforces organizational boundaries, role-based permissions, resource quotas, and project-level isolation.

Real-Time Event Streaming

Pushes live metric and state updates to web clients over WebSockets backed by a high-throughput NATS messaging fabric.

React Web Management Console

Director embeds a production-ready React-based Single-Page Application (SPA) that gives administrators and end-users intuitive graphical control over their virtual infrastructure:

Live Cluster Map: Visual health status, CPU/RAM utilization bars, and VM density per hypervisor node.
Resource Quotas: Visual gauges tracking CPU cores, allocated memory, and pool storage capacity.
Activity Feed: Real-time event log tracking VM lifecycle transitions, user logins, and background job status.

Storage Pool Manager: Inspect iSCSI LUNs, OCFS2 cluster volumes, and local directory pools.
Network Visualizer: Graphical interface for defining Linux bridges, 802.1Q VLAN tags, and VXLAN overlays.
OS Image Catalog: Browse images populated by osinfodb and deploy new instances in seconds.

Director Configuration (`director.yaml`)

Director is configured via /etc/pivirt/director.yaml:

listen_address: "0.0.0.0:5000"
log_level: "info"

# TLS & Security
tls:
  enabled: true
  cert_file: "/etc/pivirt/certs/director.crt"
  key_file: "/etc/pivirt/certs/director.key"
  client_ca_file: "/etc/pivirt/certs/ca.crt"

# State Storage
storage:
  driver: "sqlite" # options: sqlite, postgres
  database: "/var/lib/pivirt/director.db"

# Event Messaging Fabric
messaging:
  nats_url: "nats://127.0.0.1:4222"
  cluster_name: "pivirt-prod"

# Web UI Configuration
web_ui:
  enabled: true
  path: "/ui"
  cors_allowed_origins:
    - "https://pivirt.example.com"

# Authentication & OIDC
auth:
  oidc:
    enabled: true
    issuer_url: "https://auth.pilab.hu/realms/pivirt"
    client_id: "pivirt-director"

Service Management & CLI

# Start Director
sudo systemctl start pivirt-director

# Enable on boot
sudo systemctl enable pivirt-director

# View live service logs
sudo journalctl -u pivirt-director -f

# Start director binary with specified configuration
director --config /etc/pivirt/director.yaml

# Query ConnectRPC health endpoint
curl -k https://localhost:5000/health

# Access React Web Console
open https://localhost:5000/ui

Agent Service Mesh

Learn how Node Agents report telemetry and execute actions dispatched by Director.
View Agent Overview

pvcli Reference

Command-line alternative to the React Web Management Console.
View pvcli Reference

ConnectRPC APIs

Programmatic API endpoints exposed by Director and Agent mesh.
View API Specs

Cluster High Availability

Configure multi-host clustering, Corosync/Pacemaker, and storage replication.
View HA Patterns