Proxmox Cloud Image Tool

Tool untuk membuat template di Proxmox menggunakan cloud image (Ubuntu, Debian, CentOS, dll) dengan Golang.

Features

• Download cloud image dari URL atau gunakan local file
• Customize image (resize disk, inject SSH key)
• Otomatis create template di Proxmox
• Support konfigurasi via CLI flags atau YAML file
• Progress bar untuk download
• QEMU Guest Agent support (auto-enable)
• Firewall configuration (enable/disable + custom rules)
• Batch mode untuk create multiple templates sekaligus

Tools

1. Linux Cloud Images (Main Tool)

Tool utama untuk Linux cloud images (Ubuntu, Debian, CentOS, Rocky, dll).

📁 Location: Root directory 📖 Docs: README.md (this file)

2. Windows Cloud Images

Tool terpisah untuk Windows cloud images (Windows Server, Windows 11).

📁 Location: windows-tools/ 📖 Docs: windows-tools/README.md

Key Differences:

• Windows: UEFI + TPM 2.0 + Secure Boot
• Linux: BIOS/UEFI flexible
• Windows: Requires qcow2 image from cloudbase/windows-imaging-tools
• Linux: Download langsung dari official repos

Requirements

• Go 1.19+
• SSH access ke Proxmox host
• qemu-img dan virt-customize (libguestfs-tools)

Install dependencies di Ubuntu/Debian:

sudo apt install qemu-utils libguestfs-tools

Installation

Quick Install (Recommended):

git clone <repo-url>
cd cloud-image
sudo ./install.sh

Installer akan otomatis:

• Install dependencies (qemu-utils, libguestfs-tools)
• Build binary
• Install ke /usr/local/bin

Manual Build:

git clone <repo-url>
cd cloud-image
go build -o proxmox-cloud-image
sudo cp proxmox-cloud-image /usr/local/bin/
sudo chmod +x /usr/local/bin/proxmox-cloud-image

Uninstall:

cd cloud-image
sudo ./uninstall.sh

Setelah install, bisa langsung dipanggil dari mana aja:

proxmox-cloud-image -h

Windows (WSL2):

# Install WSL2 Ubuntu
wsl --install

# Masuk ke WSL
wsl

# Install dependencies
sudo apt update
sudo apt install qemu-utils libguestfs-tools golang-go

# Clone dan install
git clone <repo-url>
cd cloud-image
sudo ./install.sh

Docker (Cross-platform):

Build image:

docker build -t proxmox-cloud-image .

Jalankan:

docker run --rm -v $(pwd)/configs:/workspace proxmox-cloud-image -config /workspace/config.yaml

Atau buat alias:

alias proxmox-cloud-image='docker run --rm -v $(pwd):/workspace proxmox-cloud-image'
proxmox-cloud-image -h

Usage

Menggunakan URL (download):

proxmox-cloud-image \
  -image-url "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -vm-id 9000 \
  -proxmox-host "192.168.1.100" \
  -proxmox-user "root@pam" \
  -storage "local-lvm" \
  -memory 2048 \
  -cores 2 \
  -disk-size "20G" \
  -bridge "vmbr0" \
  -ssh-key "/root/.ssh/id_rsa.pub" \
  -guest-agent \
  -firewall

Menggunakan local file:

proxmox-cloud-image \
  -image-url "/path/to/ubuntu-22.04-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -vm-id 9000 \
  -proxmox-host "192.168.1.100" \
  -storage "local-lvm" \
  -guest-agent

Auto-find VM ID (mulai dari 10000):

proxmox-cloud-image \
  -image-url "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -proxmox-host "192.168.1.100" \
  -guest-agent

Dengan VLAN:

proxmox-cloud-image \
  -image-url "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -vm-id 9000 \
  -proxmox-host "192.168.1.100" \
  -bridge "vmbr0" \
  -vlan-tag 100 \
  -guest-agent \
  -firewall

Menggunakan config file:

proxmox-cloud-image -config config.yaml

Contoh config.yaml dengan URL:

image_url: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
vm_name: "ubuntu-template"
vm_id: 0
storage: "local-lvm"
memory: 2048
cores: 2
disk_size: "20G"
bridge: "vmbr0"
vlan_tag: 100
ssh_key: "/root/.ssh/id_rsa.pub"
proxmox_host: "192.168.1.100"
proxmox_user: "root@pam"
proxmox_pass: ""
guest_agent: true
firewall: true
firewall_rules:
  - type: in
    action: accept
    protocol: tcp
    dport: "22"
    comment: "SSH"
  - type: in
    action: accept
    protocol: tcp
    dport: "80,443"
    comment: "HTTP/HTTPS"

Contoh config.yaml dengan local file:

image_url: "/home/user/images/ubuntu-22.04-server-cloudimg-amd64.img"
vm_name: "ubuntu-template"
vm_id: 0
storage: "local-lvm"
memory: 2048
cores: 2
disk_size: "20G"
bridge: "vmbr0"
ssh_key: "/root/.ssh/id_rsa.pub"
proxmox_host: "192.168.1.100"
proxmox_user: "root@pam"
guest_agent: true
firewall: false

