[TUTORIAL] Proxmox automator for deploy LXC and QEMU guests, with Cloud-init

[asded]

Good evening everyone, I've just released a small command line utility for Proxmox v7, 8 to automate the provisioning and deployment of your containers and virtual machines with Cloud-init.

Key features:

• Unified configuration of LXC and QEMU/KVM guests via Cloud-init.
• Flexible guest deployment:
  • in single or serial mode
  • fully automated or with your own presets
• Fast, personalized provisioning of your Proxmox templates

• Github
• latest release (tar.gz)
• GPL-3.0 license

I've always been frustrated by the lack of native tools in Proxmox for automating guest provisioning and deployment, whether for virtual machines or containers. This left the field wide open to solutions such as Packer, Terraform|OpenTofu, Ansible, etc. Very good tools if there ever was one, but perhaps a little oversized for the number of features they offer. What I found particularly regrettable was that virtually all the building blocks needed to automate provisioning and deployment tasks were present in Proxmox, and all that was needed was a link to make them work together.

Initially, I used a set of heterogeneous shell scripts, exclusively to automate the creation of Cloud-init compatible vm's (I was greatly inspired by the article Linux VM Templates in Proxmox on EASY MODE using Prebuilt Cloud Init Images. After a while, as my scripts became more and more important as new features were added, I realized that there was enough material there to develop a complete utility.

At least, enough to finalize a first version of a quick and easy-to-use utility, specifically dedicated to these provisioning and deployment tasks. In that sense, it's more an extension to Proxmox than a full-fledged tool. And, of course, far less comprehensive than the aforementioned solutions.

I had a few guiding principles during development:

• Transparent interaction with system commands, simplified error handling and debugging. To help with code maintenance and modularity.
• I also needed a simple installation process, so as to reduce the number of dependencies as much as possible, notably by favoring calls to basic UNIX tools.
• Finally, I wanted a low learning curve, with no need to define a new nomenclature of notions to be assimilated to be able to manipulate the utility, simply reusing and unifying the concepts of the native commands and of course the Cloud-init syntax.

How it's works ?​

Let's take a look at what it can do, and how it can do it.

Flexible deployment modes​

As I said earlier, what I wanted above all was a simple tool that would allow you to launch a guest, be it a container or a virtual machine, in a single command line. Here, we're deploying a vm under Alpine Linux, and since the regex syntax is supported by grep, there's no need to enter the full name of the image.

pgk -a kvm alpine

It's also possible to deploy multiple guests from a single image. For example, three Alpine Linux virtual machines, with an ID (100,101,102) for each one, and a dedicated IP address in 192.168.2.** format.

pgk -b kvm alpine 141,142,143 192.168.2.14,15,16

In all these cases, a default configuration will be applied from a "shape" file according to the chosen image, and will perform a basic setup of the guest(s), including: adding a default user, configuring OpenSSH, installing the QEMU agent (only for vm), adjusting the time zone and location.

All default values are accessible from the main configuration file /etc/pgk/config.cfg, editable with pgk -e confile.

Customization and templating​

It's also possible to pass on your own shape file, so you can customize the configuration of your guests on a case-by-case basis. Here are a few example shapes (based on Alpine Linux) for you to try out:

• ss_kvm_alpine-docker.yaml : Docker pre-configuration for QEMU/KVM guests
• ss_plxc_alpine-docker.yaml : Docker pre-configuration for privileged containers
• ss_ulxc_alpine-docker.yaml : Docker pre-configuration for non-privileged containers

All you need to do is fill in the arguments, as follows:

pgk -a lxc alpine ss_ulxc_alpine-docker.yaml

In this example, we create our own shape for a vm. We will then be asked to choose a pre-filled base model according to the chosen distribution. All that's left to do is to make our own modifications, according to our needs:

pgk -e kvm my_shape.yaml

Here again, the pre-filled fields are made according to your parameters in the main configuration file /etc/pgk/config.cfg. Also, all shape files are structured in the same way and respect YAML syntax. Three blocks must be present:

• gs_values: contains the values required to create the LXC/QEMU guest, which will be extracted and interpreted as environment variables, and only concerns the creation of the vm or container (essentially interacting with /usr/bin/pct and /usr/bin/qm).
• extra_guest_config: this is an optional block, containing directives (one per line) that we'd like to pass directly to the guest's PVE configuration file, /etc/pve/lxc/CTID.conf or /etc/pve/qemu-server/VMID.conf. Use with caution, as a wrong instruction could prevent the guest from booting correctly.
• cloud_init: contains the directives that will be interpreted by Cloud-init to configure the guest.

Finally, you can provision your Proxmox templates, here, by reusing our previously created shape.

pgk -t kvm my_shape.yaml

The output template can then be reused, like a conventional template, by simple cloning, as the basis for subsequent deployments.

Functional structure​

I didn't want the utility to radically alter the way Proxmox works. Its installation adds only a few prerequisite files, following the official nomenclature of a classic Debian package.

• /etc/pgk/config.cfg : the main configuration file
• /var/lib/pgk: Contains the basic shapes for the various guest types, and the indexes. This is also where your custom shapes will be stored. Also contains some files needed to initialize Cloud-init for containers.
  • init/ds_kvm_*.conf: default shape for KVM guests
  • init/ds_lxc_*.conf: default shape for LXC guests
  • init/cinit.sh: payload needed to configure Cloud-init containers.
  • lxc_index.json: auto-generated index, contains the addresses of the various container images and their default shapes.
  • kvm_index.json: index containing the addresses of the various QEMU/KVM guest images.
• /usr/lib/pgk: Contains scripts for executing the main functions.
  • /usr/lib/pgk/pgk.sh > /usr/bin/pgk: Main executable, symlinked to /usr/bin/pgk.
• /var/log/pgk.log: log file, tracking during guest creation, as well as the Cloud-init setup process for containers.

Roadmap​

As it stands, the project is still in alpha phase, and I'm the only one working on it (for the moment). In my opinion, the main functions are defined, but they'll have to be improved in future releases. For the time being, I'll be concentrating on consolidating them, and adding a few other ancillary functions.

What will be improved

• Log management and guest creation/configuration tracking
• Secret management (hash, password)
• Cloud-init integration for LXC

What will be added

• Bash completion
• Debian package
• Customizable indexes and default shapes (LXC/QEMU)
• A function to update/modify the Coud-init configuration of an existing guest
• Interactive function (in Dialog mode) for configuring Proxmox GK on first boot
• Support for deployment in a cluster infrastructure

That's it, I think I've said it all, I'll be posting progress here as often as I can. I'm also open to criticism, questions and bug reports if you feel like it.