Migrate a CA to database-backed storage

Before you begin:
  • Ensure you have a recent PE backup.
  • In HA deployments, perform migration on the primary only.

Migrate to database-backed storage

To migrate the CA to database-backed storage, run the CA storage import plan:

puppet plan run puppet_enterprise::ca_storage_import \
  targets=<primary-certname>

This plan:

  • Imports CA data into the database

  • Switches the active backend

  • Restarts Puppet Server

  • Performs a delta sync

  • Verifies the migration

The operation is safe to re-run if it fails.

Validate the migration

To verify that the migration completed successfully, check the CA storage status:

/opt/puppetlabs/bin/puppetserver ca storage --status

Confirm that:

  • Puppet Server is running

  • Certificate operations succeed

Roll back to file system storage

If you need to roll back the migration, run the CA storage export plan to restore file system-backed CA storage:

puppet plan run puppet_enterprise::ca_storage_export \
  targets=<primary-certname> \

Optional: Remove file system CA data

After you verify that the database-backed CA is functioning correctly, you can remove the remaining file system CA data:

systemctl stop pe-puppetserver 
puppetserver ca storage --cleanup-fs --force 
systemctl start pe-puppetserver
Only remove file system CA data after confirming the database backend is functioning correctly.

Advanced migration (large environments)

You can perform migration in phases:

  • Phase A: Pre-stage (no downtime)

  • Phase B: Cutover (restart required)

  • Phase C: Cleanup

During cutover, Puppet Enterprise performs a delta sync to ensure no CA data is lost.

Related information