Add an OpenVox 8 to 9 upgrade guide to the 9.x docs by miharp · Pull Request #461 · OpenVoxProject/openvox-docs

miharp · 2026-08-27T13:43:37Z

Adds an upgrade-planning page to the 9.x collection, "Upgrading from OpenVox 8 to OpenVox 9", covering what to review before moving a production deployment, alongside the existing package-mechanics page (upgrade_minor). Modeled on the shape of Puppet Core's 8-to-9 guide, with every claim checked against the OpenVox 9 prerelease sources rather than copied.

Part of #456. The page links to the server 9.x, OpenVoxDB 9.x, and OpenFact 6.x release notes and to the server 9.x auth.conf page; #457, #458, and #459 have merged, so every link on the page resolves on master.

What the page covers

Component table: Ruby 3.2 to 4.0, OpenSSL 3.0 to 3.5, OpenFact 5 to 6, JRuby 9.4 to 10.1, Java 21 or 25 (17 dropped), with a link to the component-versions page for exact versions.
Before-you-upgrade checklist: latest 8.x first, per-component release notes, platform coverage (Debian 11/12 dropped for server and OpenVoxDB, Amazon Linux 2 for server), backups.
Ruby 4.0 review guidance for custom facts, functions, types, providers, and agent- or server-installed gems, including the Kernel#open pipe removal.
OpenFact 6 changes that affect fact code (Ruby 3.0+, exec/which deprecations, time_limit/limit aliases, ldapname removal, /opt/puppetlabs/bin search path).
Behavior changes verified in the prerelease sources: deferred functions preprocessed by default again (openvox#462), report storage opt-in (openvox#583), and the server setting fallback (openvox#536). As of 9.0.0-rc1 an agent with no server setting fails whether it runs as root or not; the page quotes both messages, since the non-root text differs.
Removed settings (configprint, pluginsync, data_binding_terminus, environment_data_provider) and other removals (regsubst encoding argument, pe_serverversion, zone_core, Java keystores, legacy PAL APIs).
Server and OpenVoxDB changes: Java 21/25, the filebucket read-authorization change (openvox-server#549), Jetty 12 with the OpenVoxDB bootstrap.cfg jetty10-service pitfall for upgrades from 8.14.0 or earlier, PostgreSQL 14 minimum, and the openvox-server and openvoxdb packages' dependency on agent 9 (openvoxdb-termini is unversioned, verified against the published rc1 apt and yum metadata).
Test-then-upgrade checklist and upgrade order, including the switch to the openvox9-release repository package (on Debian and Ubuntu openvox8-release has to be removed first, since both ship /etc/apt/preferences.d/openvox-release.pref; on EL they coexist). The 9.x upgrade_minor page points at that step.

Also adds the nav entry (before "Upgrading OpenVox 9") and cross-links the page from the breaking-changes callout in upgrade_minor.

File	Change
`upgrade_major.md`	New page
`upgrade_minor.md`	Callout links to the new page; the Linux package section points at the repository-switch step
`openvox_9x.yml`	Nav entry

Checks

markdownlint clean; jekyll build clean; the page renders under /openvox/9.x/upgrade_major.html and the nav and upgrade_minor callout link to it. Every cross-collection link resolves now that Add OpenVox Server 9.x docs collection as a preview (latest stays on 8.x) #457, Add OpenVoxDB 9.x docs collection as a preview (latest stays on 8.x) #458, and Add OpenFact 6.x docs collection as a preview (latest stays on 5.x) #459 are merged.
Every testable statement on the page was run against a 9.0.0-rc1 lab (EL9, EL10, Ubuntu 24.04; 62 checks on the server host and 43 per agent, plus an in-place 8.28.1 to rc1 agent upgrade for the gem section): all pass. Four observations from that run are folded into the text: the non-root missing-server message, the removed ldapname option making a fact resolve to nothing rather than raising, a version 3 hiera.yaml still loading with a deprecation warning, and the removed settings being ignored silently where 8 warned. Not testable there and taken from sources only: the dropped Debian 11/12 and Amazon Linux 2 packages, the gem's Ruby floor, module unit tests on Ruby 4, report processors under JRuby 10, and the PAL APIs.
Package facts (release-package coexistence on EL, the apt preferences-file conflict on Debian/Ubuntu, the termini dependency) were checked against the published rc1 packages and repository metadata.

bastelfreak · 2026-09-10T15:07:43Z

+| OpenSSL (bundled with `openvox-agent`) | 3.0 | 3.5 |
+| OpenFact (bundled with `openvox-agent`) | 5.x | 6.x |
+| JRuby (bundled with `openvox-server`) | 9.4 | 10.1 |
+| Java (required by `openvox-server` and `openvoxdb`) | 17 or 21 | 21 or 25 |


Maybe mention that openvox-agent 8 vendored curl, but we dropped that in 9.

bastelfreak · 2026-09-10T15:10:07Z

+   On EL, the two release packages can be installed side by side and the package manager prefers the 9.x packages; remove `openvox8-release` once the host is upgraded.
+
+   ```bash
+   sudo rpm -Uvh https://yum.voxpupuli.org/openvox9-release-el-9.noarch.rpm


Suggested change

sudo rpm -Uvh https://yum.voxpupuli.org/openvox9-release-el-9.noarch.rpm

sudo dnf install https://yum.voxpupuli.org/openvox9-release-el-9.noarch.rpm

let's promote new tools!

Add an upgrade-planning page to the 9.x collection covering what to review before moving a production deployment from OpenVox 8 to 9, alongside the existing package-mechanics page (upgrade_minor): - Component version table: Ruby 3.2 -> 4.0, OpenSSL 3.0 -> 3.5, OpenFact 5.x -> 6.x, JRuby 9.4 -> 10.1, Java 21/25 (17 dropped) - Ruby 4.0 review guidance for custom facts, functions, types, providers, and agent/server-installed gems - Behavior changes verified against the 9.0.0 prerelease sources: deferred functions preprocessed by default again (openvox#462), reports default store -> none (openvox#583), and the server setting fallback deprecation (openvox#536 - root agents still fall back with a warning, non-root runs fail; the code keeps the root fallback in beta2, so the page documents the deprecation rather than a hard removal) - Removed settings (configprint, pluginsync, data_binding_terminus, environment_data_provider) and other removals (regsubst encoding argument, pe_serverversion fact, zone_core module, Java keystores, legacy PAL APIs) - Server/OpenVoxDB notes: Java 17 dropped, Jetty 12, OpenVoxDB Debian 11/12 packages discontinued, openvox-server 9 requires openvox-agent 9 on the same host - Test-then-upgrade checklist and upgrade order Also add the nav entry and cross-link the page from the breaking- changes callout in upgrade_minor. Updated after the server, OpenVoxDB, and OpenFact 6 preview cutovers (OpenVoxProject#457, OpenVoxProject#458, OpenVoxProject#459): per-component release-notes links, OpenVox Server 9 also dropping Debian 11/12 and Amazon Linux 2, the OpenVox Server 9 filebucket read-authorization change (openvox-server#549), the OpenVoxDB bootstrap.cfg jetty10-service pitfall for upgrades from 8.14.0 or earlier, the PostgreSQL 14 minimum, and the concrete OpenFact 6 changes that affect fact code. Part of OpenVoxProject#456 Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

…uide OpenVox Server 9.0.0-rc1 moved to EZbake 4.1.0, which runs the JVM directly from the systemd unit. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

…s an error in rc1 - New section: gems installed into the agent's Ruby live under lib/ruby/gems/3.2.0 and are invisible to OpenVox 9's Ruby 4.0; the old directory and the bin wrappers stay behind, so tools like r10k fail with Gem::GemNotFoundException until reinstalled. puppet_gem-managed gems come back on the first run; hand-installed ones do not. puppetserver gems are unaffected (jruby-gems is not version-specific). - The missing-server paragraph now reflects 9.0.0-rc1, where the run fails with an error for root as well (openvox#623), instead of the beta-era warning. Both verified on a CentOS Stream 9/10 and Ubuntu 24.04 lab on 9.0.0-rc1. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

…nlint Signed-off-by: Michael Harp <mike@mikeharp.com>

OpenVoxDB 9 now requires openvox-agent 9 on the same host and, like the server, runs the JVM directly from the systemd unit, so JAVA_BIN in the init config file is ignored. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

- puppet has no gem subcommand; reinstall gems with /opt/puppetlabs/puppet/bin/gem. - Add the openvox9-release step to the upgrade checklist. On Debian and Ubuntu openvox8-release must be removed first because both packages ship /etc/apt/preferences.d/openvox-release.pref; on EL they coexist. Point the package-commands page at that step. - openvoxdb-termini depends on openvox-agent with no version, so only openvox-server and openvoxdb pull the agent to 9. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

From the rc1 lab run of the upgrade guide: the non-root missing-server error has different text from the root one, a removed ldapname option makes the fact resolve to nothing instead of raising, a version 3 hiera.yaml still loads on 9 with a deprecation warning, and the four removed settings are ignored silently where 8 warned. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

openvox-agent 8 vendors curl (puppet-runtime agent-runtime-8.x includes the curl component); the 9 runtime does not. Install the EL release package with dnf rather than rpm -Uvh. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

miharp force-pushed the docs/openvox8-to-9-upgrade branch 2 times, most recently from 25bf2e7 to 3934834 Compare September 3, 2026 14:07

miharp force-pushed the docs/openvox8-to-9-upgrade branch 7 times, most recently from 72cf95f to 524eaff Compare September 10, 2026 12:45

miharp marked this pull request as ready for review September 10, 2026 12:47

miharp requested a review from a team as a code owner September 10, 2026 12:47

miharp force-pushed the docs/openvox8-to-9-upgrade branch from 524eaff to f4821b4 Compare September 10, 2026 13:02

bastelfreak reviewed Sep 10, 2026

View reviewed changes

miharp force-pushed the docs/openvox8-to-9-upgrade branch from c6e5286 to 3cf70e3 Compare September 10, 2026 15:34

miharp and others added 8 commits September 13, 2026 07:47

Note the removed puppetserver start/stop subcommands in the upgrade g…

f940c9a

…uide OpenVox Server 9.0.0-rc1 moved to EZbake 4.1.0, which runs the JVM directly from the systemd unit. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

Upgrade guide: wrap a long line and label the error fence for markdow…

4772e94

…nlint Signed-off-by: Michael Harp <mike@mikeharp.com>

miharp force-pushed the docs/openvox8-to-9-upgrade branch from cbf8a44 to e773e6f Compare September 13, 2026 11:47

miharp requested a review from bastelfreak September 15, 2026 10:23

Navigation Menu

Uh oh!

Add an OpenVox 8 to 9 upgrade guide to the 9.x docs - #461

Add an OpenVox 8 to 9 upgrade guide to the 9.x docs#461
miharp wants to merge 8 commits into
OpenVoxProject:masterfrom
miharp:docs/openvox8-to-9-upgrade

miharp commented Aug 27, 2026 •

edited

Loading

Uh oh!

bastelfreak Sep 10, 2026

Uh oh!

miharp Sep 15, 2026

Uh oh!

bastelfreak Sep 10, 2026

Uh oh!

miharp Sep 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	sudo rpm -Uvh https://yum.voxpupuli.org/openvox9-release-el-9.noarch.rpm
	sudo dnf install https://yum.voxpupuli.org/openvox9-release-el-9.noarch.rpm

Uh oh!

Conversation

miharp commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What the page covers

Checks

Uh oh!

bastelfreak Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

miharp Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

bastelfreak Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

miharp Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

miharp commented Aug 27, 2026 •

edited

Loading