Restoring from a portal database backup

Create a PortalRestore CR to restore your management database.

Before you begin

Restore the management database backup on your management subsystem first. Restore from a management database backup that was taken at the same time as the portal database backup you want to restore.

About this task

  • Portal database backups can be restored in the same environment where they were taken, or in a different environment that has the same network configuration, endpoints, and deployment profile. You cannot restore a portal database backup in a different network environment, form factor, or deployment profile. If you want to move your API Connect deployment to a different form factor or change endpoints, see Migrating from v10 to v10 on a different form factor.
  • Two data center disaster recovery deployments have extra backup and restore considerations. Review Backup and restore requirements for a 2DCDR deployment before you follow the instructions in this topic.
Three types of restore are available:
  • all: restores the Developer Portal system and all the sites that are contained in the specified database backup.
  • system: restores the Developer Portal system but not any sites from the database backup.
  • site: restores a specific Developer Portal site from the database backup.
Note: For OpenShift users: The steps that are detailed in this topic use the Kubernetes kubectl command. On OpenShift, use the equivalent oc command in its place.

Procedure

  1. Identify the portal backup that you want to restore with: 
    $ kubectl -n <portal namespace> get portalbackup -o wide --sort-by=.status.backupId | grep record
    Example output:
    NAME                  ID                TASK ID      STATUS   TYPE     CR TYPE   CLUSTER   AGE   COMMENT   FILENAME
portal-record-2vcgs   20231105.181212   n/a          Ready    system   record    portal    55m             _portal_system_backup-20231105.181212.tar.gz
portal-record-9j8lt   20231104.095949   n/a          Ready    system   record    portal    55m             _portal_system_backup-20231104.095949.tar.gz
portal-record-c4d5s   20231106.121946   n/a          Ready    site     record    portal    25m             portal.fyre-ci-162245-master.fyre.ibm.com@ibm@api-connect-catalog-2-20231106.121946.tar.gz
portal-record-c7p5q   20231106.110330   n/a          Ready    system   record    portal    55m             _portal_system_backup-20231106.110330.tar.gz
portal-record-f5h2h   20231106.115701   n/a          Ready    system   record    portal    55m             _portal_system_backup-20231106.115701.tar.gz
    Note: You can restore the portal database only from backups where the CR TYPE is record.
    You can get more information on a specific backup with:
    kubectl -n <portal namespace> get portalbackup <backup name> -o yaml
  2. Verify that the backup you want to restore exists on the remote server.
  3. Identify the name of the portal cluster that you want to restore to: 
    kubectl -n <portal namespace> get PortalCluster
  4. Create a file called portalrestore_cr.yaml. The text that you paste into the YAML file depends on the type of backup you want to restore:
    • Restore type all. Restore the full portal database, including all sites:
      apiVersion: portal.apiconnect.ibm.com/v1beta1
kind: PortalRestore
metadata:
  generateName: portal-restore-
spec:
  type: all
  portalCluster: <portal cluster name>
  dryRun: <true or false>
  timestamp: <datestamp>
  priorityList:
    - <most important site to restore>
    - <second most important site to restore>
      where:
      • portalCluster is the cluster name that you identified in step 3.
      • dryRun if you want to test restore of the backup, without overwriting your portal, set dryRun to true.
      • timestamp specify a timestamp to retrieve the backup from. The nearest backup, searching backwards from this timestamp, is used. Format is 'YYYYMMDD.HHMMSS', or set to now to restore the most recent backup.
      • priorityList Prioritizes the restore of specific site. The sites are restored in the order in which they are listed in priorityList, followed by any remaining unlisted sites. Example contents:
        priorityList:
    - production.site.com
    - test.site.com
        If you have no preference for site restore priority, then omit this property.
    • Restore type site. Restore backup of a particular site:
      apiVersion: portal.apiconnect.ibm.com/v1beta1
kind: PortalRestore
metadata:
  generateName: portal-restore-
spec:
  type: site
  portalCluster: <portal cluster name>
  siteName: <portal site to restore>
      where:
      • portalCluster is the cluster name that you identified in step 3.
      • siteName is either:
        • The UUID or URL of the site you want to restore, for example: myportal.com, in this case the latest backup of this site restored.
        • The backup ID of the backup that contains the site that you want to restore.
        • all - restore all sites in the latest backup.
        • installed - restore from the latest backup only sites that currently exist. For cases where your backup contains site backups for sites that no longer exist on your portal.
        • Backup .tgz file name. For example: site-1234.tgz restores the site from the backup file name. The file name of the backup is shown in the last column of the kubectl get portalbackup -o wide output.
    • Restore type system. Restore portal system backup, but no sites.
      apiVersion: portal.apiconnect.ibm.com/v1beta1
kind: PortalRestore
metadata:
  generateName: portal-restore-
