Backing up and restoring the Developer Portal in a Kubernetes environment

How to backup and restore your Developer Portal service in your Kubernetes environment.

• How to configure the location and timing of your backups
  1. Open your API Connect installation project directory.
  2. Run the following commands to set the location and timing of your backups:

     apicup subsys set ptl site-backup-host mybackuphost.com
     apicup subsys set ptl site-backup-port 22
     apicup subsys set ptl site-backup-auth-user mybackupauthusername
     apicup subsys set ptl site-backup-auth-pass mybackupauthpassword
     apicup subsys set ptl site-backup-path /site-backups
     apicup subsys set ptl site-backup-protocol sftp
     apicup subsys set ptl site-backup-schedule "0 2 * * *"

     The backup parameters are detailed in the following table.

     Table 1. Portal backup parameters

     Parameter	Description
     site-backup-host	The fully qualified domain name of the backup server, in lowercase only. Ensure that the Kubernetes nodes can access this host. If using object storage, enter Endpoint/Region. (The / character between the endpoint and region is required for the object storage setting.)
     site-backup-port	The port for the protocol to connect to the site-backup-host. Defaults to 22 if not explicitly set. The backup port is not required for object storage.
     site-backup-auth-user	The user name for the server specified in site-backup-host. If using object storage, the user name is the S3 Secret Key ID.
     site-backup-auth-pass	The password for the server specified in site-backup-host. If using object storage, the password is the S3 Secret Access Key parameter. The password is stored in Base64 encoded format, and must not be edited directly in the apiconnect-up.yml file.
     site-backup-path	The full path to the directory where the backup files are stored. For object storage, the path can be set to the bucket value or the bucket/subfolder value.
     site-backup-protocol	The protocol that is used to communicate with your remote backup endpoint. Specify one of the following values: sftp - for secure file transfer protocol objstore - for S3 compatible object storage The default protocol is sftp. Note: The public certificate on the S3 storage provider must be signed by a known certificate authority that is trusted by API Connect. Use of an untrusted authority can cause the following error during backup upload: x509: certificate signed by unknown authority.
     site-backup-schedule	The schedule for how often automatic Portal backups are run. The format for the schedule is any valid cron string, as follows: * * * * * - - - - - | | | | | | | | | +----- day of week (0 - 6) (Sunday=0) | | | +------- month (1 - 12) | | +--------- day of month (1 - 31) | +----------- hour (0 - 23) +------------- min (0 - 59) For example: 30 22 * * 1 performs backups at 10:30 pm on Mondays. The default backup schedule is 0 2 * * * (runs every day at 2 am). The timezone for backups is UTC.

  3. Optional: At any time you can view the current Portal subsystem values by running the following command:

     apicup subsys get ptl

     where ptl is the name that you assigned to your Portal service. The output from this command lists all of the subsystem settings, including backup, and indicates whether there are any errors. You must fix any errors before continuing.
  4. Validate the installation with the new backup parameters by running the following command:

     apicup subsys get ptl --validate

     where ptl is the name that you assigned to your Portal service. The output from this command lists all of the subsystem settings, including backup, and indicates whether the values are valid or invalid. You must correct any invalid values before continuing.
  5. Activate the backup settings by running the following command:

     apicup subsys install ptl

     where ptl is the name that you assigned to your Portal service.
• How to run on-demand backups

  You can make on-demand backups of your Developer Portal system, sites, and complete service, by running the following exec commands in your API Connect installation project directory.

  • To backup the Portal system configuration (and not the sites), run the following command:

    apicup subsys exec ptl backup-system

  • To backup a specific Portal site or all sites, run the following command:

    apicup subsys exec ptl backup-site arg

    where arg is a specific site UUID or URL, or to backup all sites use the argument installed.
  • To backup the entire Portal service (the system and all installed sites), run the following command:

    apicup subsys exec ptl backup

  Where ptl is the name that you assigned to your Portal service.

  Note: To restore a Developer Portal service, you need backups of both the Portal system and the installed sites.
• How to restore a Developer Portal service
  You can restore your Developer Portal service by using the backups that exist on your remote server, by running the following exec commands in your API Connect installation project directory. Note that before you can run these commands, you must have configured your remote backup server details, and have valid backups of both the Portal system and the installed sites (see sections How to configure the location and timing of your backups and How to run on-demand backups).

  Note:

  • If you have to perform a restore, you must complete the restoration of the Management Service first, and then immediately restore the Developer Portal. The backups of the Management and Portal must be taken at the same time to ensure that the Portal sites are consistent with Management database.
  • Restoration requires a functioning Developer Portal. In a disaster recovery scenario, you might need to reinstall the Developer Portal subsystem before you can restore the backed-up data. To reinstall, refer to Installing the Developer Portal subsystem into a Kubernetes environment.

  • To see what Portal system and site backups that you currently have on your remote backup server, run the following command. (This command may be useful when performing some of the following commands.)

    apicup subsys exec ptl list-backups remote

  • To see what restore actions are performed when the apicup subsys exec ptl restore-all command is run, you can use the following command:

    apicup subsys exec ptl restore-all dry backup_from

    where backup_from can be now, so the latest backup file that is available is used. Or you can specify a timestamp in the format of YYYYMMDD.HHMMSS to retrieve the nearest backup file to a specified time, searching backwards from the timestamp given.
    Note: From IBM® API Connect Version 2018.4.1.17, the timestamp format changed to YYYYMMDD.HHMMSS. For Version 2018.4.1.16 and earlier, the timestamp format is YYYY-MM-DD HH:MM:SS.
  • To restore your Portal service, run the following command:

    apicup subsys exec ptl restore-all run backup_from

    where backup_from can be now, so the latest backup file that is available is used. Or you can specify a timestamp in the format of YYYYMMDD.HHMMSS to retrieve the nearest backup file to a specified time, searching backwards from the timestamp given. This command executes the portal restore process, which downloads the system backup and all of the site backups from the remote server, and installs them within the Portal stack. This process will then restore the system configuration from the found backup, and restore all of the sites.
    Note: Note that if a backed up site is already installed on the current stack, then the site is reinstalled by using the backup (the site is overwritten by the backup).
    If there are multiple sites to restore, then these sites are queued for restoring. You can track the restoration process within the Portal www admin logs.
  • To view the list of installed and restoring sites, run the following command:

    apicup subsys exec ptl list-sites sites

    Note that any sites that are pending restore and still in the queue do not appear in this list.
  • To restore just the Portal system configuration, run the following command:

    apicup subsys exec ptl restore-system arg

    where arg can be the system backup tgz file name, to restore the system by using the specified backup file, or use the argument latest to restore the system by using the latest backup file on the remote server. Note that if Portal system configuration information exists on the current stack, running this command will overwrite that configuration.
  • To restore just the Portal sites, run the following command:

    apicup subsys exec ptl restore-site arg

    where arg can be the site backup tgz file name or URL, to restore a particular site by using the specified backup file (or the latest backup file found if using a URL). Or you can use the argument all to restore all of the Portal sites that have backup files on the remote server. Note that if any of the backed up sites are already installed on the current stack, then they are reinstalled by using the backup (the sites are overwritten by the backup).