Add a guide for upgrading from Puppet 7 to OpenVox 8

[miharp]

Adds an upgrade-planning page to the 8.x collection, "Upgrading from Puppet 7 to OpenVox 8", alongside the existing package-mechanics page (upgrade_minor). It follows the shape of the 8 to 9 guide in #461.

Closes #497.

What the page covers

• Choosing a path: Puppet 7 and OpenVox 7 upgrade in place. For Puppet 6 and older the page says to rebuild, points at "Getting started with OpenVox" as the starting point, and does not cover the intermediate versions.
• What changes: a component table (Ruby 2.7 to 3.2, OpenSSL 1.1.1 to 3.0, Facter 4 to OpenFact 5, JRuby 9.3 to 9.4, Java 8, 11, or 17 to 17 or 21, PostgreSQL 11 to 14) and a table of the six settings with new defaults, including whether each one applies on the server or the agent.
• Strict mode: what fails, and that restoring the 7 behavior needs both strict = warning and strict_variables = false. Each puppet.conf snippet on the page has its puppet config set equivalent, and the puppet_conf task is mentioned for many nodes.
• Legacy facts: a table of how each form of reference behaves on 8 in manifests, EPP, ERB, hierarchy paths, and Hiera data values. Some fail, and some resolve to nothing without a message.
• Finding legacy facts: the puppet-lint legacy_facts check for manifests and YAML, its limits, a pointer to rowlf for the forms puppet-lint skips, a grep for templates and .eyaml files, and the 11 facts the check can't rewrite with what to build each one from.
• Hiera 3, PSON, Ruby 3.2 (including keeping server-side Ruby at 3.1 syntax for JRuby 9.4), agent gems, and other changed defaults.
• Server and OpenVoxDB: the direct package replacement, the default-Java trap, which configuration files are kept or replaced (including the install hook that resets the server paths in puppet.conf, which the server process doesn't read because puppetserver.conf sets them, and an edited OpenVoxDB bootstrap.cfg that still loads jetty9-service), the OpenVoxDB schema migration and PostgreSQL versions, and a "Mixed versions" section that states the order: server first, then OpenVoxDB and the termini, then agents. The same order is in "Before you upgrade" and in the final upgrade steps.
• Test, then upgrade: rehearsing the 8 defaults on 7, comparing catalogs, updating modules to a set that declares Puppet 8 and still supports 7 (stdlib 9, concat 9, apt 9.1, inifile 6.1, firewall 6, chosen so their stdlib requirements agree), switching repositories and removing version pins, the upgrade order (server and OpenVoxDB in the same window, then agents; compilers one at a time; a full systemctl restart puppetserver afterwards; theforeman/puppet's version parameter as a way to upgrade agents from a class), and switching to puppet/openvoxdb after OpenVoxDB is on 8, since that module requires OpenVox 8.19.

File	Change
docs/_openvox_8x/upgrade_major.md	New page
_data/nav/openvox_8x.yml	Nav entry, before "Upgrading OpenVox 8"
docs/_openvox_8x/upgrade_minor.md	Pointer to the new page
docs/_openvox_8x/release_notes.markdown	Link under "If you're upgrading from Puppet Open Source"
docs/_ecosystem_8x/devkit/linting.md	Pointer to the legacy_facts check

Where the page differs from the upstream notes

The Puppet 8 release notes and compatibility page were the starting point, and the page was also checked against the Puppet Core 8 upgrade section (order, pins, restart, downtime), which added the items in parentheses above. The lab disagreed with them in four places, and the page follows the lab:

Upstream says	On OpenVox 8.29.0
$facts['osfamily'] fails under strict mode	No error. The value is undef.
A hierarchy path that interpolates an undefined variable fails	A warning, and the hierarchy level is skipped
File.exists? is removed	OpenVox defines it when it loads. It fails only under facter on its own.
ERB.new with positional arguments is not allowed	Works on Ruby 3.2, with a deprecation warning. Left off the page.

Checks

• markdownlint is clean and jekyll build is clean. Every link and anchor on the page resolves, and no code block or table overflows.
• Behavior was run on openvox-agent 8.29.0 (Ubuntu 24.04 package) and OpenVox Server 8.16.0, with agent 7.37.2 and server 7.18.2 as the baseline. That covers the setting defaults, strict mode, every row of the legacy facts table, Hiera 3, PSON, reports, custom fact errors, and 7 and 8 agents against 7 and 8 servers.
• Package steps were run on Ubuntu: puppet-agent 7.34.0 replaced by openvox-agent 8.29.0, openvox-agent 7.37.2 upgraded to 8.29.0, and the openvox7-release and openvox8-release conflict.
• The server side was run on Ubuntu 22.04 against PostgreSQL 14: puppetserver 7.17.3, puppetdb 7.20.1, and puppetdb-termini 7.20.1 replaced by the OpenVox 8.16.0 packages in one apt-get install. That covered the Java 11 startup failure and its fix, which configuration files were kept or replaced, the dpkg conffile prompt in an unattended run, the OpenVoxDB schema migration with the existing node and report intact, and puppetserver gem installs carrying over. EL 9 package metadata was checked with dnf repoquery (Conflicts and Obsoletes on the Puppet packages, java-17-openjdk-headless), but no EL upgrade was run.
• The puppet-lint commands on the page were run as written with puppet-lint 5.1.1.
• The module versions in the update step come from the Forge API, including each release's stdlib dependency range so the set installs together. The stdlib function removals are from the stdlib 9.0.0 changelog. The puppet/openvoxdb requirement and its PuppetDB 8 floor are from its metadata and README.
• The puppet.conf install hook (task_postinst_deb_install in the server package's install.sh) and the bootstrap.cfg service rename (jetty9-service in 7.21.2, jetty-service in 8.16.0) were checked in the package and source.
• The page also points at rowlf, which was run at commit c5ac59f6 against the same sample files. It handles the forms puppet-lint skips. One wrong fact mapping (swapfree_mb and swapsize_mb) was found and is written up for the author in a gist.

Not run, and taken from the docs or upstream notes:

• RPM platforms, beyond the package metadata
• systemd behavior on the server hosts, since the lab ran the services in the foreground
• A large OpenVoxDB migration; the lab database was nearly empty
• Deferred function ordering
• The zones replacement, which needs a Solaris host

PostgreSQL versions

The page states that OpenVoxDB 8 supports PostgreSQL 14 or later, starts on 11 through 13 with an error logged, and refuses to start on anything older. That comes from the OpenVoxDB 8.16.0 source: oldest-allowed-db is [11 0] and oldest-supported-db is [14 0] in src/puppetlabs/puppetdb/scf/storage.clj, and verify-database-version in src/puppetlabs/puppetdb/cli/services.clj throws below the first and logs PostgreSQL {0}.{1} is unsupported below the second.

Assisted by Claude.

[cvquesty]

LGTM

[bastelfreak]

Does it hell or confuse people if we mention that a 7 agent can also speak to openvox 9 server?

[miharp]

hum, my thinking is jumping from 7->9 is "not supported", and definitely not something I tested.

[bastelfreak]

In situations where we recommend config options, I always like to pitch puppet config set... and the puppet_conf task. Both are very helpful but node widely known. Also theforeman/puppet is a great module to manage the config with openvox.

[miharp]

Agreed, I'll add puppet config set and the puppet_conf task next to the puppet.conf snippets, and mention theforeman/puppet in the agent step. It does a lot, so I'd keep it as an option rather than the recommendation.

The real gap is a puppetlabs-puppet_agent equivalent: a class that switches the release package and upgrades the agent, on Linux, Windows, and macOS. theforeman/puppet doesn't manage the repo and openvox_bootstrap is tasks only. A class in openvox_bootstrap seems the cleanest fix; happy to open an issue there if that makes sense.

[miharp]

One correction to what I wrote: the puppet_conf task is the separate puppetlabs-puppet_conf module (3.0.0), not part of puppet_agent. Both are on the page now.

[jay7x]

JFYI, there is also openvox_bootstrap::configure task available: https://github.com/voxpupuli/puppet-openvox_bootstrap/blob/main/tasks/configure.json.

[miharp]

Thanks, added it next to puppet_conf, with a note that it starts and enables the agent service by default.

[bastelfreak]

My memory here is a bit weak. I think that plugin only covers some legacy facts. If they are written as top scope variable, we need https://github.com/voxpupuli/puppet-lint-topscope-variable-check as well?

[miharp]

legacy_facts does cover the top-scope form: it flags $::osfamily and $facts['osfamily'] and rewrites both (tested with 5.1.1). The topscope-variable-check is about $::module::var inside classes; on a fact its fix would produce bare $osfamily, which is the one form nothing lints. Strict mode catches that one at compile time, and the page says so.

[lollipopman]

Rowlf has support for unscoped facts, e.g. $osfamily, if you pass the -u flag. It will also try to keep track of variables that were declared in Puppet code with the same name as a puppet fact, to avoid clobbering them in ERBs.

[bastelfreak]

There is also a lint_fix rake task for autofix.

[miharp]

Added. Both lint and lint_fix use **/*.pp, so YAML still needs puppet-lint run directly.

[bastelfreak]

Nitpick: jruby rim openvox server 8 is only compatible wth ruby 3.1. So if people configure rubocop to lint for ruby 3.2, and they have a ruby function, the server might fail to parse it. The voxpupuli-test gem provides a proper rubocop config and rake tasks and lints for ruby 3.1.

[bastelfreak]

Ah OK, it's Linde mentioned below 😅

[miharp]

Added a sentence: keep server-side code at 3.1 syntax, rubocop targeting 3.2 can rewrite it into something the server can't load. One correction on voxpupuli-test: its rubocop.yml in v14.0.0 sets TargetRubyVersion: 2.6, with a comment about JRuby 9.3, so it's safe for 3.1 by being older, not because it targets 3.1.