spec:
  type: system
  portalCluster: <portal cluster name>
  systemName: <backup ID>
      where:
      • portalCluster is the cluster name that you identified in step 3.
      • systemName is either:
        • The backup ID of a portal backup CR. You can restore only portal database backups that are of type system and crType record.
        • Filename of the backup's .tgz file. Restores the system from the specified backup file name. The file name of the backup is shown in the last column of the kubectl get portalbackup -o wide output.
        • latest: restores from latest system backup that is available.
  5. Optional: If the API hostname of your management subsystem platform API changed since taking the backup you are restoring, then add the property customPlatformApiHostname to your portalrestore_cr.yaml file and set it to the new platform API hostname of the management subsystem. For example: 
    apiVersion: portal.apiconnect.ibm.com/v1beta1
kind: PortalRestore
metadata:
  generateName: portal-restore-
spec:
  ...
  customPlatformApiHostname: mgmt.platformapi.host
  ...
  6. Create the PortalRestore CR from the portalrestore_cr.yaml file: 
    kubectl -n <portal namespace> create -f portalrestore_cr.yaml
  7. Verify that the restore is running with: 
    kubectl -n <portal namespace> get portalrestore
    Example output for a restore type of all:
    NAME                   TYPE   TASK ID            STATUS    MESSAGE                                                  AGE
portal-restore-2xsgl   all    t3wz85rxz61jam92   Running   Sites Restored: 2, Sites Failed: 0, Sites Pending: 1
    Example output for a restore type of system:
    NAME                   TYPE     TASK ID            STATUS   MESSAGE                                           CLUSTER   AGE
portal-restore-xtjjt   system   yrwtcw5ult08p786   Ready    Please describe the CR to see the full message.   portal    72s
  8. To see more information about the restore, run: 
    kubectl -n <portal namespace> get portalrestore <restore name> -o yaml
    Example output:
    apiVersion: portal.apiconnect.ibm.com/v1beta1
kind: PortalRestore
metadata:
  creationTimestamp: "2020-11-11T10:14:39Z"
  generateName: portal-restore-
  generation: 1
  name: portal-restore-8f4c5
  namespace: portal
  resourceVersion: "1497597"
  selfLink: /apis/portal.apiconnect.ibm.com/v1beta1/namespaces/portal/portalrestores/portal-restore-8f4c5
  uid: 5a70b657-d998-4989-b9b6-8480e986311d
spec:
  siteName: "20200526.090209"
  portalCluster: portal
  type: site
status:
  backupId: ""
  commentLeft: ""
  conditions:
  - lastTransitionTime: "2020-11-11T10:14:39Z"
    reason: RestoreFailed
    status: "False"
    type: Error
  - lastTransitionTime: "2020-11-11T10:14:39Z"
    reason: RestorePending
    status: "False"
    type: Pending
  - lastTransitionTime: "2020-11-11T14:55:32Z"
    message: |-
      2020-05-26 13:11:25: CLI task (restore:site) starting.
      2020-05-26 13:11:36: Deleting any old site data if it exists...
      2020-05-26 13:13:18: Restoring site test.com ...
      2020-05-26 13:13:18: .
      2020-05-26 13:13:19: Patching the database dump before restoring ...
      2020-05-26 13:13:48: .
      2020-05-26 13:19:41: Triggering the drush command to restore the site. This may take some time.
      2020-05-26 13:19:48: .
      2020-05-26 13:25:40: Drush restore command completed. Setting up the site.
      2020-05-26 13:25:48: .
      2020-05-26 13:30:49: Site test.com restored from backup /var/aegir/backups/test.com-20200526.090209.tar.gz. Initializing the site...
      2020-05-26 13:30:52: Restore site completed.
      2020-05-26 13:30:52: CLI task (restore:site) completed successfully.
    reason: RestoreComplete
    status: "True"
    type: Ready
  - lastTransitionTime: "2020-11-11T14:55:32Z"
    reason: RestoreInProgress
    status: "False"
    type: Running
  - lastTransitionTime: "2020-11-11T10:14:39Z"
    reason: RestoreStatusUnknown
    status: "False"
    type: Warning
  fullBackupName: ""
  id: bybyibd99wxtmkmk
  message: ""
  9. When the restore completes RestorePortal CR shows Ready state, regardless of whether the restore was successful or not. 
    
NAME                   TYPE   TASK ID            STATUS    MESSAGE                                                  AGE
portal-restore-2xsgl   all    t3wz85rxz61jam92   Ready   Sites Restored: 3, Sites Failed: 0, Sites Pending: 0
  10. If a site fails to restore, check for messages in the restore description: 
    kubectl -n <portal namespace> get portalrestore <restore name> -o yaml

    Also, check the logs of the admin container in the www pod:

    kubectl -n <portal namespace> logs <portal www pod> -c admin