loc_az_hci/docs/temporary/VM_TEMPLATE_SETUP_GUIDE.md

# VM Template & Install Script Setup Guide

## Overview

This guide explains how to use Cloud-Init templates and automated install scripts for each VM.

## Architecture

### VM Configuration

| VM ID | Name | IP Address | Install Script | Purpose |
|-------|------|------------|-----------------|---------|
| 100 | cloudflare-tunnel | 192.168.1.60 | `setup-cloudflare-tunnel.sh` | Cloudflare Zero Trust Tunnel |
| 101 | k3s-master | 192.168.1.188 | `setup-k3s.sh` | Kubernetes (K3s) cluster |
| 102 | git-server | 192.168.1.121 | `setup-git-server.sh` | Gitea Git server |
| 103 | observability | 192.168.1.82 | `setup-observability.sh` | Prometheus + Grafana |

## Prerequisites

1. **Cloud-Init Template**: Ubuntu 24.04 Cloud-Init template in Proxmox
2. **SSH Key**: SSH key pair for accessing VMs
3. **Network**: VMs must be reachable on their assigned IPs

## Step 1: Create Cloud-Init Template

### Option A: Download Official Ubuntu Cloud Image

```bash
# Download Ubuntu 24.04 Cloud Image
./scripts/download-ubuntu-cloud-image.sh 24.04

# Upload to Proxmox and convert to template
# See: docs/proxmox-ubuntu-images.md
```

### Option B: Create Template from Installed VM

1. Install Ubuntu 24.04 from ISO on a VM
2. Install Cloud-Init: `sudo apt install cloud-init`
3. Configure Cloud-Init
4. Convert VM to template in Proxmox Web UI

## Step 2: Create VMs from Template

### Automated Method

```bash
# Set template name (if different from default)
export TEMPLATE_NAME="ubuntu-24.04-cloudinit"

# Create all VMs from template
./scripts/create-vms-from-template.sh
```

### Manual Method (Proxmox Web UI)

1. **Clone Template:**
   - Proxmox Web UI → Template → Clone
   - Set VM ID (100, 101, 102, 103)
   - Set name (cloudflare-tunnel, k3s-master, etc.)

2. **Configure Cloud-Init:**
   - Options tab → Cloud-Init
   - Set IP address
   - Set gateway
   - Set DNS servers
   - Set SSH keys

3. **Start VM:**
   - VM will boot and configure automatically

## Step 3: Apply Install Scripts

### Automated Method

```bash
# Set SSH key path (if different)
export SSH_KEY="~/.ssh/id_rsa"
export SSH_USER="ubuntu"

# Apply install scripts to all VMs
./scripts/apply-install-scripts.sh
```

### Manual Method

For each VM:

1. **SSH to VM:**
   ```bash
   ssh ubuntu@<VM_IP>
   ```

2. **Copy install script:**
   ```bash
   scp scripts/setup-<service>.sh ubuntu@<VM_IP>:/tmp/
   ```

3. **Run install script:**
   ```bash
   ssh ubuntu@<VM_IP>
   sudo chmod +x /tmp/setup-<service>.sh
   sudo /tmp/setup-<service>.sh
   ```

## Complete Automated Setup

Run the complete setup script:

```bash
./scripts/setup-vms-complete.sh
```

This script will:
1. Check for template
2. Create VMs from template
3. Wait for VMs to boot
4. Apply install scripts

## Install Scripts Details

### VM 100: Cloudflare Tunnel

**Script:** `scripts/setup-cloudflare-tunnel.sh`

**What it does:**
- Installs cloudflared
- Creates cloudflared user
- Sets up systemd service
- Creates configuration template

**Manual steps required:**
- Authenticate cloudflared: `cloudflared tunnel login`
- Create tunnel: `cloudflared tunnel create azure-stack-hci`
- Update config.yml with your domain
- Configure DNS records in Cloudflare

### VM 101: K3s Master

**Script:** `scripts/setup-k3s.sh`

**What it does:**
- Installs K3s Kubernetes
- Configures kubectl
- Sets up kubeconfig

**Next steps:**
- Create namespaces
- Deploy ingress controller
- Deploy cert-manager
- Deploy HC Stack services

### VM 102: Git Server (Gitea)

**Script:** `scripts/setup-git-server.sh`

**What it does:**
- Installs Gitea
- Creates Gitea user
- Sets up systemd service
- Creates initial configuration

**Next steps:**
- Complete initial setup via web UI
- Create GitOps repository
- Configure SSH keys
- Set up Flux GitOps

### VM 103: Observability

**Script:** `scripts/setup-observability.sh`

**What it does:**
- Installs Prometheus
- Installs Node Exporter
- Installs Grafana
- Creates systemd services

**Next steps:**
- Access Grafana (http://192.168.1.82:3000)
- Change default password
- Add Prometheus as data source
- Import dashboards

## Troubleshooting

### Template Not Found

**Error:** `Template not found`

**Solution:**
- Create template first (see Step 1)
- Verify template name matches `TEMPLATE_NAME` variable

### VM Not Reachable

**Error:** `VM not reachable`

**Solution:**
- Check VM is started
- Verify IP address configuration
- Check network connectivity
- Verify Cloud-Init completed

### SSH Connection Failed

**Error:** `SSH not available`

**Solution:**
- Wait longer for VM to boot (5-10 minutes)
- Check SSH service is running
- Verify SSH key is correct
- Check firewall rules

### Install Script Failed

**Error:** `Install script failed`

**Solution:**
- SSH to VM and check logs
- Run script manually to see errors
- Check script has execute permissions
- Verify network connectivity for downloads

## Verification

After setup, verify each service:

```bash
# VM 100: Cloudflare Tunnel
ssh ubuntu@192.168.1.60
sudo systemctl status cloudflared

# VM 101: K3s
ssh ubuntu@192.168.1.188
kubectl get nodes

# VM 102: Gitea
curl http://192.168.1.121:3000

# VM 103: Observability
curl http://192.168.1.82:9090  # Prometheus
curl http://192.168.1.82:3000  # Grafana
```

## Summary

1. **Create Cloud-Init template** (one-time)
2. **Create VMs from template** (automated or manual)
3. **Apply install scripts** (automated or manual)
4. **Verify services** are running
5. **Complete manual configuration** as needed

## Scripts Reference

- `scripts/create-vms-from-template.sh` - Create VMs with Cloud-Init
- `scripts/apply-install-scripts.sh` - Apply install scripts via SSH
- `scripts/setup-vms-complete.sh` - Complete automated setup
- `scripts/download-ubuntu-cloud-image.sh` - Download Cloud Image
- `scripts/create-proxmox-template.sh` - Template creation guide