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

New PE 2026.x installations use database-backed CA storage by default and do not require migration. Use this procedure only if you are migrating an existing installation from file system-backed CA storage.

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:

  • The active CA storage backend is database.

  • 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

puppetserver ca storage --cleanup-fs is a destructive operation. Run this command only after verifying that the active CA storage backend is database by using puppetserver ca storage --status.

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. The --cleanup-fs command archives the CA directory to a tarball and then permanently removes the file system CA data. Before proceeding, the command verifies that the active CA storage backend is database. If the backend cannot be confirmed, the command exits with an error and no data is removed.

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