Migrating to another instance with an external Db2 database

You can migrate OpenPages from one instance to another with an external database.

Before you begin

Your source and target environments must have the same version of IBM® Software Hub.
Your source and target environments must have the same version of OpenPages.
Your source and target environments must have the same version of Db2.
The status of OpenPages is Completed in both the source and target environments.
Ensure that no long-running OpenPages processes, such as FastMap imports, are in progress.
Ensure that no database scripts are running in your source or target environments.

About this task

Do this task when the load on your source and target environments is light. For example, choose a time when few users are logged in.

Complete all backup steps within a short time frame to ensure that the database and the application are in sync. Similarly, do all restore steps within a short time frame.

Backing up your source environment

Procedure

Back up the database encryption keys and secrets in the source environment.
Do these steps so that the backup files can be decrypted in the target environment and so that the target environment has the same secrets as the source environment.
1. Log in to the database server by using ssh.
2. Switch to the database instance owner (db2inst1 by default).
```
su - db2inst1
```
3. Locate the database encryption keys by running the following command:
```
gsk8capicmd_64 -cert -list -db /home/db2ext/sqllib/security/keystore/extdb_db.p12 -stashed
```
  Look for a result that is similar to the following text:
```
* default, - personal, ! trusted, # secret key
#       DB2_SYSGEN_db2inst1_OPX_2020-10-19-17.51.55_81D83D47
#       DB2_SYSGEN_db2inst1_OPX_2020-10-19-17.56.05_AF8AC2F5
```
4. Extract the keys from the keystore by running the following command:
```
gsk8capicmd_64 -secretkey -extract -db /home/db2ext/sqllib/security/keystore/extdb_db.p12 -stashed -target <label>.sec -format pkcs12 -label <label>
```
5. Note the <label> of each key. You need this information later.
Back up the external OpenPages database by doing an offline backup.
For more information, see Database backup and restore for OpenPages (Db2) and Backup overview in the Db2 documentation.
In your source environment, log in to your Red Hat® OpenShift® cluster as an instance administrator:
```
oc login OpenShift_URL:port
```
Change to the project where OpenPages is installed:
```
oc project ${PROJECT_CPD_INST_OPERANDS}
```
Run the following commands. Note the secret that is returned by each command. You need this information later.
```
oc get secret -n <openpages_project> openpages-instance_name-platform-secret -o jsonpath="{.data.encryption-key-pw}"
oc get secret -n <openpages_project> openpages-instance_name-platform-secret -o jsonpath="{.data.keystore-pw}"
oc get secret -n <openpages_project> openpages-instance_name-platform-secret -o jsonpath="{.data.opsystem-pw}"
```
In addition, you can migrate the initial secrets for the default user accounts. Do this, for example, if you did not change the initial password of a user account and you want to migrate the initial secret to your new instance. To get the secret, run the following command for each secret that you want to migrate:
```
oc get secret -n <openpages_project> openpages-instance_name-initialpw-secret -o jsonpath="{.data.<user name>}"
```
Replace the following values:

Variable Replace with

<instance_name> The name of your OpenPages instance.

<openpages_project> The name of the project where OpenPages is installed.

<user name> A user account.
The encoded password of the account is displayed. Save the password.
Back up OpenPages in your source environment by running the following commands.
1. Back up the openpages-storage directory.
```
cd /opt/ibm/OpenPages/aurora/bin
./OPBackup.sh /opt/ibm/OpenPages/temp nosrvrst
```
  Important: Do not use the /openpages-shared/openpages-backup-restore directory for this command.
2. Back up the application configuration.
```
cd /opt/ibm/OpenPages/aurora/bin
./OPBackup.sh /openpages-shared/openpages-backup-restore app-cp4d nosrvrst
```

Variable	Replace with
`<instance_name>`	The name of your OpenPages instance.
`<openpages_project>`	The name of the project where OpenPages is installed.
`<user name>`	A user account.

Restoring in the target environment

Procedure

In your target environment, import the encryption keys.

Log in to the database server by using ssh.
Switch to the database instance owner (db2inst1 by default).
```
su - db2inst1
```

Import the encryption keys by running the following command for each key. Ensure the <label> matches the <label> from the source environment.

gsk8capicmd_64 -secretkey -add -db /home/db2ext/sqllib/security/keystore/extdb_db.p12 -stashed -label <label> -format pkcs12 -file <key_file_path>

For example:

gsk8capicmd_64 -secretkey -add -db /home/db2ext/sqllib/security/keystore/extdb_db.p12 -stashed -label DB2_SYSGEN_db2inst1_OPX_2020-10-12-20.09.20_9F1D9078 -format pkcs12 -file /tmp/seckey/DB2_SYSGEN_db2inst1_OPX_2020-10-12-20.09.20_9F1D9078.sec

