Arvandor

Production-grade infrastructure-as-code for running services on Proxmox with enterprise HA patterns.

Overview

Arvandor provides a complete infrastructure stack:

Terraform - VM provisioning on Proxmox
Ansible - Configuration management
Nebula - Encrypted overlay network
Vault - Secrets management (3-node Raft cluster)
PostgreSQL - Database (3-node Patroni + etcd)
Valkey - Cache/queue (3-node Sentinel)
Garage - S3-compatible storage (3-node cluster)

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         Proxmox Host                                    │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Management  │  │  Services   │  │    Data     │  │  Workloads  │    │
│  │ 1000-1999   │  │ 2000-2999   │  │ 3000-3999   │  │ 4000-4999   │    │
│  │             │  │             │  │             │  │             │    │
│  │ DNS, Caddy  │  │ Vault       │  │ PostgreSQL  │  │ Your Apps   │    │
│  │ Lighthouse  │  │ Gitea       │  │ Valkey      │  │             │    │
│  │             │  │             │  │ Garage      │  │             │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
│         │                │                │                │           │
│         └────────────────┴────────────────┴────────────────┘           │
│                                  │                                      │
│                         Nebula Overlay (10.10.10.0/24)                 │
└─────────────────────────────────────────────────────────────────────────┘

Quick Start

1. Prerequisites

Proxmox VE host
Arch Linux VM template (VMID 9000)
Terraform, Ansible installed locally
Nebula binary for certificate generation

2. Configure

# Clone repository
git clone <repo-url> arvandor
cd arvandor

# Configure Terraform
cp terraform/terraform.tfvars.example terraform/terraform.tfvars
vim terraform/terraform.tfvars

# Configure Ansible
cp ansible/inventory.ini.example ansible/inventory.ini
vim ansible/inventory.ini

# Generate Nebula CA
cd nebula
nebula-cert ca -name "Arvandor CA"

3. Provision

# Create VMs
cd terraform
terraform init
terraform plan
terraform apply

# Bootstrap VMs (in order)
cd ../ansible
ansible-playbook -i inventory.ini playbooks/bootstrap.yml
ansible-playbook -i inventory.ini playbooks/security.yml
ansible-playbook -i inventory.ini playbooks/nebula.yml

4. Deploy Services

# DNS server
ansible-playbook -i inventory.ini playbooks/dns.yml

# PostgreSQL HA cluster
ansible-playbook -i inventory.ini playbooks/postgres-ha.yml

# Valkey Sentinel
ansible-playbook -i inventory.ini playbooks/valkey-sentinel.yml

# Garage S3
ansible-playbook -i inventory.ini playbooks/garage.yml

Directory Structure

arvandor/
├── terraform/           # VM provisioning
│   ├── modules/vm/      # Reusable VM module
│   ├── management.tf    # DNS, Caddy
│   ├── services.tf      # Vault, Gitea
│   └── data.tf          # PostgreSQL, Valkey, Garage
├── ansible/             # Configuration management
│   ├── playbooks/       # Core playbooks
│   ├── templates/       # Jinja2 templates
│   └── vault/           # Ansible Vault secrets
├── nebula/              # Overlay network
│   └── configs/         # Per-host certificates
├── network/             # Host networking
└── docs/                # Documentation

Network Design

Two-Network Model

Network	CIDR	Purpose
Bridge (vmbr1)	192.168.100.0/24	Provisioning only
Nebula	10.10.10.0/24	All application traffic

VMs only accept traffic from the Proxmox host (for Ansible) and the Nebula overlay. This provides isolation even if someone gains bridge network access.

Security Groups (Nebula)

Group	Purpose
`admin`	Full access (your devices)
`infrastructure`	Core services
`projects`	Application workloads
`games`	Isolated game servers

Documentation

Getting Started - Detailed setup guide
Architecture - Design decisions
Provisioning Guide - Adding new VMs

License

MIT

5.3 KiB Raw Blame History