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

# 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

# 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

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

   ssh ubuntu@<VM_IP>
   

2. Copy install script:

   scp scripts/setup-<service>.sh ubuntu@<VM_IP>:/tmp/
   

3. Run install script:

   ssh ubuntu@<VM_IP>
   sudo chmod +x /tmp/setup-<service>.sh
   sudo /tmp/setup-<service>.sh
   

Complete Automated Setup

Run the complete setup script:

./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:

# 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