In your target environment, log in to your Red Hat OpenShift cluster as an instance administrator:
```
oc login OpenShift_URL:port
```
Change to the project where OpenPages is installed:
```
oc project ${PROJECT_CPD_INST_OPERANDS}
```
Scale to 1 replica.
```
oc scale --replicas=1 sts/openpages-<instance_name>-sts -n <openpages_project>
```
To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-opinst-sts
Copy the openpages-storage backup file to your target environment.
1. In your source environment, copy the backup file from step 6.a to the current working directory of your source environment.
```
oc cp -n ${INSTANCE_NAMESPACE} openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/opt/ibm/OpenPages/temp/<Backup_File_Name> <Backup_File_Name>
```
2. Copy the backup file to the /openpages-shared/openpages-backup-restore directory in your target environment.
```
oc cp -n ${INSTANCE_NAMESPACE} <Backup_File_Name> openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/openpages-shared/openpages-backup-restore/<Backup_File_Name>
```
  Make a note of the file name. You need this file in a later step. This file contains the backup of the openpages-storage directory.

Copy the application configuration backup file to your target environment.

Copy the backup file from step 6.b to the current working directory of your source environment.

oc cp -n ${INSTANCE_NAMESPACE} openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/openpages-shared/openpages-backup-restore/<Backup_File_Name> <Backup_File_Name>

Copy the backup file to the /openpages-shared/openpages-backup-restore directory in your target environment.

oc cp -n ${INSTANCE_NAMESPACE} <Backup_File_Name> openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/openpages-shared/openpages-backup-restore/<Backup_File_Name>

Restore the openpages-storage directory.
1. Log in to the application server pod and open a terminal.
```
oc exec -it openpages-<instance_name>-sts-0 -- /bin/bash
```
  To find the pod name, run oc get sts and look for a name that starts with openpages-.
2. Go to the /opt/ibm/OpenPages/openpages-backup-restore directory.
3. Locate the op_backup_<timestamp>.zip file that you copied from your source environment in step 5.
4. Run the following commands:
```
cd /opt/ibm/OpenPages/aurora/bin
./OPRestore.sh <backup_filename_without_the_file_extension> 
```
  For example, if the openpages-storage backup is in op_backup_2023_10_20_21_43_04.zip, the commands are:
```
cd /opt/ibm/OpenPages/aurora/bin
./OPRestore.sh op_backup_2023_10_20_21_43_04
```
5. Remove the openpages-storage backup file from the /openpages-shared/openpages-backup-restore directory.
6. Verify that the backup file from step 6 is now the most recent backup file in the /openpages-shared/openpages-backup-restore directory.
Restart the application server pod.
1. Scale down to 0 replicas.
```
oc scale --replicas=0 sts/openpages-<instance_name>-sts
```
  To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-instance_name-sts
2. Wait until all application server pods are deleted.
3. Scale to 1 replica.
```
oc scale --replicas=1 sts/openpages-<instance_name>-sts
```
The application configuration is restored.
Stop the application server pods.
1. Scale down to 0 replicas.
```
oc scale --replicas=0 sts/openpages-<instance_name>-sts -n <openpages_project>
```
2. Wait until all application server pods are deleted.
Restore the database.
1. Log in to the database server by using ssh.
2. Restore the database from the offline backup.
  For more information, see Database backup and restore for OpenPages (Db2) and Restore overview in the Db2 documentation.
Restore the secrets into the target environment.
```
oc edit secrets -n <openpages_project> openpages-<instance_name>-platform-secret
```
1. Update the values for each secret based on the values in your source environment.
  For more information, see Secrets in the Kubernetes documentation.
2. If you want to restore the initial secrets for the default user accounts, run the following command:
```
 oc edit secrets -n <openpages_project> openpages-<instance_name>-initialpw-secret
```
  Do this step, for example, if you did not change the initial password of a default user account and you want to migrate the account's initial secret from your old instance to your new instance.

Scale up to the number of replicas you want to use for the application server by running the following command:

oc scale --replicas=<#_of_replicas> sts/openpages-<instance_name>-sts

Replace the following values:

Variable Replace with

Variable	Replace with
`<#_of_replicas>`	Specify the number of replicas. Can be 1 or more.
`<StatefulSet_name>`	Specify the name of the StatefulSet for the application. To find the name of the StatefulSet, run `oc get sts` and look for a name that starts with `openpages-`. For example, `openpages-opinst-sts`

<#_of_replicas>

Specify the number of replicas.

Can be 1 or more.

<StatefulSet_name>

Specify the name of the StatefulSet for the application.

To find the name of the StatefulSet, run oc get sts and look for a name that starts with openpages-.

For example, openpages-opinst-sts