diff --git a/_data/nav/openvox_9x.yml b/_data/nav/openvox_9x.yml index 544df48fa..9c6b69e40 100644 --- a/_data/nav/openvox_9x.yml +++ b/_data/nav/openvox_9x.yml @@ -37,6 +37,8 @@ link: "install_osx.html" - text: What gets installed and where (agent) link: "install_what_and_where.html" + - text: Upgrading from OpenVox 8 to 9 + link: "upgrade_major.html" - text: Upgrading OpenVox 9 link: "upgrade_minor.html" - text: Configuration diff --git a/docs/_openvox_9x/upgrade_major.md b/docs/_openvox_9x/upgrade_major.md new file mode 100644 index 000000000..d308e22ec --- /dev/null +++ b/docs/_openvox_9x/upgrade_major.md @@ -0,0 +1,141 @@ +--- +layout: default +title: "Upgrading from OpenVox 8 to OpenVox 9" +--- + +OpenVox 9 is a major release, but it does not change the Puppet language. Its focus is updating the platform underneath OpenVox: newer Ruby, OpenSSL, JRuby, and Java, plus the removal of settings and behaviors deprecated in OpenVox 8. Most Puppet code that runs cleanly on OpenVox 8 runs unchanged on OpenVox 9, but review the component upgrades and removals below before upgrading a production deployment. + +This page covers what to check and change before the upgrade. For the package mechanics of the upgrade itself, see [Upgrading OpenVox 9](upgrade_minor.html). + +> **OpenVox 9 is in prerelease.** Details on this page can still change before the stable 9.0.0 release. See the [release notes](release_notes.html) and [known issues](known_issues.html) for the current state of the prerelease builds. + +## What changes in OpenVox 9 + +The major version bump comes from the underlying components: + +| Component | OpenVox 8 | OpenVox 9 | +| --------- | --------- | --------- | +| Ruby (bundled with `openvox-agent`) | 3.2 | 4.0 | +| 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 | + +See [Component versions in recent releases](component_versions.html) for the exact versions in each release. + +## Before you upgrade + +1. Upgrade your deployment to the latest OpenVox 8 release first and resolve any deprecation warnings in agent and server logs. Most of what OpenVox 9 removes was already deprecated in the 8.x series. +2. Read the release notes for each component: [OpenVox 9](release_notes.html), [OpenVox Server 9](/openvox-server/9.x/release_notes.html), [OpenVoxDB 9](/openvoxdb/9.x/release_notes.html), and [OpenFact 6](/openfact/6.x/release_notes.html). Each links to the GitHub release page with the full list of changes. +3. Check that packages exist for your platforms on the [supported platforms](supported_platforms.html) page. OpenVox Server 9 and OpenVoxDB 9 no longer publish packages for Debian 11 and 12, which only provide Java 17, and OpenVox Server 9 also drops Amazon Linux 2. +4. Back up `/etc/puppetlabs/` on your servers and take a database backup of OpenVoxDB with `pg_dump` before starting. + +## Review Ruby code for Ruby 4.0 + +The agent's bundled Ruby moves from 3.2 to 4.0. Everything that runs inside the agent's Ruby must be compatible with Ruby 4.0: + +- Custom facts, functions, types, and providers in your modules +- Gems you install into the agent with `puppet_gem` or `/opt/puppetlabs/puppet/bin/gem` + +Ruby 4.0 removes APIs that were deprecated during the Ruby 3.x series. A common one in older facts and providers is spawning a subprocess with `Kernel#open` and a pipe argument (`open("|command")`), which no longer works; use `IO.popen` or, better, OpenFact's `Facter::Core::Execution.execute` for fact code. Run your module unit tests on Ruby 4.0 to find problems before the upgrade. + +OpenVox Server 9 bundles JRuby 10.1, which targets the same Ruby 4.0 language level. Ruby code that runs on the server, such as report processors, custom indirector termini, and gems installed with `puppetserver gem`, needs the same review. + +If you install OpenVox as a gem rather than from packages, the `openvox` gem now requires at least Ruby 3.2. + +## Reinstall gems added to the agent's Ruby + +Gems are installed into a directory named after the Ruby minor version, so gems you added to the agent's Ruby on OpenVox 8 live under `/opt/puppetlabs/puppet/lib/ruby/gems/3.2.0/`. OpenVox 9's Ruby 4.0 looks in `/opt/puppetlabs/puppet/lib/ruby/gems/4.0.0/` and does not see them. +The upgrade neither migrates nor removes the old directory, and the gems' command wrappers in `/opt/puppetlabs/puppet/bin/` stay behind, so a tool such as `r10k` installed with `puppet gem install` still appears to exist but fails: + +```console +$ /opt/puppetlabs/puppet/bin/r10k version +.../rubygems.rb:265:in 'Gem.find_spec_for_exe': can't find gem r10k (>= 0.a) with executable r10k (Gem::GemNotFoundException) +``` + +Before upgrading, list what you added so you can put it back afterwards: + +```console +/opt/puppetlabs/puppet/bin/gem list --local +ls /opt/puppetlabs/puppet/lib/ruby/gems/*/gems +``` + +After upgrading, reinstall each gem with `puppet gem install `. Gems that Puppet manages with the `puppet_gem` package provider are reinstalled by the first agent run on OpenVox 9, because the provider no longer finds them; gems installed by hand are not. Once nothing depends on it, the old `3.2.0` gem directory can be deleted. + +Gems installed into OpenVox Server with `puppetserver gem` are not affected: their directory, `/opt/puppetlabs/server/data/puppetserver/jruby-gems`, is not tied to a Ruby version, so they carry over the JRuby 9.4 to 10.1 upgrade. Review them for Ruby 4.0 compatibility as described above. + +## Review custom facts for OpenFact 6 + +`openvox-agent` 9 bundles and requires OpenFact 6, a major version bump from the 5.x series bundled with OpenVox 8. Test your custom and external facts against OpenFact 6. The changes most likely to affect fact code: + +- OpenFact 6 requires Ruby 3.0 or later, which the agent's Ruby 4.0 satisfies; fact code that also runs elsewhere needs the same floor. +- `Facter::Core::Execution.exec`, `Facter::Util::Resolution.exec`, and `Facter::Util::Resolution.which` now log a deprecation warning ahead of removal. Use `Facter::Core::Execution.execute` and `Facter::Core::Execution.which`. +- The `time_limit` and `limit` option keys for `execute` are deprecated aliases; use `timeout`. +- The deprecated `ldapname` fact option is removed. +- When a fact calls a bare command name, OpenFact now also searches `/opt/puppetlabs/bin`, so facts that call `puppet`, `puppetserver`, or `puppetdb` resolve when the agent runs as a service. + +See the [OpenFact 6 release notes](/openfact/6.x/release_notes.html) for the full list. + +## Deferred functions are preprocessed again by default + +OpenVox 8 evaluated deferred functions (functions called through the `Deferred` data type) lazily, at the moment the catalog applied the resource that used them. OpenVox 9 returns to the older behavior of resolving all deferred functions up front, before catalog application starts. + +This matters if a deferred function depends on something the same run puts in place, for example a package or library installed earlier in the catalog. Under preprocessing, the function runs before that prerequisite exists and the run fails. If you depend on lazy evaluation, set `preprocess_deferred = false` in the agent's `puppet.conf` to keep the OpenVox 8 behavior. + +## Report storage is now opt-in + +The default for the [`reports` setting](configuration.html#reports) changed from `store` to `none`, so an upgraded server stops writing YAML report files to the reports directory. If you rely on stored reports, or on tooling that reads them, set the value explicitly on the server: + +```ini +[server] +reports = store +``` + +Report submission from agents is unchanged; only the server-side default for processing them changed. + +## Agents must have an explicit server setting + +OpenVox 8 agents fell back to contacting a host named `puppet` when no server was configured. OpenVox 9 removes this fallback. As of 9.0.0-rc1 an agent run with no `server` setting fails, whether it runs as root or not: + +```text +Error: OpenVox does not default to `server=puppet` as of version 9.0. Please update your configuration appropriately by providing a specific server of your choice. +``` + +(The 9.0.0 beta releases only logged a deprecation warning for root.) If any nodes still rely on the fallback, set the [`server` setting](configuration.html#server) explicitly before upgrading them: + +```console +puppet config set server openvox.example.com --section main +``` + +## Removed settings + +These settings are gone in OpenVox 9. Remove them from `puppet.conf` and from any scripts or tooling that reference them before you upgrade: + +- `configprint`: use `puppet config print ` instead of `puppet agent --configprint `. +- `pluginsync`: plugins always sync; the setting had been deprecated since Puppet 6. +- `data_binding_terminus` and `environment_data_provider`: the classic `hiera` indirector and pluggable data bindings are removed. Automatic class parameter lookup always uses the modern lookup system. If you still maintain a Hiera 3 `hiera.yaml`, see [Migrating your Hiera configuration](hiera_migrate.html); Hiera 3 backends keep working through a version 5 `hiera.yaml`. + +## Other removals + +- The `regsubst` function no longer accepts its deprecated encoding argument. +- The `pe_serverversion` fact is removed. +- The `zone_core` module for Solaris zones is no longer vendored with the agent. Install [`puppetlabs-zone_core`](https://forge.puppet.com/modules/puppetlabs/zone_core) from the Forge if you manage `zone` resources. +- The agent runtime no longer ships Java keystore files, and legacy PAL script-evaluation APIs are removed. See the [release notes](release_notes.html) if you depend on either. + +## Server and OpenVoxDB changes + +- **Java:** OpenVox Server 9 and OpenVoxDB 9 drop support for Java 17. Install Java 21 or 25 before upgrading the server packages. +- **Filebucket reads need an administrative certificate:** the default `auth.conf` in OpenVox Server 9 lets agents store filebucket content (`HEAD` and `PUT`) but restricts reading it back (`GET` and `POST`) to client certificates with the `pp_cli_auth: "true"` extension. + If you restore or diff filebucket content remotely with an ordinary agent certificate, add an `auth.conf` rule for that certname before upgrading. See [auth.conf](/openvox-server/9.x/config_file_auth.html). +- **Jetty 12:** both OpenVox Server 9 and OpenVoxDB 9 move to Jetty 12. If you customized `webserver` settings beyond host and port, review them after the upgrade. + For OpenVoxDB, if you upgrade from 8.14.0 or earlier and have modified `/etc/puppetlabs/puppetdb/bootstrap.cfg`, the package manager keeps your copy and the service fails to start because it still loads `jetty10-service`; the [OpenVoxDB 9 release notes](/openvoxdb/9.x/release_notes.html) have the fix. +- **PostgreSQL:** OpenVoxDB 9 requires PostgreSQL 14 or later, the same minimum as the last 8.x releases. +- **Packaging:** the `openvox-server` 9 package requires `openvox-agent` 9 on the same host, so the server host's agent upgrades along with it. +- **Service management:** OpenVox Server 9 removes the `puppetserver start` and `puppetserver stop` subcommands; systemd starts the JVM directly from the unit file. Replace any scripts that call them with `systemctl start puppetserver` and `systemctl stop puppetserver`. `systemctl reload puppetserver` still works on every platform. + +## Test, then upgrade + +1. Run your module unit tests on Ruby 4.0 and fix any failures. +2. Validate your manifests with `puppet parser validate`. +3. Stand up an OpenVox 9 server in a test environment, point test agents at it, and compare `puppet agent --test --noop` output against OpenVox 8 for unexpected changes. +4. Upgrade production in the usual order: `openvox-server`, then `openvoxdb` and `openvoxdb-termini`, then agents. OpenVox 8 agents can keep checking in to an upgraded OpenVox 9 server while you roll out agent upgrades. [Upgrading OpenVox 9](upgrade_minor.html) has the package commands. diff --git a/docs/_openvox_9x/upgrade_minor.md b/docs/_openvox_9x/upgrade_minor.md index 905820ded..88f226103 100644 --- a/docs/_openvox_9x/upgrade_minor.md +++ b/docs/_openvox_9x/upgrade_minor.md @@ -7,8 +7,9 @@ Use this page for routine OpenVox 9 upgrades and for in-place migrations from th legacy Puppet packages to OpenVox packages. > **OpenVox 9 is a major version** and includes breaking changes relative to OpenVox -> 8 — see the [release notes](./release_notes.html) before upgrading a production -> host. The steps below cover the mechanics of the upgrade itself. +> 8 — see [Upgrading from OpenVox 8 to 9](upgrade_major.html) and the +> [release notes](./release_notes.html) before upgrading a production host. The +> steps below cover the mechanics of the upgrade itself. The main migration rule is that a host cannot have both Puppet and OpenVox packages installed at the same time. Back up `/etc/puppetlabs/` before you start.