Configuring management database backups

Configure scheduled database backups of your management subsystem.

Before you begin

You must have a remote SFTP server or S3-compatible object-store for storing your management database backups. Example S3-compatible object-stores:

AWS S3.
IBM Cloud Object Storage.
Custom S3 storage.

The object-store's backup folder must be empty.

About this task

Important points:

Management 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 management 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.
Ensure that you regularly take a Taking a management infrastructure configuration backup. If a disaster occurs and you lose your management subsystem configuration, then you cannot restore your management database backup without first restoring the config backup.
Take portal database backups at the same time as you take management database backups.

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

Create a backup secret.
The backup secret is a Kubernetes secret that contains your access key and secret for your SFTP server or object-store.
Create the backup secret with the following command:
- Object-store:
```
kubectl -n <management namespace> create secret generic mgmt-backup-secret --from-literal=key='<access key>' \
--from-literal=keysecret='<access secret>'
```
  where <access key> and <access secret> are the access credentials for your object-store.
- SFTP username and password:
```
kubectl -n <management namespace> create secret generic mgmt-backup-secret --from-literal=username='<username>' --from-literal=password='<password>'
```
- SFTP username and SSH key:
```
kubectl -n <management namespace> create secret generic mgmt-backup-secret --from-literal=username='<username>' --from-file=ssh-privatekey='<privatekeyfile>' [--from-literal=password='<privatekey_passphrase>']
```
Take a backup of this secret and keep it with your Taking a management infrastructure configuration backup.
Important: It is recommended to regularly update your backup secret:
1. Run the same kubectl create secret generic <secret name> command, but with a new secret name and your updated access key and secret.
2. Edit your management CR to update the secret name in spec.databaseBackup.credentials.
3. Reload the secret in the management subsystem with:
```
 kubectl annotate mgmt <mgmt-subsystem-name> apiconnect-operator/management-db-reloaded-at=$(date -u +"%Y-%m-%dT%H:%M:%SZ") -n <management namespace> --overwrite
```
  where <mgmt-subsystem-name> is the name of your management subsystem CR.
If your object-store has a custom CA certificate, then create a Kubernetes secret that contains this CA certificate, so that your management subsystem trusts the object-store.
1. Run the following command to create a Kubernetes secret from the certificate file:
```
kubectl -n <management namespace> create secret generic mgmt-custom-objstore-ca --from-file=ca.crt=/path/to/cert.crt
```
  Note: Include the complete chain in your certificate file, for example:
```
intermediate-certificate-1
intermediate-certificate-2
. . .
intermediate-certificate-n
root-certificate
```
  The first certificate (intermediate-certificate-1) is the issuer of the object-store server certificate, and each subsequent certificate is the issuer of the preceding certificate. The root certificate must be self-signed.
  If the certificate includes no intermediate certificates, then the file contains only the root certificate.
2. Take a backup of the new secret.
```
kubectl -n <management namespace> get secret mgmt-custom-objstore-ca -o yaml > mgmt-custom-objstore-ca.yaml
```
  Keep the generated mgmt-custom-objstore-ca.yaml file with your management infrastructure backup.
Kubernetes and OpenShift individual subsystem CR users: Edit your ManagementCluster CR:
```
kubectl -n <management namespace> edit ManagementCluster
```
Cloud Pak for Integration and OpenShift top-level CR users: Edit your APIConnectCluster CR:
```
oc -n <apic namespace> edit APIConnectCluster
```
Configure your backup settings in the databaseBackup section of the spec object:
```
spec:
  databaseBackup:
    host: <host>/<region>
    port: <port number>
    protocol: [local|sftp|objstore]
    path: <path>
    credentials: <backup secret>
    backupCerts: <custom CA certificate>
    schedule: "<cron schedule>"
    repoRetentionFull: <number of days>
    backups3URIStyle: <path/host> # host or virtual style is the default 
```
Note: On Cloud Pak for Integration and OpenShift when using the top-level CR, add the databaseBackup section to the spec.management section.
Set the properties as follows:
- host hostname of your remote SFTP server or object-store endpoint. If you are using an object-store and your endpoint does not have a region, then omit /<region>.
- port is the listening port on your remote SFTP server or object-store. Defaults are 22 for SFTP and 443 for object-store.
- path is the location for your backups on your remote SFTP server or object-store. If you are using an object-store the format must be: bucket_name/folder.
- protocol: Type of remote backup site, objstore or sftp. If you do not have a remote backup site then, set to local.
- credentials is the name of the backup secret that you created in step 1.
- backupCerts is the CA certificate secret that is created in step 2.
- schedule is the schedule for when database backups are run, in cron format:
```
    * * * * * *
    - - - - - -
    | | | | | |
    | | | | | +----- day of week (0 - 6) (Sunday=0)
    | | | | +------- month (1 - 12)
    | | | +--------- day of month (1 - 31)
    | | +----------- hour (0 - 23)
    | +------------- min (0 - 59)
    +--------------- sec (0 - 59)
```
  For example:
```
0 0 1 * * *
```
  runs a backup at 1 AM every day.
  
  The default is an empty string (no backup configured).
  
  Note: Set the same schedule as your developer portal database backups.
- repoRetentionFull is the number of days to retain backups for. For example, if repoRetentionFull is set to 30, then any backups older than 30 days are deleted.
```
Minimum: 1
Maximum: 9999999
Default: 0 (No retention)
```
  Important points:
  - The repoRetentionFull start day is reset to the current day when you restore a management database backup.
  - repoRetentionFull applies to both manual backups and scheduled backups.
  - When older backups are deleted, their corresponding backup CR is deleted.
- backups3URIStyle applies to backups to object-store only. Indicates whether URIs to your object-store backup specify a host or a path value. Set to either host or path. The default is host.
  Some custom object-store providers require URI style to be set to path. For example, MinIO supports both host and path style setup. You can create a MinIO S3 server to accept only path style client communications.
  
  Important: Contact your custom object-store administrator before you configure this field. If not properly configured, an upstream custom object-store can reject connections from the client, such as the management subsystem.

What to do next

Run an on-demand backup to confirm that your backup configuration is correct, see Running an on-demand backup of the management database.