ansible-role-proxmoxserver

An Ansible role for For setting up a Proxmox node.

Table of Contents

🔎 Metadata
📌 Requirements
📜 Role Variables
📜 Facts/Variables defined by this role
🏷️ Tags
👫 Dependencies
📚 Example Playbook Usages
🧪 Tested Distributions
🧪 Tested Ansible versions
📝 Development
🗒 Changelog
⚖️ License

🔎 Metadata

Below you can find information on…

the role’s required Ansible version
the role’s supported platforms
the role’s role dependencies

---
galaxy_info:
  role_name: "proxmoxserver"
  description: "An ansible role for For setting up a Proxmox node."
  standalone: true

  author: "bvierra"
  license: "MIT"

  min_ansible_version: "2.11"
  platforms:
    # note: text after "actively tested: " represent the docker image name
    - name: Debian
      versions:
        - bookworm # actively tested: debian12

  galaxy_tags: []

dependencies: []

📌 Requirements

The Ansible User needs to be able to become.

The community.general collection must be installed on the Ansible controller.

📜 Role Variables

Table 1. Variables - ansible-user

Variable	Type	Default	Comments
`manage_ansible_user`	`bool`	`true`	Whether or not to manage the ansible user. If set to false the rest of the options in this section are ignored.
`ansible_user`	`str`	`ansible`	The name of the ansible user
`ansible_user_password`	`str`	`null`	The encoded password for the ansible user (use `mkpasswd --method=SHA-512` to generate, if left as null it will lock the variable)
`ansible_user_regenerate_ssh_key`	`str`	`never`	Whether or not to regenerate the ansible user’s ssh key. When set to never, if a key already exists (even if it does not match the specified type and size) it will not be regenerated. When set to `always` it will always regenerate the key. When set to `on_change` it will only regenerate the key if the type or size do not match the specified values.
`ansible_user_ssh_key_type`	`str`	`ssh-ed25519`	The type of ssh key to generate for the ansible user
`ansible_user_ssh_key_size`	`int`	`521`	The size of the ssh key to generate for the ansible user
`ansible_user_ssh_key_dir`	`str`	`~/.ssh`	The directory (on the computer running ansible) to store the ansible user’s ssh key. This is by default set to ~/.ssh since it is assumed that the ansible nodes are more perminant that VM’s would be and you will want to keep the key around for future use.
`ansible_user_ssh_key_name`	`str`	`id_ed25519-ansible`	The name of the ssh key to generate/use for the ansible user

Table 2. Variables - proxmox-os

Variable	Type	Default	Comments
`pve_additional_packages`	`list[str]`	`null`	A list of additional packages to install
`pve_no_subscription`	`bool`	`true`	If set to true this will disable the subscription nag screen, disable the enterprise apt source, and setup the community apt source. This is useful for homelab users who do not have a subscription.
`pve_no_subscription_apt_key_id`	`str`	`1140AF8F639E0C39`	The key id to use when importing the proxmox no subscription apt key
`pve_no_subscription_apt_key_url`	`str`	`https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg`	The url to use when downloading the proxmox no subscription apt key
`pve_no_subscription_apt_source`	`str`	`deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription`	The community apt source to use when `pve_no_subscription` is set to true
`update_system_packages`	`bool`	`true`	Whether or not to update the system packages

Table 3. Variables - install-sdn

Variable	Type	Default	Comments
`pve_install_sdn`	`bool`	`false`	Whether or not to install the proxmox SDN module
`pve_sdn_package`	`str`	`pve-sdn`	The name of the proxmox SDN package to install

Table 4. Variables - install-sdn

Variable	Type	Default	Comments
`pve_watchdog_ipmi`	`bool`	`false`	Whether or not to install the proxmox SDN module (if set to false the rest of the variables in the section are ignored)
`pve_watchdog_ipmi_action`	`str`	`reset`	Action to take when the watchdog timer expires. Valid values are `power_cycle`, `power_off`, `reset`, `none`
`pve_watchdog_ipmi_package`	`str`	`ipmitool`	The name of the ipmi package to install. Currently the only supported package is `ipmitool`
`pve_watchdog_ipmi_enterprise_numbers_file`	`str`	`/usr/share/misc/enterprise-numbers.txt`	The path to the enterprise numbers file. This is used to lookup the ipmi manufacturer id
`pve_watchdog_ipmi_enterprise_numbers_url`	`str`	`https://www.iana.org/assignments/enterprise-numbers.txt`	The url to download the enterprise numbers file from

Table 5. Internal Variables

Variable	Type	Section	Default	Comments
`_pve_required_packages`	`list[str]`	`proxmox-os`	`["sudo", "numactl"]`	A list of packages that are required to be installed on the proxmox nodes.

📜 Facts/Variables defined by this role

Each variable listed in this section is dynamically defined when executing this role (and can only be overwritten using ansible.builtin.set_facts) and is meant to be used not just internally.

🏷️ Tags

Tasks are tagged with the following tags:

Tag	Purpose
This role does not have officially documented tags yet.

You can use Ansible to skip tasks, or only run certain tasks by using these tags. By default, all tasks are run when no tags are specified.

👫 Dependencies

📚 Example Playbook Usages

Note

This role is part of many compatible purpose-specific roles of mine.

The machine needs to be prepared. In CI, this is done in molecule/resources/prepare.yml which sources its soft dependencies from requirements.yml:

molecule/resources/prepare.yml

---
- name: prepare
  hosts: all
  become: true
  gather_facts: false

  roles:
    - role: jonaspammer.bootstrap
    #    - name: jonaspammer.core_dependencies

The following diagram is a compilation of the "soft dependencies" of this role as well as the recursive tree of their soft dependencies.

Example 1. Minimum Viable Play

roles:
  - role: bvierra.proxmoxserver

vars:
  some_var: "some_value"

🧪 Tested Distributions

A role may work on different distributions, like Red Hat Enterprise Linux (RHEL), even though there is no test for this exact distribution.

OS Family	Distribution	Distribution Release Date	Distribution End of Life	Accompanying Docker Image
Debian	Debian 12	10 Jun 2023	10 Jun 2026 (LTS: 10 Jun 2028)

🧪 Tested Ansible versions

The tested ansible versions try to stay equivalent with the support pattern of Ansible’s community.general collection. As of writing this is:

2.13 (Ansible 6)

📝 Development

📌 Development Machine Dependencies

Python 3.9 or greater
Docker

📌 Development Dependencies

Development Dependencies are defined in a pip requirements file named requirements-dev.txt. Example Installation Instructions for Linux are shown below:

# "optional": create a python virtualenv and activate it for the current shell session
$ python3 -m venv venv
$ source venv/bin/activate

$ python3 -m pip install -r requirements-dev.txt

ℹ️ Ansible Role Development Guidelines

Please take a look at my Ansible Role Development Guidelines.

If interested, I’ve also written down some General Ansible Role Development (Best) Practices.

🔢 Versioning

Versions are defined using Tags, which in turn are recognized and used by Ansible Galaxy.

Versions must not start with v.

When a new tag is pushed, a GitHub CI workflow () takes care of importing the role to my Ansible Galaxy Account.

🧪 Testing

Automatic Tests are run on each Contribution using GitHub Workflows.

The Tests primarily resolve around running Molecule on a varying set of linux distributions and using various ansible versions.

The molecule test also includes a step which lints all ansible playbooks using ansible-lint to check for best practices and behaviour that could potentially be improved.

To run the tests, simply run tox on the command line. You can pass an optional environment variable to define the distribution of the Docker container that will be spun up by molecule:

$ MOLECULE_DISTRO=ubuntu2204 tox

For a list of possible values fed to MOLECULE_DISTRO, take a look at the matrix defined in .github/workflows/ci.yml.

🐛 Debugging a Molecule Container

Run your molecule tests with the option MOLECULE_DESTROY=never, e.g.:

$ MOLECULE_DESTROY=never MOLECULE_DISTRO=ubuntu1604 tox -e py3-ansible-5
...
  TASK [ansible-role-pip : (redacted).] ************************
  failed: [instance-py3-ansible-5] => changed=false
...
 ___________________________________ summary ____________________________________
  pre-commit: commands succeeded
ERROR:   py3-ansible-5: commands failed

Find out the name of the molecule-provisioned docker container:

$ docker ps
30e9b8d59cdf   geerlingguy/docker-debian10-ansible:latest   "/lib/systemd/systemd"   8 minutes ago   Up 8 minutes                                                                                                    instance-py3-ansible-5

Get into a bash Shell of the container, and do your debugging:

$ docker exec -it 30e9b8d59cdf /bin/bash

root@instance-py3-ansible-2:/#
root@instance-py3-ansible-2:/# python3 --version
Python 3.8.10
root@instance-py3-ansible-2:/# ...

Tip

