Ansible for Proxmox VE

Hands-on workshop · 3.5 h · beginner level

Author

credativ GmbH

About this workshop

Three and a half hours of hands-on automation: starting with three unconfigured Proxmox VE nodes, forming a cluster with Ansible, and automating recurring operational tasks (repositories, storage, service accounts, API tokens, virtual machines, backups).

The workshop assumes no prior Ansible experience. If you have written playbooks before, module 01 is a quick recap and you can focus on the optional exercises.

Your lab

Your personal lab. Every participant has an identical, isolated set.
Machine Role Address (management) Access
desktop Linux desktop, your Ansible control node 192.168.0.254 the VDI session you are in
pve01 Proxmox VE node 1, later the cluster primary 192.168.0.1 SSH from desktop, GUI on :8006
pve02 Proxmox VE node 2 192.168.0.2 SSH from desktop, GUI on :8006
pve03 Proxmox VE node 3 192.168.0.3 SSH from desktop, GUI on :8006
  • Proxmox VE version: 9, based on Debian 13 “trixie”. Package sources are in the deb822 .sources format.
  • Lab network: 192.168.0.0/24. The desktop is also the gateway for it, so the nodes reach the internet through the machine you are working on.
  • Host names and addresses are the same for every participant, which is why the starter project ships a ready-made inventory.
  • Shared NFS library: nas01.training.credativ.de:/mnt/pool01/shared, holding ISOs, container templates and the cloud image. You attach it yourself in module 05.
  • Proxmox VE login: user root, password password123, identical on all three nodes. The same credentials work for SSH and for the web GUI (realm Proxmox VE authentication server). It is a throwaway password in a throwaway lab.
  • SSH: deploy.sh generates a key and installs it on all three nodes, so neither ssh nor Ansible prompts for anything. The password above is still the fallback, and exercise 01 uses it once on purpose.
  • Working directory on desktop: ~/ansible-proxmox, created by deploy.sh from the starter project. The virtualenv with ansible-core, community.proxmox and proxmoxer is in ~/ansible-venv/bin and already on your PATH.

The nodes are installed but not configured: no cluster, enterprise repository still active, no extra storage, no users. That is on purpose. You build all of it with Ansible.

Presenting

One deck for the whole workshop: slides.qmd. That is what you present from; the module decks below are the same content, split up for handing out single topics.

quarto preview courses/ansible-proxmox/slides.qmd   # fullscreen: f, speaker notes: s
./slides-pdf.sh trainer                             # PDF export of every deck

Modules

Every module is self-contained and renders its own slides, handout and exercise.
# Module Slides Handout Exercise
00 Welcome & the lab reveal.js — —
01 Ansible in 30 minutes reveal.js HTML · PDF Exercise
02 Preparing the nodes reveal.js HTML · PDF Exercise
03 Forming the cluster reveal.js HTML · PDF Exercise
04 From playbook to role reveal.js HTML · PDF Exercise
05 Operating the cluster reveal.js HTML · PDF Exercise
06 Dynamic inventory reveal.js HTML · PDF Exercise
07 Where to go next reveal.js — —

Plus one cheat sheet covering the whole workshop, and bonus exercises for participants who finish early.

Two Ansible projects ship with this workshop

starter/ is the skeleton participants clone at the beginning. Configuration and inventory are complete (all participants share the same addresses), every playbook is present with the right task names and structure, and each unfinished task is a debug carrying a TODO. It runs successfully from the first minute and changes nothing. This exists so that nobody spends the workshop debugging YAML indentation.

code/ is the finished project: the same files, filled in, plus the pve_node role and the verification suite in code/tests/. Use it to unblock someone, and hand it out afterwards as the take-home artefact.

Timing

Reference schedule.
Block Content Minutes
00 Welcome, goals, lab tour, first SSH login 15
01 Ansible in 30 minutes: inventory, ad-hoc, idempotency 30
02 First playbook: repositories, packages, /etc/hosts, time 30
— Break 10
03 Forming the cluster with Ansible 40
04 From playbook to role: structure, variables, handlers 25
05 Operating the cluster: storage, NFS, users, cloud-init guest, backup 45
06 Dynamic inventory from Proxmox VE 10
07 Wrap-up, next steps, questions 5
Total 210

Trainer notes — running this workshop

Knowledge level & pacing. Ask at the start who has written a playbook before; if more than half raise their hand, compress module 01 to 15 minutes and move the time into module 05. Point everyone at the starter repository so nobody gets stuck on YAML indentation.

Pacing. Modules 01–03 are the spine. If you are behind schedule after the break, cut module 04 to a live walkthrough (no lab) and cut module 06 to a demo. Never cut module 03. Forming the cluster is what the workshop title promises.

Decide up front how much typing you want. Point the room at the starter project in module 00 if the group is mixed or large; let them write the files by hand if they are experienced and the schedule is comfortable. Announce the decision once and clearly: half the room cloning while the other half types costs ten minutes of confusion.

The environment does the heavy lifting. Verify before the session that:

  • desktop has ansible-core 2.17 or newer (required by community.proxmox), plus python3-proxmoxer and python3-requests
  • the collection community.proxmox is installed for the participant user, or the desktop has internet access for ansible-galaxy collection install
  • root SSH from desktop to pve01..3 works with the handed-out password
  • the three nodes are freshly installed, not clustered, and have no guests
  • the starter repository is reachable from the VDI desktops, and its inventory addresses match the environment you hand out

Failure modes to expect live. Host key prompts on the first connection, the enterprise repository failing apt update before module 02 fixes it, and the API becoming briefly unreachable while a node joins the cluster. All three are covered in the material. Use them as teaching moments instead of apologising for them.

Break. Take the break after module 02, not later. Module 03 is the longest block and deserves fresh attention.