diff --git a/README.md b/README.md index ba7dde9..a7a038a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,73 @@ # Proxmox Create Template -Script to create a proxmox template VM using a Ubuntu Cloud Image. +Script to create a Proxmox template VM using the newest Ubuntu Cloud Image, with a cloud-init drive. + +## What it does + +1. Looks up the newest Ubuntu release on `cloud-images.ubuntu.com` (newest LTS by default). +2. Downloads the cloud image and verifies its SHA256 checksum. +3. Optionally bakes `qemu-guest-agent` into the image with `virt-customize` (installs `libguestfs-tools` if missing). +4. Creates the VM (virtio NIC, virtio-scsi-single, `cpu host`, guest agent enabled, serial console). +5. Imports the image as `scsi0` (discard, ssd, iothread) and resizes it to `DISK_SIZE`. +6. Adds a cloud-init drive with user, SSH keys, optional password and DHCP networking. +7. Converts the VM to a template. + +## Requirements + +- Run on the Proxmox host as **root** +- `curl` +- Internet access (for the image and, if needed, `libguestfs-tools`) + +## Usage + +```bash +./create-template.sh +``` + +Override any setting via environment variables: + +```bash +VMID=9001 STORAGE=local-zfs CHANNEL=latest ./create-template.sh +``` + +Then clone the template: + +```bash +qm clone 9000 --name --full && qm start +``` + +## Configuration + +| Variable | Default | Description | +|-------------------|-----------------------------|-------------| +| `VMID` | `9000` | ID of the template VM (must not exist yet) | +| `STORAGE` | `local-lvm` | Storage for the disk and cloud-init drive | +| `BRIDGE` | `vmbr0` | Network bridge | +| `CORES` | `2` | CPU cores | +| `MEMORY` | `2048` | Memory in MiB | +| `DISK_SIZE` | `20G` | Final root disk size (must be larger than the image, ~3.5G) | +| `ARCH` | `amd64` | `amd64` or `arm64` | +| `CHANNEL` | `lts` | `lts` = newest LTS, `latest` = newest release incl. interim | +| `CI_USER` | `niklas` | Cloud-init default user | +| `CI_PASSWORD` | *(empty)* | Optional password; leave empty to rely on SSH keys only | +| `SSH_KEY_FILE` | `$HOME/.ssh/authorized_keys`| Public keys injected via cloud-init | +| `INSTALL_QGA` | `1` | Bake `qemu-guest-agent` into the image (`0` to skip) | +| `SNIPPET_STORAGE` | `local` | Storage for the cloud-init snippet used by the QGA fallback | + +## QEMU guest agent fallback + +If `virt-customize` can't install `qemu-guest-agent` (usually no network/DNS inside the libguestfs appliance), the script falls back to a cloud-init vendor snippet (`qga-vendor.yaml`) on `SNIPPET_STORAGE`. Clones then install the agent on first boot, which requires internet access on the clone. The vendor data only adds to Proxmox's generated user data, so `ciuser`/`sshkeys` still apply. + +The snippet storage must allow the `snippets` content type. Enable it by adding `snippets` to the existing content list, e.g.: + +```bash +pvesm set local --content iso,vztmpl,backup,snippets +``` + +Otherwise, just run `apt install qemu-guest-agent` inside each clone. + +## Notes + +- If neither an SSH key file nor a password is set, you can't log in until you set one in the VM's Cloud-Init tab. +- The script aborts if the VMID already exists or the storage doesn't exist. +- Downloads happen in a temp directory that is removed on exit.