Solti Platforms Collection¶

Automated infrastructure provisioning and management for Proxmox VMs, cloud platforms, and Kubernetes clusters.

Overview¶

Collection Name: jackaltx.solti_platforms

Purpose: Provides enterprise-grade infrastructure automation with:

Proxmox VM Templates: Cloud-init enabled templates from official images
Smart VM Creation: Auto-naming, auto-VMID, and flexible template selection
Cloud Platforms: Linode instance management
Kubernetes: K3s cluster deployment

Quick Links¶

Getting Started - Start here for new users
Proxmox Template Role - Build VM templates
Proxmox VM Role - Create and manage VMs
Management Tools - Script reference

Key Features¶

Smart Automation¶

Auto-naming: VMs named {distribution}-{YYMMDD} (e.g., rocky9-260125)
Auto-VMID: Finds next available VMID in configurable range
Template Discovery: Select templates by distribution, name, or VMID
Minimum Disk Sizing: Ensures minimum size without shrinking
Linked Clones: Fast, space-efficient VM creation

Production Ready¶

UEFI/Secure Boot: Pre-enrolled keys for Rocky Linux
Cloud-init: SSH keys, users, networking pre-configured
Idempotent: Safe to run multiple times
Validation: Fails early if requirements not met
Verification Tasks: Built-in health checks

Enterprise Features¶

Multi-Distribution: Rocky 9/10, Debian 12/13
Consistent Templates: Reproducible across environments
Version Control: Infrastructure-as-code
CI/CD Ready: Automation-friendly workflows

Getting Started¶

Installation¶

ansible-galaxy collection install jackaltx.solti_platforms

5-Minute Quick Start¶

# 1. Build template
./manage-platform.sh -h magic -t rocky9 proxmox_template build

# 2. Create VM (everything auto-generated)
./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9

# 3. Start VM
ssh magic.example.com "sudo qm start 500"

Result: VM rocky9-260125 running at VMID 500 with passwordless SSH access.

See Quick Start Guide for detailed walkthrough.

Documentation Sections¶

Getting Started¶

New to Solti-Platforms? Start here:

Introduction - What is Solti-Platforms and why use it
Quick Start - Get your first VM running in 5 minutes
Architecture Overview - How the components work together

Roles¶

Detailed role documentation:

Proxmox Template - Create cloud-init enabled VM templates
Proxmox VM - Smart VM creation with auto-features
Platform Base - Base platform configuration

Management Tools¶

Management Tools - Scripts for platform operations

Roles Overview¶

proxmox_template¶

Creates cloud-init enabled VM templates from official cloud images.

Features:

Auto-downloads and verifies cloud images
UEFI/OVMF with Secure Boot support
Auto-calculates VMIDs in range 9000-9999
Disk resizing with qemu-img
Template metadata tracking

Supported Distributions:

Distribution	Status
Rocky Linux 9	Production
Rocky Linux 10	Production
Debian 12 (Bookworm)	Production
Debian 13 (Trixie)	Ready

Example:

./manage-platform.sh -h magic -t rocky9 proxmox_template build

Read full documentation →

proxmox_vm¶

Creates VMs from templates with intelligent automation.

Features:

Template Selection: By VMID, name, or distribution
Auto-naming: {distribution}-{YYMMDD} format
Auto-VMID: Next available in configurable range
Smart Disk Sizing: Minimum size without shrinking
Linked Clones: Fast, space-efficient (default)
Cloud-init: SSH keys, users, networking

Example - Minimal:

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9
# Result: rocky9-260125 at VMID 500

Example - Explicit:

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky10 \
  -e vm_name="prod-web-01" \
  -e vm_vmid=600 \
  -e vm_disk_min_size="100G"

Read full documentation →

Use Cases¶

Development Labs¶

Quickly spin up VMs for testing:

vm_template_distribution: rocky9
# Auto-generates: rocky9-260125 at next available VMID

Production Deployments¶

Explicit configuration for production environments:

vm_template_distribution: rocky10
vm_name: "prod-web-01"
vm_vmid: 600
vm_disk_min_size: "100G"
vm_memory: 16384
vm_linked_clone: false

CI/CD Pipelines¶

Automated testing environments:

# Create test VM
./manage-platform.sh -h magic proxmox_vm create -e vm_template_distribution=debian12

# Run tests
ansible-playbook -i vm-inventory.yml test-playbook.yml

# Cleanup
ssh magic "sudo qm destroy 500"

Integration with Other Collections¶

Solti-Platforms integrates seamlessly with:

solti-monitoring: Deploy monitoring agents to created VMs
solti-containers: Run containerized services on platforms
solti-ensemble: Shared infrastructure services

Example workflow:

