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

asded

Member
Sep 2, 2022
30
55
23
France
asded.fr
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
icon_txt.png
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.

Bash:
pgk -a kvm alpine

demo-00.gif

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.

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

demo-01.gif

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:

Bash:
pgk -a lxc alpine ss_ulxc_alpine-docker.yaml

demo-02.gif


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:

Bash:
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.

Bash:
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.
 
Thanks for sharing. Please note that Proxmox is a registered trademark, so please don't use it as part of your own product/app/tool name.
You can indicate that your work is for Proxmox VE by, e.g., using a wording that avoids suggesting that this is a Proxmox project, but rather for (enhancing) one, like "Guest Kickstarter for Proxmox VE".

You can find more details on our trademark on our website at https://www.proxmox.com/en/news/media-kit
 
Thanks for sharing. Please note that Proxmox is a registered trademark, so please don't use it as part of your own product/app/tool name.
You can indicate that your work is for Proxmox VE by, e.g., using a wording that avoids suggesting that this is a Proxmox project, but rather for (enhancing) one, like "Guest Kickstarter for Proxmox VE".

You can find more details on our trademark on our website at https://www.proxmox.com/en/news/media-kit
Yes, I received an email from the staff on this point. I'm currently working to rename my project, which takes some time considering that my Git repository also needs to be updated. I will include a note about it in the next release.
Best regards,
 
Many thanks for your considerations! FYI: a big reason to post an additional note here, was to better convey the trademark guidelines (which we have to defend, or we would lose them otherwise) to other readers, e.g. those also working on some projects (in the future).
 
  • Like
Reactions: asded
Many thanks for your considerations! FYI: a big reason to post an additional note here, was to better convey the trademark guidelines (which we have to defend, or we would lose them otherwise) to other readers, e.g. those also working on some projects (in the future).
I understand that, it's completely normal. I'll try to update my project as soon as possible.
 

About

The Proxmox community has been around for many years and offers help and support for Proxmox VE, Proxmox Backup Server, and Proxmox Mail Gateway.
We think our community is one of the best thanks to people like you!

Get your subscription!

The Proxmox team works very hard to make sure you are running the best software and getting stable updates and security enhancements, as well as quick enterprise support. Tens of thousands of happy customers have a Proxmox subscription. Get yours easily in our online shop.

Buy now!