If the failure you try to debug is part of verify.yml step and not the actual converge.yml, you may want to know that the output of ansible’s modules (vars), hosts (hostvars) and environment variables have been stored into files on both the provisioner and inside the docker machine under: * /var/tmp/vars.yml * /var/tmp/hostvars.yml * /var/tmp/environment.yml grep, cat or transfer these as you wish!

Tip	You may also want to know that the files mentioned in the admonition above are attached to the GitHub CI Artifacts of a given Workflow run. This allows one to check the difference between runs and thus help in debugging what caused the bit-rot or failure in general.

After you finished your debugging, exit it and destroy the container:

root@instance-py3-ansible-2:/# exit

$ docker stop 30e9b8d59cdf

$ docker container rm 30e9b8d59cdf
or
$ docker container prune

🐛 Debugging installed package versions locally

Although a standard feature in tox 3, this now only happens when tox recognizes the presence of a CI variable. For example:

$ CI=true tox

🧃 TIP: Containerized Ideal Development Environment

This Project offers a definition for a "1-Click Containerized Development Environment".

This Container even enables one to run docker containers inside of it (Docker-In-Docker, dind), allowing for molecule execution.

To use it:

Ensure you fullfill the the System requirements of Visual Studio Code Development Containers, optionally following the Installation-Section of the linked page section.
This includes: Installing Docker, Installing Visual Studio Code itself, and Installing the necessary Extension.
Clone the project to your machine
Open the folder of the repo in Visual Studio Code (File - Open Folder…).
If you get a prompt at the lower right corner informing you about the presence of the devcontainer definition, you can press the accompanying button to enter it. Otherwise, you can also execute the Visual Studio Command Remote-Containers: Open Folder in Container yourself (View - Command Palette → type in the mentioned command).

Tip	I recommend using `Remote-Containers: Rebuild Without Cache and Reopen in Container` once here and there as the devcontainer feature does have some problems recognizing changes made to its definition properly some times.

Note	You may need to configure your host system to enable the container to use your SSH/GPG Keys. The procedure is described in the official devcontainer docs under "Sharing Git credentials with your container".

🍪 CookieCutter

This Project shall be kept in sync with the CookieCutter it was originally templated from using cruft (if possible) or manual alteration (if needed) to the best extend possible.

Official Example Usage of cruft update

🕗 Changelog

When a new tag is pushed, an appropriate GitHub Release will be created by the Repository Maintainer to provide a proper human change log with a title and description.

ℹ️ General Linting and Styling Conventions

General Linting and Styling Conventions are automatically held up to Standards by various pre-commit hooks, at least to some extend.

Automatic Execution of pre-commit is done on each Contribution using pre-commit.ci*. Pull Requests even automatically get fixed by the same tool, at least by hooks that automatically alter files.

Note

Not to confuse: Although some pre-commit hooks may be able to warn you about script-analyzed flaws in syntax or even code to some extend (for which reason pre-commit’s hooks are part of the test suite), pre-commit itself does not run any real Test Suites. For Information on Testing, see 🧪 Testing.

Tip

Nevertheless, I recommend you to integrate pre-commit into your local development workflow yourself.

This can be done by cd’ing into the directory of your cloned project and running pre-commit install. Doing so will make git run pre-commit checks on every commit you make, aborting the commit themselves if a hook alarm’ed.

You can also, for example, execute pre-commit’s hooks at any time by running pre-commit run --all-files.

🗒 Changelog

Please refer to the Release Page of this Repository for a human changelog of the corresponding Tags (Versions) of this Project.

Note that this Project adheres to Semantic Versioning. Please report any accidental breaking changes of a minor version update.

⚖️ License

LICENSE

MIT License

Copyright (c) 2023, Billy Vierra

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

bvierra/ansible-role-proxmoxserver

ansible-role-proxmoxserver

🔎 Metadata

📌 Requirements

📜 Role Variables

📜 Facts/Variables defined by this role

🏷️ Tags

👫 Dependencies

📚 Example Playbook Usages

🧪 Tested Distributions

🧪 Tested Ansible versions

📝 Development

📌 Development Machine Dependencies

📌 Development Dependencies

ℹ️ Ansible Role Development Guidelines

🔢 Versioning

🧪 Testing

🐛 Debugging a Molecule Container

🐛 Debugging installed package versions locally

🧃 TIP: Containerized Ideal Development Environment

🍪 CookieCutter

🕗 Changelog

ℹ️ General Linting and Styling Conventions

🗒 Changelog

⚖️ License