VM Tracker Architecture
System Overview
VM Tracker consists of two main components that work together to monitor and manage virtual machines:
- API Server: Central management and monitoring service
- Client: Lightweight agent running on each VM
High-Level Architecture
+-------------+ +-------------+ +-------------+
| VM #1 | | VM #2 | | VM #3 |
| | | | | |
| +--------+ | | +--------+ | | +--------+ |
| | Client | | | | Client | | | | Client | |
| +---+----+ | | +---+----+ | | +---+----+ |
+------+------+ +------+------+ +------+------+
| | |
| POST /api/register (Heartbeat) |
+-------------------+-------------------+
|
v
+-----------------+
| API Server |
| |
| +-----------+ |
| | REST API | |
| +-----------+ |
| |
| +-----------+ |
| | Web UI | |
| +-----------+ |
| |
| +-----------+ |
| | Storage | |
| +-----------+ |
+-----------------+
Component Details
API Server Components
+--------------------------------------------------+
| API Server |
| |
| +--------------------------------------------+ |
| | HTTP Router | |
| | - POST /api/register | |
| | - GET /api/vms | |
| | - DELETE /api/vms/{hostname} | |
| | - GET /install.sh | |
| | - GET / (Web UI) | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | VM Registry (In-Memory) | |
| | - Hostname | |
| | - IP Address | |
| | - Interface | |
| | - Last Seen (Timestamp) | |
| | - Status (online/offline) | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | Background Services | |
| | - Status Checker (every 10s) | |
| | - Cleanup Service (every 60s) | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | Web UI (HTML) | |
| | - VM List Table | |
| | - Auto-refresh (every 5s) | |
| | - Delete VM functionality | |
| +--------------------------------------------+ |
+--------------------------------------------------+
Client Components
+--------------------------------------------------+
| VM Tracker Client |
| |
| +--------------------------------------------+ |
| | Hostname Detection | |
| | - os.Hostname() | |
| | - Fallback: "unknown" | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | IP Address Detection | |
| | - Read network interfaces | |
| | - Filter by interface name | |
| | - Extract IPv4 address | |
| | - Ignore loopback addresses | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | Registration Logic | |
| | - Initial registration with retries | |
| | - Periodic updates (configurable) | |
| | - HTTP POST to API Server | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | Signal Handling | |
| | - SIGTERM / SIGINT | |
| | - Graceful shutdown | |
| +--------------------------------------------+ |
+--------------------------------------------------+
Communication Flow
Initial Registration
Client API Server
| |
| 1. Detect Hostname |
| 2. Detect IP Address |
| |
| 3. POST /api/register |
+----------------------------------------->|
| { |
| "hostname": "vm1", |
| "ip_address": "10.0.0.12", | 4. Store VM info
| "interface": "eth0" | 5. Update last_seen
| } | 6. Set status: online
| |
| 7. Response: 200 OK |
|<-----------------------------------------+
| { |
| "status": "ok", |
| "message": "VM registered" |
| } |
| |
Periodic Heartbeat
Client API Server
| |
| Every 30s (configurable): |
| |
| POST /api/register |
+----------------------------------------->|
| (same payload as initial) | Update last_seen
| | Set status: online
| Response: 200 OK |
|<-----------------------------------------+
| |
Status Monitoring
API Server (Background Service)
|
| Every 10 seconds:
|
| For each VM:
| if (now - last_seen) > 20 seconds:
| status = "offline"
| else:
| status = "online"
|
Cleanup Process
API Server (Background Service)
|
| Every 60 seconds:
|
| For each VM:
| if (now - last_seen) > 300 seconds:
| Remove VM from registry
|
Data Flow Diagram
+--------+ 1. Detect +--------+
| System | ----------------> | Client |
| Info | (hostname/IP) +--------+
+--------+ |
| 2. Send
| Registration
v
+------------------+
| API Server |
| |
| 3. Store/Update |
| VM Info |
+------------------+
|
+--------------+--------------+
| |
4. Background 5. Serve Web UI
Services & API
| |
v v
+--------------+ +----------------+
| Status Check | | Web Browser / |
| Cleanup | | API Client |
+--------------+ +----------------+
Network Diagram
+------------------------+
| Network: eth0 |
| 10.0.0.0/24 |
+------------------------+
|
|
+----+----+----+----+----+
| | | | | |
| | | | | |
VM1 VM2 VM3 VM4 API User
.12 .13 .14 .15 .196 Browser
| | | | |
+----+----+----+----+
|
v
Registration
& Heartbeats
|
v
+----------+
| API |
| Server |
| :8080 |
+----------+
Deployment Scenarios
Scenario 1: Docker Compose
+--------------------------------------------------+
| Docker Host |
| |
| +--------------------+ +-------------------+ |
| | API Container | | Client Container | |
| | | | | |
| | Port: 8080 | | --network host | |
| +--------------------+ +-------------------+ |
| | | |
| +------------------------+ |
| | |
+----------------------|---------------------------+
|
Host Network
Scenario 2: Kubernetes
+--------------------------------------------------+
| Kubernetes Cluster |
| |
| +--------------------------------------------+ |
| | API Server Deployment | |
| | - Replicas: 1 | |
| | - Service: LoadBalancer/NodePort | |
| | - Port: 8080 | |
| +--------------------------------------------+ |
| |
| +--------------------------------------------+ |
| | Client DaemonSet | |
| | - Runs on every node | |
| | - hostNetwork: true | |
| | - Reports node IP addresses | |
| +--------------------------------------------+ |
+--------------------------------------------------+
Scenario 3: Binary Installation
+-------------+ +-------------+ +-------------+
| VM 1 | | VM 2 | | VM 3 |
| | | | | |
| Client | | Client | | API Server |
| (systemd) | | (systemd) | | (systemd) |
| | | | | |
| 10.0.0.12 | | 10.0.0.13 | | 10.0.0.196 |
+------+------+ +------+------+ +------+------+
| | |
+-------------------+-------------------+
|
Network: eth0
Technology Stack
+--------------------------------------------------+
| Technology Stack |
+--------------------------------------------------+
| |
| Programming Language: |
| - Go 1.21+ |
| |
| API Server: |
| - net/http (Standard Library) |
| - encoding/json |
| - sync.RWMutex (Thread-safe storage) |
| |
| Client: |
| - net (Network interface detection) |
| - os (Hostname detection) |
| - os/signal (Graceful shutdown) |
| - time.Ticker (Periodic updates) |
| |
| Data Format: |
| - JSON for API communication |
| - In-memory storage (map[string]*VMInfo) |
| |
| Web UI: |
| - Embedded HTML template |
| - Vanilla JavaScript (auto-refresh) |
| - No external dependencies |
| |
+--------------------------------------------------+
Scalability Considerations
Current Architecture (In-Memory)
Single API Server Instance
|
+-- In-Memory Storage (map)
| - Fast read/write
| - Limited to single instance
| - Data lost on restart
|
+-- No persistence layer
Future Enhancements (Persistent Storage)
Multiple API Server Instances
|
+-- Load Balancer
| |
| +-- API Server 1
| +-- API Server 2
| +-- API Server 3
|
+-- Shared Database (PostgreSQL/MySQL/Redis)
|
+-- Persistent VM data
+-- Supports horizontal scaling
+-- Data survives restarts
Security Considerations
Current Implementation
Client -----------------> API Server
| |
| HTTP (unencrypted) |
| No authentication |
| |
Recommended Production Setup
Client -----------------> API Server
| |
| HTTPS (TLS) |
| API Key / mTLS |
| Firewall rules |
| |
Monitoring & Observability
+--------------------------------------------------+
| Monitoring Points |
+--------------------------------------------------+
| |
| API Server: |
| - Number of registered VMs |
| - Online/Offline VM count |
| - Request rate (registrations/sec) |
| - Response times |
| - Error rates |
| |
| Client: |
| - Registration success/failure rate |
| - Network connectivity status |
| - Retry attempts |
| - Uptime |
| |
| System: |
| - CPU usage |
| - Memory usage |
| - Network bandwidth |
| |
+--------------------------------------------------+
Configuration Parameters
API Server
| Parameter |
Default |
Description |
PORT |
8080 |
HTTP server port |
| Status check interval |
10s |
How often to check VM status |
| Cleanup interval |
60s |
How often to clean up old VMs |
| Offline threshold |
20s |
Mark VM offline after this time |
| Cleanup threshold |
300s |
Remove VM after this time |
Client
| Parameter |
Flag |
Default |
Description |
| API URL |
-api |
http://10.0.2.196:8080 |
API Server URL |
| Interface |
-interface |
eth0 |
Network interface to monitor |
| Update interval |
-interval |
30s |
Heartbeat frequency |
| Retry delay |
-retry |
5s |
Delay between retries |
| Verbose logging |
-verbose |
false |
Enable detailed logs |
Error Handling
Client Error Flow
Start
|
v
Get Hostname
|
+-- Success --> Continue
|
+-- Failure --> Use "unknown"
|
v
Get IP Address
|
+-- Success --> Continue
|
+-- Failure --> Retry (5s delay)
|
+-- Max 3 retries
|
+-- Exit if all fail
v
Send Registration
|
+-- Success --> Wait interval, repeat
|
+-- Failure --> Log error, continue
| (retry on next interval)
API Server Error Flow
Receive Request
|
v
Validate JSON
|
+-- Valid --> Continue
|
+-- Invalid --> Return 400 Bad Request
|
v
Validate Required Fields
|
+-- Valid --> Continue
|
+-- Missing --> Return 400 Bad Request
|
v
Store/Update VM
|
v
Return 200 OK