Proxmox Virtual Machines

VM Requests

Request and manage virtual machines through ARROW’s integrated VM provisioning system powered by Proxmox Virtual Environment.

Overview

ARROW’s VM request system provides a streamlined workflow for provisioning virtual machines:

• Self-Service Requests: Submit VM requests through the ARROW console
• Automated Provisioning: Requests are automatically processed and deployed to Proxmox infrastructure
• Real-Time Monitoring: Track build progress with live WebSocket logs and status updates
• VPN Integration: Automatic NetBird VPN setup for secure VM access
• Lifecycle Management: Manage VM usage periods and completion with automated cleanup

VM Request Process

Submitting a Request

To request a VM, navigate to Device Requests in the ARROW console and select + New Request with device type Virtual Machine.

Required Information:

Field	Description
VM Name	Unique identifier for the virtual machine
Client	Associated client organization
Request Period	Start and end dates for VM usage
VM Type	Target format (QCOW2 for Proxmox deployment)
Images	Base image(s) to include in the VM
Consultants	Team members who will access the VM

Request-to-Deployment Workflow

The following sequence diagram illustrates the complete workflow from request submission to VM deployment:

sequenceDiagram
    participant User
    participant Console
    participant Backend as PocketBase Backend
    participant B2 as B2 Storage
    participant GitHub as GitHub Actions
    participant Builder as Build Server
    participant Proxmox as Proxmox VE
    participant NetBird

    User->>Console: Submit VM Request
    Console->>Backend: POST /api/device_requests
    Backend->>Backend: Validate request & Generate VM serial (VM-XXXXX)
    Backend->>Backend: Create device_settings record
    Backend->>Backend: Create vm_build_tasks record (status: queued)

    Backend->>GitHub: POST webhook (event_type: vm_imaging_request)
    GitHub->>Builder: Trigger GitHub Actions runner
    Builder->>Backend: GET /api/vm-build/tasks (poll for work)
    Backend-->>Builder: Return BuildTask with configs

    Builder->>B2: Download base image
    Builder->>Builder: Apply customizations via Ansible
    Builder->>Backend: POST /api/vm-build/task-status (progress updates)
    Builder->>Backend: WebSocket logs via /api/vm-build/logs/stream

    Builder->>Proxmox: Deploy customized VM
    Proxmox->>NetBird: Register VM as VPN peer
    NetBird->>Backend: Confirm peer registration

    Builder->>Backend: POST /api/vm-build/task-status (status: completed)
    Backend->>Backend: Update device_request status to "fulfilled"
    Backend->>Console: Real-time status update
    Console->>User: Display VM access details

Request Status Tracking

Monitor your request status in the Device Requests page:

Status	Description	Backend State
Pending	Request submitted, awaiting approval	device_request.status = "pending"
Approved	Request approved, build queued	vm_build_tasks.status = "queued"
Imaging	VM image being customized	vm_build_tasks.status = "building"
Provisioning	VM being deployed to Proxmox	vm_build_tasks.status = "building"
Configuring	Post-deployment configuration in progress	vm_build_tasks.status = "building"
Fulfilled	VM ready for use	device_request.status = "fulfilled"
Failed	Build encountered an error	vm_build_tasks.status = "failed"

Build Task Status Transitions

stateDiagram-v2
    [*] --> queued: Task Created
    queued --> started: Builder Claims Task
    started --> building: Build Begins
    building --> completed: Success
    building --> failed: Error Occurred
    building --> cancelling: Cancel Requested
    cancelling --> cancelled: Cleanup Done
    failed --> queued: Rebuild Triggered
    completed --> [*]
    cancelled --> [*]

VM Provisioning

Automated Deployment

Once approved, your VM request enters the automated provisioning pipeline:

1. Build Task Creation: A build task is queued in the system
2. GitHub Actions Trigger: The imaging workflow is triggered via webhook
3. Image Customization: Base image is customized with organization settings
4. Software Installation: Selected applications installed via Ansible
5. Proxmox Deployment: Customized image deployed as a VM
6. VPN Registration: VM registered with NetBird for secure access
7. Access Configuration: Consultant access groups configured

Resource Allocation

VMs are provisioned with resources based on the selected configuration:

• CPU: Virtual CPU cores allocated from Proxmox cluster
• Memory: RAM allocation based on workload requirements
• Storage: Disk space provisioned from shared storage pools
• Network: Virtual network interfaces with VPN connectivity

VM Access

VPN Setup

After your VM is provisioned, access is provided through the NetBird VPN:

1. Install NetBird Client: Download from the VPN management page
2. Configure Management URL: Set your organization’s VPN endpoint
3. Authenticate: Log in using your organization’s identity provider
4. Connect: Your VPN client will automatically connect to assigned VMs

Connection Details

Once the VM is ready, connection information is available in the console:

• VPN IP Address: Internal VPN address for the VM
• Hostname: NetBird hostname for DNS resolution
• Access Credentials: Initial login credentials (if applicable)

Access Control

