Hello API Community!
We will share with you some caveats on how to backup and restore your CA API Gateway running on a docker container. By following the documented steps here you will be able to spin up a fresh CA API Gateway docker container (gateway + mysql), run a full backup of it, destroy the containers, recreate them and restore to the point you left before kill them. This helps a lot as containers are not static things and usually rely on some sort of devops procedures to deploy things into it case you need to recreate everything from scratch.
This article is a result of a team effort and I wanted to include hocmo01 and solda01 as the co-authors of this tutorial
Some assumptions, before we get to it:
- None of the steps are meant to replace any Devops procedures for production environments, that means, you should use your own approach to make sure you have all the required information saved in order to do a full restore.
- All the steps were executed on a test lab environment and their replication will depend on your environment and expertise.
- The steps were made using a Mac but you still can use Windows/Linux to do so. You just have to adapt the command's name for the GMU;
- You may find a better way to do it and if so, don't by shy and post it on the comments below
Let's get started!
Backing up your containers:
We will be using 03 different tools to save everything we've changed on our CA API Gateway docker container. They are:
- The Gateway Migration Utility (aka GMU), that you can find inside the development tools through CA support/download website;
- The Gateway's native backup tool; &
- The MySQL Dump tool.
Using the GMU to export the gateway's configuration:
1. Open the Terminal and go to the folder where you saved the GMU. The version we're using in this tutorial is the 1.3.00. Run this command to export your gateway's configuration:
GMU Command to backup the gateway
|
|---|
| ./GatewayMigrationUtility.sh migrateOut -h gwlab10.apimca.com -p 8443 -u pmadmin --plaintextPassword 7layer --trustCertificate --trustHostname --plaintextEncryptionPassphrase 7layer --all -d docker/migrateout.xml |
Command's arguments detailed:
Argument
| Explanation |
|---|
| migrateOut | It wil perform a full export |
| -h gwlab10.apimca.com | Your gateway's hostname or IP address |
| -p 8443 | Gateway's port |
| -u pmadmin | Admin user name to connect to the gateway |
| --plaintextPassword 7layer | The Admin's plain text password |
--trustCertificate --trustHostname --plaintextEncryptionPassphrase 7layer | Some arguments to allow the communication to be smoothly |
| --all | Save everything |
| -d docker/migrateout-20160810.xml | Where the exported XML file will be saved. You have to create the folder (in this case docker) first |
This is the result of the above command being executed:
Using the Gateway's native tool to save a full backup:
1. Go to your docker host and connect to your gateway's container using the command: docker exec -it <container ID> bash. If you don't know your container ID, you can run a docker ps and get the CONTAINER ID of your running caapim/gateway.
2. Once inside your gateway's container, navigate to /opt/SecureSpan/Gateway/config/backup/ and run the following command:
./ssgbackup.sh -image mygatewayexport.zip -config -ext -ca -ma
Where mygatewayexport.zip is the name of the file that will be generated as your backup. After run that command you will be seeing something like that:
The backup file will be saved here: /opt/SecureSpan/Gateway/config/backup/images.
3. Exit the container by typing exit and copy the generated file from the container into the docker host. You will be using that file later during the restore process. To copy that file from the gateway's container, run the following command, using your own container ID and export file:
docker cp 838a073f638b:/opt/SecureSpan/Gateway/config/backup/images/20160810164925_mygatewayexport.zip .
Backing up the MySQL Database:
1. Connect yo your MySQL container, using the docker exec command, and run the mysqldump command as follows:
mysqldump -u root -p --all-databases > dump.sql
This will save a dump.sql file, which you have to copy from the container into your docker host like you did in the step #3 previously.
At this point you should have 03 different files:
- migrateout-20160810.xml --> created by the GMU;
- 20160810164925_mygatewayexport.zip --> created by the gateway's native backup tool; and
- dump.sql --> created by the MySQL dump tool;
I'd suggest you to put those 3 files in the same folder, to facilitate the restoring process.
Restoring everything:
Assuming you have destroyed your containers and spun up new ones, we're going to restore everything from the saved backups. Although we had used both the GMU the and Gateway's native backup tool, we will be using only one of them to restore the gateway's configuration. You don't need to use both. In this tutorial we will be using the gateway's restore tool but will be showing you how to use the GMU as well.
Stoping the SSG service and restoring the gateway's configuration and MySQL database:
1. Connect to your new Gateway's container and stop the SSG service using the command service sag stop
2. Close the connection and go to the folder where you saved your backup files. Now copy the gateway's image (zip file) to your new gateway's container using the following command:
docker cp 20160810151553_name.zip bd26c8e4fbee:/opt/SecureSpan/Gateway/config/backup/images/
3. Connect to your gateway's container again and go to the folder /opt/SecureSpan/Gateway/config/backup/
4. Now run the following command to restore the backup. Make sure you're using the right path and name of your backup file:
./ssgrestore.sh -image /opt/SecureSpan/Gateway/config/backup/images/20160810151553_name.zip -config -ca -ma
5. Exit the gateway's container and connect to your new MySQL one;
6. From the same folder you saved your backup files, run the following command to copy the saved MySQL dump file to the container:
docker cp dump.sql 1eaba1c1a4d6:/
7. Now connect to your MySQL container again to run the dump using the following command:
mysql -u root -p < dump.sql
8. In our environment we had issues with the OTK after restoring the files. If you experience any issues with either the OAuth Manager or Test Client, you will need to drop your OTK_DB and recreate it using the otk_db_schema.sql and otk_db_testdata.sql. The following will show you how to do it:
After copying the files, connect to the MySQL console and drop the otk_db (use the same name you used when installed the OTK), and then recreate it:
# mysql -u root -p
mysql> drop database otk_db;
mysql> create database otk_db;
mysql> flush privileges;
# mysql -u root -p otk_db < otk_db_schema.sql
# mysql -u root -p otk_db < otk_db_testdata.sql
9. Now go back and connect to your gateway's container again. At this time, run the following command to start the SSG service again:
# service ssg start
10. Wait until the service SSG is fully started and make some tests by connecting to your gateway using the Policy Manager and also OAuth Manager / TestClient (if you had them installed before the backup). If you had the OTK installed previously, you will need to reconfigure the clients to match your gateway's hostname following this document: Post-Installation Tasks - CA API Management OAuth Toolkit - 3.5 - CA Technologies Documentation
These are some screenshots from our restored gateway:
Documentation references: