arvandor/docs/provisioning-guide.md

Provisioning Guide

Step-by-step guide for adding new VMs to the infrastructure.

Adding a New VM

1. Choose VMID and IP

Select a VMID based on the VM's purpose:

Purpose	VMID Range	Example
Management	1000-1999	1003
Services	2000-2999	2004
Data	3000-3999	3012
Workloads	4000-4999	4056
Monitoring	5000-5999	5001

IP is derived from VMID:

• Bridge: 192.168.100.XX
• Nebula: 10.10.10.XX

Where XX is the last 2 digits of VMID.

2. Add to Terraform

Edit the appropriate .tf file:

module "myapp" {
  source       = "./modules/vm"
  name         = "myapp"
  vmid         = 4056
  node_name    = var.proxmox_node
  bridge_ip    = "192.168.100.56"
  gateway      = var.gateway
  datastore_id = var.datastore_id
  clone_vmid   = var.template_vmid
  cores        = 2
  memory       = 4096
  disk_size    = 50
  username     = var.username
  password     = var.password
  ssh_key_path = var.ssh_key_path
}

Apply:

cd terraform
terraform plan
terraform apply

3. Generate Nebula Certificate

cd nebula

nebula-cert sign -ca-crt ca.crt -ca-key ca.key \
  -name "myapp" \
  -networks "10.10.10.56/24" \
  -groups "projects" \
  -out-crt configs/4056/myapp/myapp.crt \
  -out-key configs/4056/myapp/myapp.key

Choose the appropriate group:

• infrastructure - Core services
• projects - Applications needing infrastructure access
• games - Isolated workloads

4. Add to Ansible Inventory

Edit ansible/inventory.ini:

[projects]
myapp ansible_host=192.168.100.56 nebula_ip=10.10.10.56 vmid=4056

[docker]
myapp

5. Run Bootstrap Playbooks

cd ansible

# Update packages
ansible-playbook -i inventory.ini playbooks/bootstrap.yml --limit "myapp"

# Configure firewall
ansible-playbook -i inventory.ini playbooks/security.yml --limit "myapp"

# Join Nebula
ansible-playbook -i inventory.ini playbooks/nebula.yml --limit "myapp"

# Configure DNS client
ansible-playbook -i inventory.ini playbooks/dns-client.yml --limit "myapp"

# Install Docker (if needed)
ansible-playbook -i inventory.ini playbooks/docker.yml --limit "myapp"

6. Update DNS (Optional)

If you want a .nebula hostname, re-run the DNS playbook:

ansible-playbook -i inventory.ini playbooks/dns.yml

7. Verify

# Test SSH via Nebula
ssh admin@10.10.10.56

# Test hostname resolution
dig @10.10.10.11 myapp.nebula

Adding a Service with Database

1. Define in services.yml

services:
  myapp:
    description: "My Application"
    host: myapp
    deploy_path: /opt/myapp
    postgres:
      enabled: true
    valkey:
      enabled: true
      key_prefix: "myapp"
    s3:
      enabled: true
      bucket: "myapp-media"
    vault_roles:
      - app
      - migrate

2. Provision Data Services

ansible-playbook -i inventory.ini playbooks/data-service.yml -e "service=myapp"

This creates:

• PostgreSQL database with static roles
• Valkey ACL user with key prefix
• Garage S3 bucket with API key
• Vault database engine roles

3. Retrieve Credentials

# Database credentials (dynamic)
vault read database/creds/myapp-app
vault read database/creds/myapp-migrate

# Valkey credentials (static, stored in Vault)
vault kv get secret/myapp/valkey

# S3 credentials (static, stored in Vault)
vault kv get secret/myapp/s3

Removing a VM

1. Remove from Terraform

Comment out or delete the module from .tf file, then:

terraform plan
terraform apply

2. Remove from Inventory

Edit ansible/inventory.ini and remove the host.

3. Clean up Certificates

rm -rf nebula/configs/<vmid>/

4. Update DNS

ansible-playbook -i inventory.ini playbooks/dns.yml