The Terraform Enterprise (Replicated deployment) application is stored in a PostgreSQL database and contains all of the core Terraform data objects such as the organization and workspaces details as well as registry modules, run history, configuration history, and Terraform state, etc. This KB article covers migration of the application data in mounted disk operational mode only and not when using external services.
This migration can be useful when a copy of the TFE application data is needed on separate TFE installations such as prod, non-prod, and DR as an example. This document does not cover a full restore of an existing Terraform Enterprise Instance as it is intended only for application data migration between TFE instances. Also the Replicated config will vary somewhat between separate TFE instances including the hostname.
See How to import the Terraform Enterprise console settings on a restored instance if you are instead restoring the full replicated configuration back to a new instance and the original instance is no longer operational.
TFE Application Data Migration Steps
Ensure Terraform Enterprise Versions on the source and target TFE installations match to prevent a PostgreSQL version conflict.
A PostgreSQL version conflict will also not occur if both TFE installations are on Terraform Enterprise v202103-1 and greater or both TFE Installations are on Terraform Enterprise versions prior to the v202103-1 release.
Terraform Enterprise v202103-1 introduced logic to upgrade the internally-managed PostgreSQL data from PostgreSQL 9.5 to PostgreSQL 12. This change only affects proof of concept and mounted disk installations and should not be used in production environments.
See How to Manually Backup Internally-Managed PostgreSQL Data for more info
Required Mounted Disk Data Migration Steps
Run on the Target TFE Instance
1. Install Docker and Replicated on a newly provisioned (Target TFE) instance. It is required to perform a fresh mounted disk installation which will not contain any exiting application data. It does not matter which installation method is selected (interactive or automated).
Install and Configure Terraform Enterprise
Once the TFE Installation Has Been Completed
2. Stop the Terraform Enterprise Application
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app stop
App is stopping
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app status
[
{
"AppID": "b2c6f03965cc4a4675c1b8677322ef4f",
"Sequence": 595,
"PatchSequence": 0,
"State": "stopped",
"DesiredState": "stopped",
"Error": "",
"IsCancellable": false,
"IsTransitioning": false,
"LastModifiedAt": "2022-02-15T19:04:38.325432373Z"
}
]
Run on the Source TFE Instance
3. RSYNC the folders under the mounted disk path to the Target TFE Instance. The mounted disk_path can be found in the replicatedctl app-config export output on the Source TFE instance.
Configure SSH between the Source and Target TFE instances as a prerequisite of rsync.
root@ip-10-0-107-139:~# rsync -a /opt/hashicorp/data root@10.0.44.157:/opt/hashicorp/
---
Choose to create a backup of the database on the source Terraform Enterprise installation and restore on the target via the method shown below:
*** Optionally you may also use the db-backup and db-restore option which is documented here - https://www.terraform.io/enterprise/before-installing/data-storage-requirements/disk-requirements#database-maintenance
Example with Steps
Run replicated admin db-backup on prod
root@ip-10-0-35-238:/var/snap/amazon-ssm-agent/5656# replicated admin db-backup # <--- run on prod
root@ip-10-0-35-238:/var/snap/amazon-ssm-agent/5656# ls -lah /opt/hashicorp/data/postgres-backup/
total 760K
drwxr-xr-x 2 root root 4.0K Jun 2 17:17 .
drwxr-xr-x 5 root root 4.0K Apr 25 20:06 ..
-rw-r--r-- 1 root root 751K Jun 2 17:20 ptfe.db.
Copy /opt/tfe/data/postgres-backup/ptfe.db from Prod to DR server and into the same directory location / structure. This can be done with rsync or scp, or via another file copy method.
Run replicated admin db-restore on the Target TFE Instance, which will automatically use the file /backup/ptfe.db as it's data source.
---
4. Collect the disk_path, vault encryption password, and the postgres related app-config
root@ip-10-0-107-139:~# replicatedctl app-config export --hidden | grep -E -A1 'disk_path|enc_password|generated_postgres_password|pg_url*'
"disk_path": {
"value": "/opt/hashicorp/data"
--
"enc_password": {
"value": "659a992029cd6dbfbdf1df884ecbd954"
--
"generated_postgres_password": {
"value": "r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE"
--
"pg_url": {
"value": "postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@ptfe-postgres-disk/hashicorp?sslmode=disable\u0026"
--
"pg_url_rails": {
"value": "postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@ptfe-postgres-disk/hashicorp?sslmode=disable\u0026options=-c%20search%5Fpath%3Drails"
--
"pg_url_registry": {
"value": "postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@ptfe-postgres-disk/hashicorp?sslmode=disable\u0026options=-c%20search%5Fpath%3Dregistry"
--
"pg_url_vault": {
"value": "postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@ptfe-postgres-disk/hashicorp?sslmode=disable\u0026options=-c%20search%5Fpath%3Dvault"
Run on the Target TFE Instance
5. Set the disk_path, vault encryption password, and the postgres related config from data collected on the Source TFE
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set disk_path --value /opt/hashicorp/data
Config item set successfully
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set enc_password --value 659a992029cd6dbfbdf1df884ecbd954
Config item set successfully
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set generated_postgres_password --value r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE
Config item set successfully
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set pg_url --value postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@postgres/hashicorp?sslmode=disable\u0026
Config item set successfully
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set pg_url_rails --value postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@postgres/hashicorp?sslmode=disable\u0026options=-c%20search%5Fpath%3Drails
Config item set successfully
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set pg_url_registry --value postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@postgres/hashicorp?sslmode=disable\u0026options=-c%20search%5Fpath%3Dregistry
Config item set successfully
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app-config set pg_url_vault --value postgres://hashicorp:r18vkUsQcKzOXCjChHQQgzSCEVMr5UGE@postgres/hashicorp?sslmode=disable\u0026options=-c%20search%5Fpath%3Dvault
Config item set successfully
6. Confirm the earlier RSYNC Operation was Successful
# Before RSYNC
root@ip-10-0-44-157:/opt/hashicorp/data# ls -lah
total 20K
drwxr-xr-x 5 root root 4.0K Feb 15 19:05 .
drwxr-xr-x 3 root root 4.0K Feb 15 17:59 ..
drwxr-xr-x 2 root root 4.0K Feb 15 18:04 aux
drwxr-xr-x 3 root root 4.0K Feb 15 18:04 postgres
drwxr-xr-x 2 root root 4.0K Feb 15 18:04 postgres-backup
#After RSYNC (notice timestamp change)
root@ip-10-0-44-157:/opt/hashicorp/data# ls -lah
total 20K
drwxr-xr-x 5 root root 4.0K Feb 2 21:39 .
drwxr-xr-x 3 root root 4.0K Feb 15 17:59 ..
drwxr-xr-x 3 root root 4.0K Feb 2 22:35 aux
drwxr-xr-x 3 root root 4.0K Feb 2 21:39 postgres
drwxr-xr-x 2 root root 4.0K Feb 2 21:39 postgres-backup
7. Start the Terraform Enterprise Application
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app start
App is starting
root@ip-10-0-44-157:/opt/hashicorp/data# replicatedctl app status
[
{
"AppID": "b2c6f03965cc4a4675c1b8677322ef4f",
"Sequence": 595,
"PatchSequence": 0,
"State": "started",
"DesiredState": "started",
"Error": "",
"IsCancellable": false,
"IsTransitioning": false,
"LastModifiedAt": "2022-02-15T18:06:31.892182278Z"
}
]
8. The application data migration is now complete. Login to TFE to view the newly migrated application data.