I've been walking clients through Puppet to OpenVox moves for a while now, and I'll tell you right up front... the package swap is the easy part. The OpenVox community did a great job keeping it a drop-in replacement, so it's almost never the packages that bite you. It's everything around them.
So, here's the pre-flight checklist I run every time. It's not gospel, and YMMV, but it has saved me more than once.
Inventory first
You can't plan a migration for a fleet you can't describe. Before anything else, I want:
- Server, agent, and PuppetDB versions, plus the oldest agent still checking in. One curl to the DB with an agent's certs gets you the list:
curl -sG --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem --cert /etc/puppetlabs/puppet/ssl/certs/$(hostname -f).pem --key /etc/puppetlabs/puppet/ssl/private_keys/$(hostname -f).pem https://YOUR-DB-HOST:8081/pdb/query/v4 --data-urlencode 'query=inventory[certname, facts.puppetversion] {}'
- Your OS spread. This one matters more than folks think. OpenVox 9 no longer builds packages for EL7, Amazon Linux 2, Debian 11, Fedora 42, or Ubuntu 25.04, so those agents either stay on OpenVox 8 for now, or the OS gets fixed first. (I know, I know... nobody wants to hear the EL7 boxes are the problem. But there it is.)
- Where
serverandca_serverpoint on the agents. A VIP? The CA host directly? A DNS alias somebody set up years ago that nobody remembers? (It's always DNS, right?) - How code gets deployed: r10k, Code Manager if you're coming off PE, or "git pull on the server." No judgment. Okay, a little judgment. 🙂
- How nodes get classified: Hiera plus roles/profiles, an ENC, PE console groups, or regex in site.pp. If you're coming off PE, this is the BIG one, because the console classifier doesn't come with you.
Before the swap
- Back up ALL of
/etc/puppetlabs/on the CA, every compiler, and the DB host, and take a PuppetDB dump. Yes, every time. You'll thank me later. - Find legacy facts and old function calls before they find you. This is crude, but it's an honest first pass:
grep -rnE '\$::?(operatingsystem|osfamily|hostname|fqdn|ipaddress|lsbdistcodename)\b|hiera\(' site/ modules/
- Compile catalogs for your top roles in CI against the target version. Not just "it parses." Actually compile them.
Order of operations
CA first, then compilers one at a time (pull each one out of the load balancer pool while you work on it), then PuppetDB/OpenVoxDB, then agents in waves: a 1–2% canary, then non-prod, then low-risk prod, then the rest.
Upgrade path
Straight from the OpenVox 9 release notes:
- Puppet 7 to OpenVox 7 to 8 to 9
- Puppet 8 to OpenVox 8 to 9
After each wave
- Reload systemd before you trust anything the new packages installed. The swap replaces the unit files on disk, and systemd keeps serving the copies it already loaded until you tell it to look again. On every host you just swapped:
systemctl daemon-reload
Public thanks to Hangover_Act on Reddit, who caught this the same day the post went up and reminded us it had to be in here. They were right, and I left it out. Thank you.
- Check that the agent service is still enabled. Folks have seen the package swap leave the systemd unit disabled, and that gets you a fleet of silently stale nodes. After the reload, a quick
systemctl is-enabled puppet(andsystemctl enable --now puppetwhere needed) takes care of it. - Watch for agents that stop reporting, not just agents that fail. A failed run yells at you. A node that quietly stops checking in doesn't say a word.
Happy Puppeting!