Batch mode (multiple templates):

Buat file batch (contoh: batch.txt) dengan list config files:

# Ubuntu templates
configs/ubuntu-22.04.yaml
configs/ubuntu-20.04.yaml

# Debian templates
configs/debian-12.yaml
configs/debian-11.yaml

Jalankan batch:

proxmox-cloud-image -batch batch.txt

Features:

• Process multiple config files sekaligus
• Max 3 concurrent jobs (parallel)
• Auto-skip lines yang kosong atau comment (#)
• Summary report di akhir

Cloud Image URLs

Ubuntu

• Ubuntu 22.04 (Jammy): https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
• Ubuntu 20.04 (Focal): https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img

Debian

• Debian 12 (Bookworm): https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2
• Debian 11 (Bullseye): https://cloud.debian.org/images/cloud/bullseye/latest/debian-11-generic-amd64.qcow2

CentOS Stream

• CentOS Stream 9: https://cloud.centos.org/centos/9-stream/x86_64/images/CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2

Flags

Flag	Default	Description
-config	-	Path ke config file (YAML)
-image-url	-	URL cloud image (required)
-vm-name	cloud-vm	Nama template
-vm-id	0	Template ID (0 = auto-find dari 10000+)
-storage	auto-detect	Nama storage Proxmox (auto-detect jika kosong)
-memory	2048	Memory dalam MB
-cores	2	Jumlah CPU cores
-disk-size	20G	Ukuran disk
-bridge	vmbr0	Network bridge
-vlan-tag	0	VLAN tag (0 = no VLAN)
-guest-agent	false	Enable QEMU guest agent
-firewall	false	Enable firewall
-ssh-key	-	Path ke SSH public key
-proxmox-host	-	IP/hostname Proxmox (required)
-proxmox-user	root@pam	Proxmox user
-proxmox-pass	-	Proxmox password
-list-storage	-	List semua storage yang tersedia
-ls	-	Shorthand untuk -list-storage

How It Works

1. Prepare image (download dari URL atau copy dari local file)
2. Customize image:
   • Resize disk (jika di-specify)
   • Inject SSH key (jika ada)
   • Install qemu-guest-agent package (jika guest-agent enabled)
3. Upload image ke Proxmox host via SCP
4. Create VM menggunakan qm commands
5. Import disk dan configure VM
6. Setup cloud-init
7. Enable QEMU Guest Agent (jika di-enable)
8. Enable Proxmox firewall (jika di-enable)
9. Configure firewall rules (jika ada rules yang di-define)
10. Convert VM menjadi template dengan qm template

QEMU Guest Agent

QEMU Guest Agent adalah service yang berjalan di guest OS untuk:

• IP address discovery
• Graceful shutdown/reboot
• File system freeze/thaw
• Time synchronization

Tool ini akan otomatis install qemu-guest-agent package ke dalam image menggunakan virt-customize sebelum upload ke Proxmox.

Enable dengan flag -guest-agent atau di config file:

guest_agent: true

Note: Guest agent di-enable by default. Package akan di-install otomatis saat customize image.

Proxmox Firewall

Proxmox firewall bisa di-enable untuk template dengan flag -firewall atau di config file:

firewall: true

Firewall Rules

Kamu juga bisa define firewall rules langsung di config file:

firewall: true
firewall_rules:
  - type: in
    action: accept
    protocol: tcp
    dport: "22"
    comment: "SSH"
  - type: in
    action: accept
    protocol: tcp
    dport: "80,443"
    comment: "HTTP/HTTPS"
  - type: in
    action: accept
    protocol: icmp
    comment: "ICMP/Ping"
  - type: in
    action: drop
    comment: "Drop all other incoming"

Firewall Rule Fields:

• type: in (incoming) atau out (outgoing)
• action: accept, drop, atau reject
• protocol: tcp, udp, icmp, dll (optional)
• dport: destination port atau port range, contoh: 22, 80,443, 8000:9000 (optional)
• sport: source port (optional)
• source: source IP/CIDR, contoh: 192.168.1.0/24 (optional)
• dest: destination IP/CIDR (optional)
• comment: komentar untuk rule (optional)

Rules akan ditulis ke /etc/pve/firewall/<vmid>.fw di Proxmox host.

Firewall akan di-enable di network interface VM.

Clone Template

Setelah template dibuat, kamu bisa clone untuk membuat VM baru:

qm clone 9000 100 --name my-vm --full
qm set 100 --ipconfig0 ip=192.168.1.100/24,gw=192.168.1.1
qm set 100 --sshkeys /root/.ssh/id_rsa.pub
qm start 100

Notes

• Tool ini menggunakan SSH untuk koneksi ke Proxmox
• Pastikan SSH key sudah di-setup untuk passwordless login
• Image akan di-download ke /tmp dan di-upload ke Proxmox
• Template tidak bisa di-start, harus di-clone dulu
• QEMU Guest Agent akan otomatis ter-install di guest OS yang support

License

MIT License

Copyright (c) 2025 Othman Hendy Suseno

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.