VM access is restricted to assigned consultants:

• Only consultants listed on the device request can access the VM
• Access is enforced through NetBird group policies
• One-way access policies prevent VMs from connecting back to user workstations

For more details on access control, see Network Access Control.

VM Monitoring

Build Progress

Track VM provisioning progress through the console:

• Status Updates: Real-time status changes displayed in the request list
• Build Logs: View detailed logs through the build monitoring interface
• Progress Indicators: Visual progress bars show completion percentage
• Error Notifications: Immediate notification if build fails

Build Logs

Access build logs to troubleshoot issues or verify configuration:

1. Navigate to your device request in the console
2. Click View Build Logs to open the log viewer
3. Logs stream in real-time during active builds
4. Historical logs remain available after completion

For detailed build monitoring information, see Build Monitoring.

VM Lifecycle

Extending Request Period

If your project requires additional time:

1. Navigate to the Devices page
2. Click the […] menu for your VM
3. Select Edit Request Details
4. Update the end date as needed

VM Completion

When your engagement ends, complete the VM to release resources:

1. Ensure all data is backed up or exported
2. Navigate to the device in the console
3. Initiate the completion process

Completion Actions:

• VM is shut down and removed from Proxmox
• NetBird peer is deleted from the VPN
• Access control groups are cleaned up
• Resources are returned to the pool

Early Completion

You can complete a VM before the scheduled end date:

1. Confirm you no longer need VM access
2. Submit completion request through the console
3. The system processes cleanup automatically

Technical Details

Device Settings

When a VM is provisioned, the following settings are stored in the device_settings collection:

Field	Description	Example
nb_device_name	NetBird VPN device name for peer identification	arrow-vm-001
build_job_info	JSON object containing build status, progress, and server info	See below
serial_number	Unique VM identifier (format: VM-XXXXX)	VM-12345
arrow_pw	Generated password for arrow user	Auto-generated
root_pw	Generated root password	Auto-generated
api_key	API key for builder authentication	Auto-generated

Build Job Info Structure:

{
  "status": "completed",
  "progress": 100,
  "stage": "deployment",
  "stage_name": "VM Ready",
  "current_step": "Completed",
  "build_server": "builder-1",
  "build_time_seconds": 1245,
  "download_url": "https://..."
}

VM Device Types

ARROW supports two VM deployment configurations:

Type	Code	VPN Group	Description
Proxmox VM	pvm	pvm	Deployed on ARROW’s managed Proxmox cluster
External VM	vm	vm	Deployed on client infrastructure (VMware, VirtualBox, QEMU)

Build Task Record

Each VM build creates a vm_build_tasks record:

Field	Description
task_id	Unique task identifier with timestamp
device_settings	Reference to device_settings record
organization	Owning organization
status	Current build status
progress	Percentage complete (0-100)
assigned_server	Build server handling the task
build_time	Duration in seconds
error_message	Details if build failed

Completion API

The VM completion endpoint (POST /api/vm/complete) performs automated cleanup:

flowchart TD
    A[POST /api/vm/complete] --> B[Authenticate User]
    B --> C[Find VM by serial_number]
    C --> D[Verify Organization Match]
    D --> E[Get device_request]
    E --> F[Retrieve device_settings]
    F --> G[Get NetBird Integration Config]
    G --> H[Create NetBirdClient]
    H --> I[Fetch All VPN Peers]
    I --> J[Match Peer by nb_device_name]
    J --> K{Peer Found?}
    K -->|Yes| L[Delete VPN Peer]
    K -->|No| M[Log Warning - Continue]
    L --> N[Delete device-{id} Group]
    M --> N
    N --> O[Remove Users from consultants-{id} Group]
    O --> P[Delete Access Policies]
    P --> Q[Update device_request status = complete]
    Q --> R[Return Success Response]

Backend Implementation

The VM completion workflow is handled by backend/api/vm_complete/handlers.go:

• Authentication: Requires valid user session
• Organization Isolation: Users can only complete VMs in their organization
• Graceful Cleanup: Continues even if NetBird operations fail
• Audit Trail: All actions logged via app.Logger()

Best Practices

Before Requesting

• Plan Resources: Estimate CPU, memory, and storage needs
• Select Images: Choose appropriate base images for your use case
• Assign Consultants: Ensure all team members are listed
• Set Dates: Allow sufficient time for the engagement

During Usage

• Monitor Resources: Check VM performance through available tools
• Maintain Access: Keep VPN client updated and connected
• Backup Data: Regularly export important data
• Report Issues: Contact support for any VM problems

At Completion

• Export Data: Save all necessary data before completion
• Notify Team: Inform assigned consultants of pending completion
• Complete Promptly: Release resources when no longer needed

Related Documentation

• ARROW Virtual Machines - VM system architecture overview
• VM Imaging Workflow - Image creation and customization process
• Build Monitoring - Real-time build tracking and logs
• VPN Management - VPN configuration and access control
• Network Access Control - Access policies and permissions
• Device Requests - General device request process