---
- name: Deploy Monitoring Stack
  hosts: localhost
  tasks:
    # 1. Create VM
    - include_role:
        name: jackaltx.solti_platforms.proxmox_vm
      vars:
        vm_template_distribution: rocky9
        vm_name: "monitor-server"

    # 2. Deploy monitoring (solti-monitoring)
    - include_role:
        name: jackaltx.solti_monitoring.loki
      vars:
        target_host: monitor-server

    # 3. Deploy containers (solti-containers)
    - include_role:
        name: jackaltx.solti_containers.grafana
      vars:
        target_host: monitor-server

Architecture Highlights¶

VMID Allocation¶

Range	Purpose	Example
9000-9999	Templates	9000: rocky9-template
500-8999	VMs (auto)	500: first auto-assigned VM
100-499	VMs (manual)	User-specified VMIDs

Template Selection Priority¶

Explicit VMID (vm_template_vmid: 9000) - Highest priority
Explicit Name (vm_template_name: "custom-template")
Distribution (vm_template_distribution: rocky9) - Most common

Disk Sizing Logic¶

Minimum sizing prevents accidental shrinking:

Template Size	Requested Minimum	Result
32G	20G	32G (no resize)
32G	50G	50G (resize up)
10G	20G	20G (resize up)

See Architecture Overview for details.

Management Scripts¶

manage-platform.sh¶

High-level platform operations:

./manage-platform.sh [-h HOST] <platform> <action> [options]

# Build template
./manage-platform.sh -h magic -t rocky9 proxmox_template build

# Create VM
./manage-platform.sh -h magic proxmox_vm create -e vm_template_distribution=rocky9

# Build all templates
./manage-platform.sh -h magic proxmox_template build --all-distros

platform-exec.sh¶

Task-level execution for debugging:

./platform-exec.sh [-h HOST] <platform> [task] [options]

# Verify template
./platform-exec.sh -h magic proxmox_template verify -e template_distribution=rocky9

# Verify VM
./platform-exec.sh -h magic proxmox_vm verify -e vm_vmid=500

Read full documentation →

Requirements¶

Proxmox VE 8.x
Ansible 2.15+
SSH access with sudo privileges
Internet access (for cloud image downloads)

Example Workflows¶

Complete Development Environment¶

# 1. Build templates (one-time setup)
./manage-platform.sh -h magic proxmox_template build --all-distros

# 2. Create development VMs
./manage-platform.sh -h magic proxmox_vm create -e vm_template_distribution=rocky9
./manage-platform.sh -h magic proxmox_vm create -e vm_template_distribution=debian12

# 3. Start VMs
ssh magic "sudo qm start 500"
ssh magic "sudo qm start 501"

# 4. Deploy applications
ansible-playbook -i dev-inventory.yml deploy-app.yml

# 5. Cleanup when done
ssh magic "sudo qm destroy 500 501"

Production Deployment¶

# 1. Create production VMs with explicit configuration
./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky10 \
  -e vm_name="prod-web-01" \
  -e vm_vmid=600 \
  -e vm_disk_min_size="100G" \
  -e vm_memory=16384 \
  -e vm_cores=8 \
  -e vm_linked_clone=false

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky10 \
  -e vm_name="prod-db-01" \
  -e vm_vmid=700 \
  -e vm_disk_min_size="200G" \
  -e vm_memory=32768 \
  -e vm_cores=16 \
  -e vm_linked_clone=false

# 2. Start VMs
ssh magic "sudo qm start 600 700"

# 3. Deploy production stack
ansible-playbook -i prod-inventory.yml deploy-prod.yml

Best Practices¶

Use Auto-Features for Development
Let auto-naming and auto-VMID handle uniqueness
Fast iteration without manual tracking
Use Explicit Configuration for Production
Specify VM names, VMIDs for predictability
Document VMID allocation
Template Management
Build all templates during initial setup
Keep templates updated with latest cloud images
Don't delete templates with linked VMs
Cloning Strategy
Linked clones for development/testing
Full clones for production
VMID Ranges
Reserve ranges for different purposes (e.g., 600-699: web, 700-799: db)
Document allocation strategy

Troubleshooting¶

Common Issues¶

Template not found:

# Verify template exists
ssh magic "sudo qm list | grep template"

# Build if missing
./manage-platform.sh -h magic -t rocky9 proxmox_template build

VMID conflict:

# Use auto-assignment (omit vm_vmid)
./manage-platform.sh -h magic proxmox_vm create -e vm_template_distribution=rocky9

Cloud-init not working:

# Check cloud-init config
ssh magic "sudo qm cloudinit dump 500 user"

# Verify SSH key
ls -la ~/.ssh/id_ed25519.pub

See role documentation for detailed troubleshooting.

Contributing¶

Issues and pull requests welcome:

GitHub: https://github.com/jackaltx/solti-platforms
Galaxy: https://galaxy.ansible.com/jackaltx/solti_platforms

License¶

MIT-0

Author¶

SOLTI Project - jackaltx