# 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:

```hcl
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:

```bash
cd terraform
terraform plan
terraform apply
```

### 3. Generate Nebula Certificate

```bash
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`:

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

[docker]
myapp
```

### 5. Run Bootstrap Playbooks

```bash
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:

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

### 7. Verify

```bash
# 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

```yaml
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

```bash
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

```bash
# 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:

```bash
terraform plan
terraform apply
```

### 2. Remove from Inventory

Edit `ansible/inventory.ini` and remove the host.

### 3. Clean up Certificates

```bash
rm -rf nebula/configs/<vmid>/
```

### 4. Update DNS

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