Proxmox GK aka Proxmox Guests Kickstart
Third-party Proxmox bash utility to automate deployment of LXC and QEMU/KVM guests, individually or in batches, via Cloud-init.
Features list:
- Batch and automate guests deployment
- Cloud-init integration for LXC and QEMU/KVM
- Fast provisioning Proxmox templates
Datasheet of supported guests:
| Distribution | Version | QEMU/KVM | LXC *1 | Cloud-init support |
|---|---|---|---|---|
| Devuan | 4.0 | ❌ | ✅ | ✅ |
| Debian | 11 | ✅ | ✅ | ✅ |
| 12 | ✅ | ✅ | ✅ | |
| Ubuntu | 20.04 | ✅ | ✅ | ✅ |
| 22.04 | ✅ | ✅ | ✅ | |
| 23.04 | ✅ | ✅ | ✅ | |
| 24.04 | ✅ | ✅ | ✅ | |
| Fedora | 39 | ✅ | ✅ | ✅ |
| 40 | ✅ | ✅ | ✅ | |
| CentOS stream | 9 | ✅ | ✅ | ✅ |
| Alamalinux | 8 | ✅ | ✅ | ✅ |
| 9 | ✅ | ✅ | ✅ | |
| Rocky Linux | 9 | ✅ | ✅ | ✅ |
| OpenSUSE | 15.4 | ❌ | ✅ | ✅ |
| 15.5 | ❌ | ✅ | ✅ | |
| Arch Linux | current | ✅ | ✅ | ✅ |
| Alpine Linux | 3.18 | ✅ | ✅ | ✅ |
| 3.19 | ✅ | ✅ | ✅ | |
| Gentoo | current | ❌ | ✅ | ✅ |
| OpenBSD | 7.5 | ✅ | ❌ | ✅ *2 |
| FreeBSD | 14 | ✅ | ❌ | ✅ *2 |
* 1 Based on container images from the official Proxmox repository
* 2 FreeBSD and OpenBSD don't officialy support cloud-init, These images come from bsd-cloud-image.org
usage: pgk -a lxc|kvm [IMAGE] [SHAPE]
- -a: Minimalist deployment option, pgk will define the appropriate parameters according to the image chosen, but it is still possible to pass a custom shape as an argument to adapt the deployment parameters.
- [lxc|kvm] Required argument for type of guests LXC or QEMU/KVM
- [IMAGE] Name of the image distribution, you can provide full namefile or use regex expression
- [SHAPE] Optional argument, specify a namefile for overide default guest settings
Ex: Minimalist deployment of Fedora 39 based virtual machine, the regex syntax is used to filter all images available.
pgk -a kvm fedora.*39Note
If no shapefile provided, a default configuration will be applied and will perform a basic pre-configuration of the guest: default user setup, openssh configuration, qemu-guest-agent installation (only KVM/QEMU guest), timezone and locale.
usage: pgk -b lxc|kvm [IMAGE] [ID(S)] [IP(S)] [SHAPE]
-b: Batch deployment option, unlike automatic mode, allows multiple Guests to be deployed from the same image.
- [lxc|kvm] Required argument for type of guests LXC or QEMU/KVM
- [IMAGE] Name of the image distribution, you can provide full namefile or use regex expression
- [ID(S)] Required argument for available CTID/VMID, numerical value like '100' or '100,101,103' for batch deployement
- [IP(S)] Required argument for static adress like '192.168.2.100' or '192.168.2.100,101,102' for batch deployement, default CIDR is provided form configuration file.
- [SHAPE] Optional argument, specify a namefile for overide default guest settings
Ex: Batch deploy three QEMU virtual machines based on alpine linux, with a VMID (100,101,102) for each of them, and a dedicated IP address in the format 192.168.2.***.
pgk -b kvm alpine 100,101,102 192.168.2.100,101,102usage: pgk -t lxc|kvm [IMAGE] [SHAPE]
-t: Provisionning a Proxmox template, the pre-configuration of template required a shape file.
- [lxc|kvm] Required argument for type of guests LXC or QEMU/KVM
- [IMAGE] Name of the image distribution, you can provide full namefile or use regex expression
- [SHAPE] Required argument, specify a namefile for overide default guest settings
Ex: Creation of a "Proxmox template" based on alpine linux for an unprivileged container. In this case, a shape preset is used to overwrite the default settings of container, and contains additionnaly directives for docker installation.
pgk -t lxc alpine ss_ulxc_alpine-docker.yamlusage: pgk -l [TYPE_FILE]
-l: Option for List available LXC/QEMU images & configurations files
- -l img list availability of guests images on pve host
- -l lxc list shape preset available for LXC guests
- -l kvm list shape preset available for QEMU/KVM guests
- -l ci list cloud-init yaml file (auto-generated by shape file)
- -l fs lists the expected required files and folders (debug)
usage: pgk -u [TYPE_FILE]
-u: Update configuration files.
- -u dshape Regenerate all default shape
- -u lxc_index Manual update of the lxc index images
usage: pgk -e [TYPE_FILE] [NAMEFILE]
usage: pgk -e [TYPE_FILE]
-e: Option to edit or create a new shape (LXC/QEMU). But also a quick way to edit the main configuration files
- -e lxc [NAMEFILE] Edit or create a shape preset file for lxc guest
- -e kvm [NAMEFILE] Edit or create a shape preset file for QEMU/KVM guest
- -e config Edit main configuration file
- -e kvm_index Edit QEMU/KVM index image
- -e lxc_index Edit LXC index image
Ex: Edit a new shape configuration file:
pgk -e kvm my_shape.yamlNote
In this example, if the file does not exist you will be asked to select a base template for the file depending on the distribution you want to customize.The preset shape will then be pre-populated with the default configuration of hardware settings, as well as the basic directives for cloud-init.You can then modify the file directly, from your favorite text-editor. To add your own instructions.
All shape files are structured in the same way and follow YAML syntax. Three blocks must be present:
- gs_values: contains the values, necessary for the creation of the lxc/qemu guest, they will be extracted and interpreted as environment variables.
- extra_guest_config: this is an optional block, containing the directives (one per line) that we would like to pass directly into the guest's PVE configuration file, /etc/pve/lxc/CTID.conf or / etc/pve/qemu-server/VMID.conf. Use with caution, the wrong instruction could prevent the guest from starting correctly.
- cloud_init: contains the directives that will be interpreted by cloud-init.
apt install make curl jq wget
git clone https://github.com/asdeed/proxmox_gk.git
cd proxmox_gk
make install
# uninstall and purge : make uninstallThe Proxmox storage model is very flexible, PGK needs to know where the different types of content are based on your Proxmox installation. The /etc/pve/storage.cfg file summarizes the status of all your storage. Make sure you then adapt the variables for the ‘data store’ and ‘image store’ in the main configuration file /etc/pgk/config.cfg.
HS_PATH_DATASTR=/var/lib/vz # Full path of datastore
# type of content required: iso,vztmpl,snippets
HS_LOCALVM=local-lvm # Name of guests image store (local-zfs|local-btrfs)
# type of content required: rootdir,images
HS_DATASTR=local # Common name of datastore
HS_CIIMG=$HS_PATH_DATASTR/template/iso # Folder dedicated to QEMU/KVM cloud images
HS_LXCIMG=$HS_PATH_DATASTR/template/cache # Folder dedicated to lxc images
HS_PATH_CONF=$HS_PATH_DATASTR/snippets # Folder dedicated to cloud-init config files (.yaml)In addition, pgk uses your environment variable to store some secret for setup your guests:
- GS_CIUSER: Default username, for all guests
- GS_CIPASSWD_PLAIN: Default plain password for GS_CIUSER, required only for OpenBSD (bcrypt exception)
- GS_CIPASSWD_SHA: Default hashed password for GS_CIUSER
You must set all these variables before run this program :
echo "export GS_CIUSER='YOUR_USERNAME'" | tee -a $HOME/.bashrc
echo "export GS_CIPASSWD_PLAIN='YOUR_PLAINTEXT_PASSWORD'" | tee -a $HOME/.bashrc
echo "export GS_CIPASSWD_SHA='$(openssl passwd -6 "YOUR_PLAINTEXT_PASSWORD")'" | tee -a $HOME/.bashrc
source $HOME/.bashrc- Better management of lxc/kvm JSON index & default shape
- Function for adding lxc/kvm images from third-party repositories
- Function for updating/modifying cloud-init configuration of an existing guest
- Bash completion
- Debian package
- Improve the logging function
- Improve cloud-init integration for LXC
- Interactive (dialog) helper for first setup
- Built-in vault function for store secret, as replacement of environment variable
- Support for guests deployed in a clustered pve infrastructure
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.