Introduction
This guide provides instructions for migrating Terraform Enterprise application data from a source installation to a new target installation. This procedure applies only to the Mounted Disk operational mode and does not cover deployments using external services.
The Terraform Enterprise application data is stored in a PostgreSQL database and includes core data objects such as organizations, workspaces, registry modules, run history, configuration history, and Terraform state.
This migration is useful for creating copies of application data for different environments, such as production, non-production, or disaster recovery (DR). This guide covers application data migration only and is not a full restore of an entire Terraform Enterprise instance. If the original instance is no longer operational and you need to restore the full Replicated configuration, refer to How to import the Terraform Enterprise console settings on a restored instance.
Prerequisites
- Both the source and target Terraform Enterprise installations must be in Mounted Disk operational mode.
- To prevent PostgreSQL version conflicts, ensure both the source and target installations are on matching versions of Terraform Enterprise. A conflict will not occur if both instances are version
v202103-1or greater, or if both are prior tov202103-1. - You have SSH access between the source and target instances for data transfer.
Note: Terraform Enterprise v202103-1 introduced an upgrade from PostgreSQL 9.5 to 12 for internally-managed databases. For more information, see the guide on how to Manually Backup Internally-Managed PostgreSQL Data.
Procedure
There are two primary methods for migrating the application data. Choose the option that best fits your requirements.
- Option 1: Full Directory Synchronization (rsync): This method copies the entire mounted disk data directory. It is comprehensive but may transfer more data than necessary.
-
Option 2: Database Backup and Restore: This method uses built-in
replicatedcommands to back up and restore only the PostgreSQL database. It is more targeted and often faster.
Option 1: Full Directory Synchronization (rsync)
This method involves copying the entire data directory from the source to the target instance.
1. Prepare the Target Instance
First, install Docker and Replicated on the new target instance according to the official documentation. Perform a fresh mounted disk installation. This ensures the target instance has the necessary directory structure but contains no application data.
After the installation is complete, stop the Terraform Enterprise application on the target instance.
# replicatedctl app stop
Verify the application has stopped.
# replicatedctl app status ## ... ## "State": "stopped" ## ...
2. Collect Configuration from the Source Instance
On the source instance, export the application configuration to retrieve the disk_path, enc_password, and PostgreSQL settings.
# replicatedctl app-config export --hidden | grep -E -A1 'disk_path|enc_password|generated_postgres_password|pg_url*'
Save the values for disk_path, enc_password, and all pg_url settings for the next step.
3. Transfer Data from Source to Target
On the source instance, use rsync to copy the data directory to the target instance. Ensure you have configured SSH access between the two instances.
# rsync -avz /path/to/mounted/disk/ root@<TARGET_IP>:/path/to/mounted/disk/
4. Apply Configuration on the Target Instance
On the target instance, use replicatedctl to apply the configuration values you collected from the source instance.
# replicatedctl app-config set disk_path --value "<DISK_PATH>" # replicatedctl app-config set enc_password --value "<ENCRYPTION_PASSWORD>" # replicatedctl app-config set generated_postgres_password --value "<POSTGRES_PASSWORD>" # replicatedctl app-config set pg_url --value "<PG_URL>" # replicatedctl app-config set pg_url_rails --value "<PG_URL_RAILS>" # replicatedctl app-config set pg_url_registry --value "<PG_URL_REGISTRY>" # replicatedctl app-config set pg_url_vault --value "<PG_URL_VAULT>"
5. Start the Application on the Target Instance
Start the Terraform Enterprise application.
# replicatedctl app start
Verify the application has started successfully.
# replicatedctl app status ## ... ## "State": "started" ## ...
Option 2: Database Backup and Restore
This method uses the built-in db-backup and db-restore commands. For more details, refer to the Database Maintenance documentation.
1. Prepare the Target Instance
Follow the same preparation steps as in Option 1 to perform a fresh installation and stop the application on the target instance.
2. Back up the Database on the Source Instance
On the source instance, create a database backup.
# replicated admin db-backup
This command creates a backup file, typically located at /opt/hashicorp/data/postgres-backup/ptfe.db.
3. Transfer the Backup to the Target Instance
Copy the backup file from the source instance to the exact same directory path on the target instance. You can use scp or rsync.
# scp /opt/hashicorp/data/postgres-backup/ptfe.db root@<TARGET_IP>:/opt/hashicorp/data/postgres-backup/ptfe.db
4. Collect and Apply Configuration
Follow the same steps as in Option 1 to collect the disk_path, enc_password, and PostgreSQL settings from the source instance and apply them to the target instance using replicatedctl app-config set.
5. Restore the Database on the Target Instance
On the target instance, restore the database from the backup file.
# replicated admin db-restore
The command automatically uses the ptfe.db file from the backup directory.
6. Start the Application on the Target Instance
Start the Terraform Enterprise application.
# replicatedctl app start
Outcome
After completing the steps for your chosen option, the application data migration is complete. You can now log in to the target Terraform Enterprise instance to view and verify the migrated application data, including workspaces, runs, and modules.