Backing up your analytics subsystem

Backup your project directory and configure scheduled database backups.

Project directory backups

The original project directory that was created with the apicup command during the initial product installation is essential for disaster recovery, see: Preparing to install API Connect in VMware. The project directory contains the YAML files that describe your deployment, encryption keys, and deployment ISO files. It is not possible to restore the analytics database on a deployment that uses a new or different project directory.

Take a new backup of your project directory every time you make any configuration changes with the apicup command. Store your project directory backups at a remote location.

Ensure that a backup is kept of your Analytics extra-values file, if this file is not located in your project directory.

Analytics database backups

Remote storage of analytics database backups requires a remote SFTP server or object-store (for example, IBM Cloud Object Storage).
Note: If you are using a self-managed S3 backup server, check that you have a DNS hostname entry and matching TLS certificate for your S3 backup endpoint.

Use the apicup command to configure backup settings for the analytics database.

  1. Configure the backup settings with the apicup command:
    apicup subsys set <analytics subsystem> <key> <value>
    The configurable backup settings are:
    Table 1. Analytics backup settings
    Key Default value Description
    analytics-backup-auth-pass  

    Password for your remote SFTP server or object-store.
    analytics-backup-auth-user  

    Username for your remote SFTP server or object-store.
    analytics-backup-certs  

    Applicable to object-store backups only. The name of the Kubernetes secret inside your analytics subsystem that contains the object-store CA certificate.

    Follow the steps on Creating the object-store CA secret to create and assign this secret.
    analytics-backup-enabled true

    Set to false if you want to disable analytics database backups completely. No local backups are taken and nothing is transferred to your remote SFTP server or object-store.

    Common scenarios for disabling backups are:
    • You have limited storage space in your analytics subsystem.
    • Maintenance operations that require that backups are temporarily disabled.
    analytics-backup-host   The fully qualified domain name of the backup server, in lowercase only.
    • For objstore type backup, specify the S3 endpoint with the corresponding S3 region in the format <S3endpoint>, or with an optional S3 region in the format <S3endpoint>/<S3region>.
      apicup subsys set <analytics subsystem> analytics-backup-host=s3.eu-gb.cloud-object-storage.appdomain.cloud
    • For sftp type, the SFTP server hostname
      apicup subsys set <analytics subsystem> analytics-backup-host=my.sftp.backup.domain.example.com
    analytics-backup-path   The location of the backups on the remote host:
    • S3 - the name of your S3 bucket to store backup data, optionally followed by a / and then any subdirectories inside the bucket. Valid examples:
      bucket
bucket/path
bucket/lots/of/paths

      Example:

      apicup subsys set <analytics subsystem> analytics-backup-path=apic-backup
    • SFTP - the full absolute path of the folder on the SFTP server, beginning with /.
      apicup subsys set <analytics subsystem> analytics-backup-path=</folder>

    When you specify a file path in a backup setting, be sure to escape any blank spaces in the path.
    analytics-backup-port  

    The port number of the remote SFTP server or object-store. The default for SFTP is 22. For object-store the default is 443.
    analytics-backup-protocol local

    Type of backup server: objstore, sftp, or local.

    Note: If set to local the only configurable properties are analytics-backup-scope and analytics-backup-enabled, all other properties are ignored.
    analytics-backup-schedule 0 2 * * *

    Determines the schedule for when backups are transferred to your remote SFTP server or object-store. The format for the schedule is any valid cron string.

    This property does not control the schedule for when backups are taken. Local backups are taken every hour. The analytics-backup-schedule property defines the schedule for transferring the most recent local backup to your remote SFTP server or object store.

    The time zone for backups is Coordinated Universal Time.

    Do not set the schedule to more frequently than once an hour.
    analytics-backup-scope default Set to default to backup only summary data and shared queries, and exclude the API event data (which can be 100s of Gb - see Estimating storage requirements). Set to all to backup all analytics data.
  2. Validate the backup settings:
    apicup subsys get <analytics subsystem> --validate
  3. Apply the updated backup settings:
    apicup subsys install <analytics subsystem>
  4. Run the health check to confirm that the subsystem handled the update successfully :
    apicup subsys health-check <analytics subsystem>
    No output is returned if no problems are detected.

Snapshots

Take a virtual machine (VM) snapshot of all your analytics VMs; see Using VM snapshots for backup and disaster recovery. Taking snapshots does require a brief outage while all the VMs in the subsystem cluster are shut down - do not take snapshots of running VMs, as they might not restore successfully. VM snapshots can provide faster recovery when compared to redeploying OVAs and restoring from normal backups.

Important: VM snapshots are not an alternative to the standard API Connect backups that are described in the previous step. Do not rely solely on VM snapshots for your backups.