How a Puppet Enterprise to OpenVox migration starts and what it involves
If a Puppet Enterprise renewal, support deadline or licensing change is forcing the decision, the core Puppet language and your existing code carry over to OpenVox, while the Enterprise console, orchestration and vendor support must be replaced or arranged separately. Vox Pupuli states that OpenVox 8.11 is functionally equivalent to Puppet, with the same command names and configuration paths, differing mainly in help text and man pages. Most of the effort therefore sits in packaging, in the Enterprise tooling around the code and in the cutover plan, while your manifests and modules usually move over unchanged.
The work usually falls to platform engineers from the in-house Puppet team, who already know the control repository, the module layout and the agent fleet. Effort is driven by two counts. Each managed node needs its Puppet agent replaced with OpenVox, which is routine but must be repeated across the fleet. Each server, including the Puppet Server and OpenVoxDB with its PostgreSQL database, needs a planned cutover, typically in a maintenance window. Before anything else, build a complete inventory of nodes and servers, including Windows and macOS agents, and confirm with your team which Enterprise features, such as console dashboards or role-based access, each group depends on.
Two constraints set the sequence. Puppet and OpenVox cannot be installed on the same system, and OpenVox's install documentation tells Puppet Enterprise users to run the puppet-enterprise-uninstaller script on each node before installing OpenVox. Back up the whole /etc/puppetlabs tree first, as the documentation strongly advises, and test a restore on a non-production host. After the uninstall, OpenVox packages install from the openvox8-release repository package and keep existing configuration files, so confirm that certificates, the certificate authority and Hiera settings survive on a pilot node before you change production. The OpenVox installation guide lists the exact packages for each platform.
Which Puppet Enterprise capabilities map cleanly to OpenVox and which need rework
This table maps each Puppet Enterprise component to its OpenVox counterpart and marks whether the move is clean, needs checking or leaves a gap. Read the middle column first, then use the notes to decide what to test in your own environment before cutting over. The main takeaway is that agents, server and code carry over most directly, while the console, classifier, RBAC and Orchestrator need replacement work.
| Capability | OpenVox position | What to verify or rework |
|---|---|---|
| Agent and server | Clean. OpenVox 8.11 is documented as functionally equivalent to Puppet, with the same command names and configuration paths. | Confirm the agent and server versions you plan to install match your module and Ruby or Java requirements, and test catalog compilation on a staging server first. |
| Code, modules and Hiera | Clean in principle. Existing configuration files are kept during the package change. | Run your control repository through a test environment. Check modules that depend on Puppet Enterprise-only features or on PE-specific classes. |
| Certificates and CA | Clean in principle. The CA and agent certificates move with the /etc/puppetlabs tree. | Back up the whole /etc/puppetlabs tree before starting. Confirm that agents still trust the CA after the server package change. |
| PuppetDB-equivalent (OpenVoxDB) and reports | Needs checking. OpenVoxDB installs as a separate package with its termini. | Confirm that your reports, exported resources and queries work against OpenVoxDB. Plan how existing PuppetDB data is handled, since it is not automatically carried over by the package change. |
| PE console | Gap. OpenVox does not document a direct console replacement in the install guidance. | Identify who uses the console and for what. Choose a replacement for dashboards and reporting, or accept command-line and report-based workflows. |
| Node classifier and RBAC | Rework. Enterprise node groups and role-based access are not part of the documented OpenVox packages. | Export your node group rules and access policies. Rebuild classification with Hiera, roles and profiles, and define access with your existing identity and Git controls. |
| Orchestrator and live management | Rework. OpenBolt ships with OpenVox for task and plan execution, but it is not a drop-in replacement for the Enterprise Orchestrator. | Inventory the Orchestrator jobs, scheduled tasks and API calls. Port them to OpenBolt or your automation tooling and test each one. |
| Puppet Enterprise support | Gap. OpenVox is community maintained, and vendor support is not included. | Decide who will handle upgrades, security fixes and production incidents. Ask any outside partner for a written scope before migration. |
What data, certificates and integrations move, and which need rebuilding
A Puppet Enterprise to OpenVox move carries over more than most teams expect, but the console-dependent pieces do not follow the files. Use the cards below to sort what travels with the /etc/puppetlabs tree and the control repository from what must be rebuilt on the OpenVox side.
Back up the whole /etc/puppetlabs tree
OpenVox's install documentation strongly advises backing up the entire /etc/puppetlabs tree before any package change. This tree holds the server and agent configuration, the certificate authority data and the settings that PE wrote during installation. Take the backup before running the uninstaller on any node, store it off the node, and test that you can restore a single file from it. Confirm the exact backup scope with the OpenVox install documentation for your package set.
Keep existing configuration files on install
OpenVox packages keep existing configuration files when they replace legacy Puppet packages, so puppet.conf and related settings are not reset by the package install. Review each retained file against what OpenVox expects, especially server-side settings tied to PE components. Diff the files after installation and record any value you changed on purpose.
Move the control repository code
Environment code, Hiera data and modules live in your control repository and on the server's code directory, and they are not part of the PE console state. Move them as Git history rather than copying directories, so environment branches and deploy steps survive. Run each environment against a test node on OpenVox before you point production agents at it. Language and module behavior are documented to be compatible, so failures usually come from PE-specific modules or settings, not from the core language.
Keep the CA and agent certificates
Reusing the existing certificate authority and agent certificates avoids re-signing every node during cutover. Certificate handling is the step most likely to break agent check-ins, so verify it before moving any production node. Confirm with the OpenVox install documentation whether the CA data under the backed-up tree is carried forward as-is for your topology. Keep a copy of the CA private key in a protected location until the cutover is verified.
Rebuild console-dependent node classification
Node groups, pinned node assignments and classification rules are managed through the PE console and are not a file set that the OpenVox server reads. Export the group definitions from the console to a record you control, then recreate them as code, for example in Hiera, site.pp or an external node classifier you operate. Treat this as a rebuild task with its own test plan, since a missed group silently removes classes from nodes.
Rebuild reporting, dashboards and orchestration jobs
PE console dashboards, reporting views, RBAC users and orchestrator jobs have no direct import path into OpenVox, so each needs a named replacement. Decide which reports you still need, such as run failures and compliance drift, and rebuild those on OpenVoxDB and your chosen dashboard tool. Orchestration jobs can be redone with OpenBolt, which the OpenVox packages include. Confirm the current OpenVoxDB and OpenBolt feature set with the install documentation before you commit to a replacement.
The migration sequence from inventory to decommissioning Puppet Enterprise
This sequence moves Puppet Enterprise nodes and servers to OpenVox in an order that keeps a working rollback path at every stage. Each step closes with a written record, so the team can see what has moved and what remains on Puppet Enterprise.
Inventory nodes, servers, modules and groups
The platform team lists every Puppet Enterprise primary server, compiler, PuppetDB and console-managed node group, along with each agent's OS, role and owner. They also export the node classifier groups, the Hiera data and the control repository, and record which modules come from the Forge and which are internal. The output is a node inventory and a classifier export, signed off by the people who own each service. Confirm with your own environment which OS versions are in scope before you plan packages.
Back up and validate the Puppet Enterprise estate
Before any change, the operations team takes a full copy of the whole /etc/puppetlabs tree on each server, the PuppetDB and console databases, and the code directory. They restore the copy on a spare host and confirm that the certificate authority, the code and the classifier data load without errors. OpenVox's install documentation strongly advises backing up the whole /etc/puppetlabs tree first. The output is a backup set with a restore test record.
Run a pilot in a non-production environment
The team builds a non-production Puppet Enterprise environment that mirrors production modules and a small set of node types. They then rebuild that environment on OpenVox, using openvox-server, OpenVoxDB, openvoxdb-termini and OpenBolt from the Vox Pupuli repositories, and compare catalog compilation and agent runs. Any module that uses console-only features must be found here. The pilot sign-off lists the nodes tested, the differences found and the owner of each fix.
Run a parallel test with OpenVox agents
The team points a small set of test agents at a new OpenVox server with a copy of the code and certificates, while production stays on Puppet Enterprise. They compare reports, facts and catalog output against the Puppet Enterprise results for the same nodes. Because OpenVox 8.11 uses the same command names and configuration paths as Puppet, most differences should appear in reporting and in the features the console provided. The output is a parallel run report that the change board reviews.
Cut over nodes one at a time
For each node, the administrator runs the puppet-enterprise-uninstaller script first, because Puppet and OpenVox cannot be installed on the same system. They then install openvox-agent from the Vox Pupuli repository, keep the existing configuration files, and run a test agent cycle against the new server. Nodes move in small waves, and each wave records the hostname, the time, the result and any rollback taken. The output is a cutover log with a rollback record for every node that failed and returned to service.
Cut over the primary server
Once the node waves are stable, the team moves the primary server role by installing openvox-server and OpenVoxDB on the target host, then migrating the certificate authority, code and data from the validated backup. They confirm that every remaining agent checks in and that catalogs compile. The console and orchestrator functions are replaced by the team's chosen tools at this point. The output is a signed server cutover record and a list of functions still provided by the old console.
Decommission Puppet Enterprise and retain records
After a period agreed with the service owners, the team stops the remaining Puppet Enterprise services and removes the old servers from the network. They keep the final backups under the retention rules of the organization, and archive the cutover logs, the classifier export and the sign-offs for audit. The output is a decommissioning record that confirms no agents still report to Puppet Enterprise, with the retained backup locations listed.
How to run both estates in parallel and cut over without a flag day
A single node can hold either Puppet or OpenVox, never both, so running the two estates side by side means splitting the fleet into groups rather than mixing agents on one host. Each node moves in one step: run the puppet-enterprise-uninstaller script, install the OpenVox agent, then point it at the new server. Before any node is touched, confirm which Puppet Enterprise nodes will stay on the old server, which will move first, and which are the last to go. Keep that grouping in a shared runbook so every change window has a clear owner and a clear list of hosts.
Every node needs its own rollback path. Back up the whole /etc/puppetlabs tree before the uninstaller runs, as the OpenVox install documentation strongly advises, and store the copy off the node so it survives a failed install. Because OpenVox keeps existing configuration files, the backup is the reference for what was there before, not the only way back. Start the cutover with a test group, then a low-risk group of non-critical hosts, and only then production. Pause between groups long enough to review agent reports and failed runs, and set a go or no-go check that someone outside the migration team signs off on.
Keep the Puppet Enterprise server reachable until the last node has moved and reported in. Agents that have not yet migrated still depend on its certificate authority, catalog compiler and reports, so do not decommission or firewall it early. Plan the CA and certificate handling carefully, since certificates and code are the parts most likely to block a move, and confirm with the Vox Pupuli install documentation how each agent will trust the new server before the first production change. Retire the Enterprise console only after the inventory shows no active agents reporting to it and the orchestrator is no longer needed for any scheduled job. Until then, the console is the fastest way to see what the old estate is still doing.
What drives migration cost and duration, and how to keep each one down
This table lists the factors that change the effort of moving from Puppet Enterprise to OpenVox, with the one-time and recurring work each one creates. Use it to scope a pilot and to check that a written quote covers the items that usually add cost late in a project.
| Driver | Why it changes cost or effort | How to keep it down |
|---|---|---|
| Node count and mix | Each Linux, Windows and macOS agent needs its own package, certificate and validation run, and Windows and macOS agents add separate testing paths. | Group nodes by OS and role, migrate in waves, and confirm the agent packages you need from the OpenVox install documentation before scheduling. |
| Custom modules and Hiera data | Modules written against Puppet Enterprise-specific behavior or older language features need review, and large Hiera hierarchies multiply test cases. | Inventory modules and Hiera levels first, run catalog compilation against OpenVox in a pilot environment, and fix only what fails. |
| Console classification and node groups | Groups, classification rules and pinned environments live in the PE console database, so they must be re-created or exported before the console is removed. | Export classification as code where possible, document each node group's purpose, and remove groups that no longer match a real role. |
| Orchestration and scheduled tasks | Orchestrator jobs, Bolt-style automation and scheduled runs built on the PE console need replacement with OpenBolt or other tooling. | List every orchestrator job and its owner, then convert only the jobs that are still used. |
| Reporting and RBAC | PE console reports and role-based access rules are features that OpenVox does not ship as a console, so reporting and access control need a chosen replacement. | Define the reports and access roles auditors and operators actually use, then confirm which open-source dashboards and OpenVoxDB queries cover them. |
| Certificates and CA handling | The certificate authority and agent certificates must be carried over or reissued, and a mistake can cut off nodes from the server. | Back up the whole /etc/puppetlabs tree before any change, test certificate handling on a non-production node, and schedule CA work separately from code changes. |
| Change windows and rollback | Each wave needs an approved window, a rollback path and staff available to verify results, which lengthens calendar time more than technical effort. | Agree windows with change owners early, keep waves small, and keep the Puppet Enterprise uninstaller step for each node documented. |
| One-time work | Covers the pilot, migration of code and data, console replacement design, documentation and training for operators. | Ask the provider to list each item with its deliverable and acceptance criteria in the written scope. |
| Recurring work | Covers OpenVox upgrades, patching, monitoring of the server and OpenVoxDB, and any support arrangement you put in place yourself. | Ask who performs upgrades, how often they are planned, and what support response you must arrange with a third party. |
What usually goes wrong in a Puppet Enterprise to OpenVox move and how to prevent it
Most failed Puppet Enterprise to OpenVox moves fail on preparation rather than on the new packages themselves. The risks below cluster around three areas: recovery, trust between nodes and servers, and what the Enterprise console quietly did for you. Each card names the failure and a check to run before cutover.
Skipping the configuration backup
OpenVox's install documentation advises backing up the whole /etc/puppetlabs tree before any change, and existing configuration files are kept on install. Without a full copy, a failed uninstall or a mistyped path leaves you with no fallback for puppet.conf, hiera.yaml, the CA directory or node certificates. Before any change, confirm the archive restores on a scratch host and that it includes the CA and SSL directories, not only the code.
Running the uninstaller on the wrong host
The OpenVox install guidance tells Puppet Enterprise users to run the puppet-enterprise-uninstaller on each node before installing OpenVox. On a compiler, a PuppetDB host or the primary server, running it on the wrong machine removes services other nodes still depend on. Maintain a written inventory that labels each host by role, run the uninstaller only on hosts in the approved cutover window, and check each role before its successor is installed.
Certificate and CA mismatches
Agents trust a server through the CA and certificates created under Puppet Enterprise. If the new server is built with a fresh CA, or DNS names and certificate subject alternative names differ from what agents expect, every agent fails its first run after cutover. Decide up front whether the existing CA moves with the migration, export it with the rest of the SSL directory, and test one agent against a staging server before changing the rest of the fleet.
Console classification lost at cutover
Node groups, classification rules and many role assignments in the Puppet Enterprise console are stored in the console's own data, not in your code. When the console is replaced, nodes can silently stop receiving their classes and nothing fails loudly. Export the current group hierarchy and rule set, rebuild it as code (for example in Hiera or an ENC) and compare the catalogs of sample nodes before and after the move.
Enterprise-only module gaps
OpenVox aims to stay compatible with Puppet, and its install documentation says OpenVox 8.11 is functionally equivalent to Puppet for command names and configuration paths. That does not cover every Enterprise-only component. Inventory every module, profile and function your code calls, flag anything tied to Enterprise features such as the console, orchestration or RBAC, and confirm the replacement or the Puppet Standards Steering Committee direction for each before you commit to a date.
Losing support before the new platform is stable
Moving off Puppet Enterprise also ends the vendor support path that your team may depend on during an incident. OpenVox is maintained by the Vox Pupuli community, so support for your deployment comes from your own staff, a contracted partner or a retainer you arrange. Agree who responds to a failed catalog compile at night, keep the old servers available until the new ones have run stably through several change cycles, and write down the rollback path.
How the migration differs by fleet size and starting point
A small Puppet Enterprise installation usually runs the primary server, console, PuppetDB and PostgreSQL on one host, with agents on the rest of the fleet. The migration is short in sequence but has one hard dependency: the server is the only place where the certificate authority, the code directory and the database live, so it has to be backed up and verified before anything else changes. Plan a window in which agents can tolerate a stopped server, since they will fail catalog runs until the replacement is serving.
- Back up the whole tree first: Archive
/etc/puppetlabsalong with the code directory and a PostgreSQL dump, and test a restore on a spare host. - Keep the CA and certificates: Confirm the replacement server reuses the existing CA so agents do not need to be re-signed.
- Decide on PuppetDB data: Confirm whether OpenVoxDB must be populated from the old database or whether a clean start is acceptable for reports and facts.
- Run the uninstaller on the server: Follow the PE uninstaller steps before installing openvox-server, since the two cannot coexist.
- Cut agents over in batches: Upgrade agents after the server answers, starting with a few non-critical nodes.
Confirm with the vendor and your own environment whether the single server also hosts the console, which will need a replacement decision before go-live.
A large estate usually runs a primary server, one or more compilers or replicas, and a load-balanced or DNS-routed pool that agents reach. The sequencing matters more here because agents, compilers and the primary must agree on certificates and on the database they query. Moving one compiler while others still run Puppet Enterprise can produce split behavior, so the cutover is normally planned as a group with a rollback point for each stage.
- Map every role first: Record which hosts are primary, compiler, replica and database, and which agents use which load balancer address.
- Stage on a parallel build: Stand up OpenVox servers beside the existing estate and validate catalog compilation against a copy of the code.
- Move the primary before compilers: Confirm the order your topology requires so that compilers do not serve catalogs from an unmigrated CA.
- Watch the database: Confirm how OpenVoxDB will be hosted and sized before the cutover, and whether PostgreSQL is shared.
- Roll back by stage: Keep the old packages recoverable until every role has passed its checks.
Confirm the exact topology and the supported compiler layout with the OpenVox install documentation before writing the change plan.
When most managed nodes run Windows, the agent rollout is the larger part of the work. OpenVox publishes agent downloads for Windows and macOS, but the server side still runs on Linux packages from the Vox Pupuli repositories. Plan the server cutover as one event and the Windows agent cutover as a separate program, because agent packages, service accounts, and Group Policy or endpoint tooling often belong to a different team.
- Inventory agent versions: Record the current Puppet agent version on each Windows host and the module dependencies that depend on it.
- Test the agent package path: Confirm how your software distribution tool will deliver the OpenVox Windows agent and whether the uninstall of the Puppet agent runs cleanly.
- Check service accounts and paths: Verify that scheduled tasks, file permissions and any hard-coded paths under the Puppet directory still resolve.
- Coordinate with endpoint security: Ask the security team to approve the new binaries and any allowlisting rules before the wave starts.
- Use waves by business unit: Move low-risk groups first and keep a reversible path for each wave.
Confirm with your own change process whether Windows reboots are needed during the agent swap, since that drives the maintenance window.
Some estates use the Puppet Enterprise console for node classification, reporting, role-based access and the orchestrator for ad hoc commands and task runs. OpenVox does not ship the PE console or the Enterprise orchestrator, so this group has the most work outside the core migration. The sequencing question is not only how to move the server but which operator workflows must survive the move and what replaces each one.
- List the workflows: Document every console dashboard, classification group, report view, RBAC role and orchestrator job that operators use today.
- Choose replacements before cutover: Evaluate which open-source tools, such as OpenBolt for ad hoc tasks, will cover each workflow, and confirm the gaps with the vendor documentation.
- Export classification data: Confirm how node groups and their rules will be recreated in Hiera, the node classifier or whatever replaces it.
- Plan access control: Map existing RBAC roles to the access model of the replacement, since audit evidence often depends on it.
- Keep reports running: Confirm that any compliance or change reports fed by the console still have a data source after go-live.
Confirm with the people who run operations which console functions they touch weekly, because those are the ones that decide whether the cutover is ready.
Questions buyers ask before moving from Puppet Enterprise to OpenVox
Can our in-house team move from Puppet Enterprise to OpenVox without outside help?
Often yes, if the team already runs Puppet well and has time in a change calendar. The migration is mostly package work: back up /etc/puppetlabs, run the PE uninstaller on each node, then install OpenVox packages. The harder parts are the ones around the packages: rebuilding the console and orchestration workflows, checking every module against the OpenVox version you pick, moving certificates and the PuppetDB or OpenVoxDB data, and testing on non-production nodes first. Count those tasks honestly against your team's current workload. A written scope from an implementation partner such as DeployOpen can separate what your staff keep and what gets outsourced.
What drives the cost and effort of moving from Puppet Enterprise to OpenVox?
The main drivers are the number of nodes and servers, how many environments and custom modules you run, how much of the PE console and orchestrator your operations depend on, and how many integrations sit on top of Puppet. Each of these changes how much testing and rework you need. The packages themselves are free under the OpenVox licenses, so the cost sits in labor, infrastructure for the new servers and OpenVoxDB with its PostgreSQL database, and any replacement tooling for console features. Ask any provider to price these components separately, and state whether backups, testing and cutover support are included.
How long does a Puppet Enterprise to OpenVox migration usually take?
No fixed duration applies across environments, so treat any single number with caution. Timing depends on the size of the estate, the number of environments, how much code needs changes, and how many change windows your organization allows. A reasonable approach is to plan a pilot group of nodes, then move production in waves, each with a rollback plan. Ask for a timeline tied to phases and acceptance criteria in the written scope, not a single overall estimate. Your own change calendar is often the real limit.
What do we need to provide for a Puppet to OpenVox migration?
Plan for administrative access to the Puppet Enterprise servers and the agent nodes, the ability to back up the full /etc/puppetlabs tree, and an approved change window for each wave. You also need people who know your control repository, your roles and profiles, and your certificate authority. Someone must own decisions about module versions, node classification and sign-off on each environment. Confirm these needs with your provider before work starts, and note any network restrictions, air-gapped segments or compliance evidence you need to keep during the change.
Will our Enterprise modules and Puppet code work on OpenVox?
Most Puppet code is expected to carry over, because OpenVox states it is functionally equivalent to Puppet, with the same command names and configuration paths, and aims to stay compatible with downstream Puppet for as long as it can. Compatibility still needs testing. Modules that depend on Puppet Enterprise-only features, such as Enterprise-specific orchestration tasks or console data, may need rework. Run your full control repository and module set against the OpenVox version you plan to deploy, and treat any failing test as a scoped change, not a surprise at cutover.
Who supports OpenVox after cutover, and what does that cost?
OpenVox is maintained by Vox Pupuli, with work hosted in the OpenVoxProject GitHub organization and direction guided by a Puppet Standards Steering Committee. That community model does not include a vendor support contract like Puppet Enterprise. If you need guaranteed response times, you must arrange support yourself, either with an internal team or with a partner under a retainer. Ask any provider which upgrades, patch cycles, security fixes and incident response they cover after the migration, and what that costs as a recurring fee.
What does a Puppet Enterprise to OpenVox engagement cover at DeployOpen?
DeployOpen plans, implements, integrates, hardens, backs up, documents and supports self-hosted open-source platforms inside your own infrastructure, so the work fits this migration. Engagements are usually fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. A typical written scope would list the node inventory, the OpenVox servers and OpenVoxDB, backup and rollback steps, test environments, the replacement for console and orchestration features, and handover. Ongoing support and upgrades are available as retainers. DeployOpen does not publish a price list, and a quote follows from the written scope.
How DeployOpen scopes, runs and supports the move to OpenVox
DeployOpen plans, implements, hardens, backs up, documents and supports self-hosted OpenVox inside your own infrastructure, whether that is your cloud accounts, data centers or an air-gapped network. The work starts with a written scope that lists the node groups in scope, the Puppet Enterprise features you rely on (console, orchestration, role-based access control, reporting and any custom tooling), the certificate authority to be carried forward, the OpenVoxDB sizing and the cutover approach for each environment. Most engagements are fixed-scope, so the scope, deliverables and timelines are agreed in writing before any node is touched. A quote follows from that written scope, which is why the inventory and discovery work is worth agreeing as a first, clearly bounded step.
Implementation covers the parts that most often go wrong in a Puppet Enterprise exit: a verified backup of /etc/puppetlabs taken before the puppet-enterprise-uninstaller runs on each node, installation of openvox-server, OpenVoxDB, openvoxdb-termini, openvox-agent and OpenBolt from the Vox Pupuli repositories, validation of the code and Hiera data against the new server, and a rollback plan for each wave. Hardening includes the TLS and certificate settings, access to the replacement console and orchestration tooling, and the audit logging you need to show what changed. Documentation records the runbooks, the configuration decisions and the evidence collected at each step. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications; your independent auditor makes that determination.
Ongoing support, OpenVox upgrades and continuous testing are available as retainers after the migration closes. Ask any provider you evaluate to confirm in writing who patches the agent and server packages, how they track OpenVox releases such as 9.1.0, and who owns the backups and the OpenVoxDB database once the project ends. Those answers, together with the scope document, are what let your team compare proposals on equal terms.
