Documentation · Platform Architecture

Architecture & Administration Guide

This guide explains how VirtStack is built and how to operate it day to day. It assumes familiarity with SLES, libvirt and KVM.

#operating-model #architecture #data-flows #host-admin #vm-ops #storage #ha #limits

Operating model: Day 0, Day 1, Day 2

Phase	Who	Tooling	Tasks
Day 0 · Foundation	Platform engineers	Standard SUSE tooling (YaST, zypper, crmsh)	Servers, SLES 15 SP7 + KVM, networks/bonds/bridges, SAN/NAS, Pacemaker/Corosync/SBD, hardening
Day 1 · Onboarding	Platform engineers, VirtStack-assisted	VirtStack	Enroll hosts, discover hardware & NUMA, register pools & networks, build golden templates, set placement defaults, adopt existing VMs
Day 2 · Operations	L1–L3 operations	VirtStack	Lifecycle and console, snapshots, clones, placement, HA visibility, maintenance mode, metrics, audit

VirtStack does not build the Pacemaker cluster (use SUSE HA tooling such as crmsh); it discovers and visualises it. It does not replace Hawk2, which remains the SUSE HA cluster-resource UI.

Architecture overview & 4 design principles

1. Outbound-only from hosts

The agent initiates connection. Control plane cannot reach a host that has not dialled in.

2. No central host credentials

No root passwords or SSH keys stored centrally. Each agent authenticates with its own certificate.

3. Local execution

Operations run through libvirt's local UNIX socket on host, not over remote virsh or SSH.

4. libvirt source of truth

VMs are standard libvirt domains. Existing VMs are discovered; VirtStack can be cleanly uninstalled.

Component	Runs on	Responsibility
Web UI	Control plane	Browser console, dashboards, noVNC client
API	Control plane	Authenticated operations, validation, audit logging
Gateway	Control plane	Terminates agent mTLS tunnels; multiplexes control, events and console streams
Placement engine	Control plane	Filter + score hosts; NUMA pinning recommendations; decision log
Audit log	Control plane	Append-only record of administrative actions
Agent	Each hypervisor	Enrolls, maintains tunnel, executes libvirt RPC locally, streams events and metrics
libvirt / QEMU / KVM	Each hypervisor	SUSE-packaged virtualization stack; VirtStack does not replace it

Host administration & agent commands

Agent Systemd Commands

Agent service management on SLES

sudo systemctl status virtstack-agent
sudo journalctl -u virtstack-agent --since "1 hour ago"
sudo systemctl restart virtstack-agent   # safe: running VMs are not affected

Standalone Host Patch Procedure

zypper patch on SLES

# after shutting down or relocating VMs
sudo zypper patch
sudo zypper needs-rebooting   # reboot if it reports that one is required

Storage & Online Volume Expansion

Discovers Directory, NFS, and LVM pools. Online volume expansion presents new size to guest immediately.

Inside Linux Guest Partition & Filesystem Expansion

sudo growpart /dev/vda 2
sudo xfs_growfs /            # XFS
# or: sudo resize2fs /dev/vda2   # ext4

Current limits

Area	Today	Roadmap
Migration	Wizard with capacity & compatibility validation	Live migration; storage copy without shared storage
Scale	Single gateway	Pooled gateways, 50+ hypervisors
Access control	Administrator accounts; restrict console via network VPN	RBAC, SSO, MFA
Host maintenance	Maintenance mode + manual moves via wizard	One-click evacuation
VMware import	Convert with virt-v2v outside VirtStack	Not on committed roadmap

Ready to inspect security & compliance?

Security & Compliance →Request trial