Enhance README with detailed usage instructions, configuration options, and QEMU guest agent fallback information.
This commit is contained in:
@@ -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 <newid> --name <name> --full && qm start <newid>
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user