API Gateway Database Backup and Restore
You can take regular backups of the internal database where API Gateway data is stored to protect against accidental data loss. You can take a backup of complete API Gateway data that includes analytics data and assets data or you can take a partial backup that includes the backup of assets data or backup of analytics data. When you take a backup, you copy the contents of the repository to a file or to a cloud storage. At a later stage, you can retrieve the contents of the backup and restore them to API Gateway.
Note:
API Gateway supports incremental backup. For example, if you have taken a backup of 50 GB and there is an increase in backup to 52 GB,
API Gateway takes a backup of the new 2 GB data added.
While performing a backup, the database experiences additional load, therefore,
Software AG recommends taking a backup when the usage is low so as to avoid performance degradation.
While restoring the backup from the repository,
API Gateway replaces the existing data in
API Gateway.
API Gateway is not accessible when database restore is in progress.
To take a complete or partial backup of the API Gateway data and restore it to API Gateway, you can use the API Gateway command line utility. To back up and restore the database in command line, use the apigatewayUtil.bat and the apigatewayUtil.sh files available in the Integration Server_directory/instances/instance_id/packages/WmAPIGateway/cli/bin folder for Windows and UNIX systems respectively.
API Gateway supports the following storage platforms:
Network File System (NFS)
Amazon Simple Storage Service (S3)
Note:
You must install the Amazon Web Services (AWS) cloud plugin if you want to use the Amazon S3 storage platform. To install the AWS cloud plugin, run the following command and restart Integration Server: Integration Server_directory InternalDataStore/bin/elasticsearch-plugin install repository-s3
Using NFS Storage Platform
API Gateway uses NFS as the default repository in which the backup is stored. You can configure the repositories in which the backup is stored either in NFS or Amazon S3 cloud. However, you can create a single repository and place all the backup files in that repository.
Taking a backup:
By default, API Gateway stores the backup in the Integration Server_directory/InternalDataStore/archives/ directory. For example, if you run the command, apigatewayUtil.sh create backup -name backup_file_name, to take a backup, the backup is saved in the Integration Server_directory/InternalDataStore/archives/default directory.
Restoring a backup:
To restore the data taken as backup to API Gateway, run the following command: apigatewayUtil.sh restore backup -name backup_file_name
Note:
Once the backup is restored, you must restart the API Gateway instance.
Restoring backup to a new instance:
1. Copy the data from Integration Server_directory/InternalDataStore/archives/ directory where the backup data is available.
2. Go to the Integration Server_directory/InternalDataStore/archives/ directory where the backup data is to be restored and ensure that you delete any existing data in this directory.
3. Paste the data in the Integration Server_directory/InternalDataStore/archives/ directory.
4. Run the following command to restore the data: apigatewayUtil.sh restore backup -name backup_file_name
Note:
Once the backup is restored, you must restart the API Gateway instance.
Specifying NFS Directory path:
For API Gateways in a clustered environment, you must specify a NFS directory path. This directory path is a shared file location, which must be accessible to all the API Gateway nodes in the cluster to take a backup and restore the backup files.
1. Configure the NFS directory path before creating the NFS repository in Elasticsearch by running the following command: apigatewayUtil.sh configure fs_path -path c://sample//APIGATEWAY
2. Restart Integration Server to make the new NFS directory path available to store the backup, else the backup is stored in the default location.
Using Amazon S3 Storage Platform
You can save your backups to Amazon S3 cloud.
Creating a repository:
1. From the command prompt, go to Integration Server_directory /InternalDataStore/bin/.
2. Run the following command to create the Elasticsearch keystore file:
elasticsearch-keystore.bat create
3. Run the following command to add the Amazon S3 repository access key to your Elasticsearch keystore:
elasticsearch-keystore.bat add s3.client.default.access_key
4. When prompted to enter the Amazon S3 repository access key, type the access key value and press Enter.
Example:
Enter value for s3.client.default.access_key: 123-test-123d-123
5. Run the following command to add the Amazon S3 repository secret key:
elasticsearch-keystore.bat add s3.client.default.secret_key
6. When prompted to enter the Amazon S3 repository secret key, type the secret key value and press Enter.
Example:
Enter value for s3.client.default.secret_key: tests1232sk12312t
Important:
You must restart Elasticsearch once you provide the secret key.
7. Run the following command:
apigatewayUtil.sh configure manageRepo -file file_path
where file_path is the path where the Amazon S3 cloud details are specified.
For example, apigatewayUtil.sh configure manageRepo -file Integration Server_directory/instances/instance_id/packages/WmAPIGateway/cli/bin/conf/gateway-s3-repo.cnf.
8. Go to Integration Server_directory/instances/instance_id/packages/WmAPIGateway/cli/bin/conf.
9. Open the gateway-s3-repo.cnf file.
10. Configure the Amazon S3 details in the gateway-s3-repo.cnf file.
After modifying the gateway-s3-repo.cnf file, run the following command: apigatewayUtil.sh configure manageRepo -file <file_path>
For example, apigatewayUtil.sh configure manageRepo -file Integration Server_directory/instances/instance_id/packages/WmAPIGateway/cli/bin/conf/gateway-s3-repo.cnf
11. To enable encryption of the backup data, set the server_side_encryption property to true. The backup files saved in the backup files in the S3 repository are encrypted using the AES256 algorithm.
12. To complete the repository creation process, restart your Elasticsearch and Integration Service instances.
Taking a backup:
To take a backup of the data, run the following command: apigatewayUtil.sh create backup -name backup_file_name
Note:
The backup_file_name must be specified in lowercase.
Restoring a backup:
To restore the data taken as backup to API Gateway, run the following command: apigatewayUtil.sh restore backup -name backup_file_name
Note:
Once the backup is restored, you must restart the API Gateway instance.
Restoring backup to a new instance:
1. Create a repository using Amazon S3 if not already created.
Note:
The Amazon S3 details which you provide in the gateway-s3-repo.cnf should point to the location where you have the backup files which were taken earlier.
2. In case of multiple backups, run the following command to retrieve a list of backups: apigatewayUtil.sh list backup
3. Run the following command to restore the data using the required backup file: apigatewayUtil.sh restore backup -name backup_file_name
4. Restart API Gateway.
Note:
If you have secured Data Store using Search Guard, you cannot restore the global cluster state of the Data Store. The global cluster state includes information such as persistent cluster settings, index templates, pipelines, and so on. To restore the global cluster state, you must either perform the restore with the cluster state first, then secure the Data Store, or disable Search Guard, perform the restore with cluster state, and then enable the security plugin. However, you can still perform a restore without the global cluster state with the Search Guard plugin enabled. For information on Restoring data and the usage of restore parameters, refer the Restore using script section.