Service Instance Migration

This document describes how to migrate data from an a9s MongoDB Service Instance to another a9s MongoDB Service Instance.

Creating a Fork of a Service Instance

Forking a Service Instance involves creating a backup of it, and restoring it to a different Service Instance. This procedure can be done either manually or through the Disaster Recovery feature.

Fork an a9s MongoDB Service Instance Manually

This method can also be used to migrate to a newer MongoDB version. For migration, it is recommended that no new data is written into MongoDB during the procedure (e.g., stop the app bound to it prior to starting with these steps).

For this process, you will need a Service Instance you want to fork and a new Service Instance you want to fork to. To learn how to create a new Service Instance, look at the Create a Service Instance section. You can get a list of all of your a9s-mongodb Service Instances by running the following command:

cf s | grep a9s-mongodb

The output should be a table of your a9s-mongodb instances:

mongodb1   a9s-mongodb70   mongodb-nano                create succeeded
mongodb2   a9s-mongodb70   mongodb-nano                create succeeded

In this guide we will be forking from mongodb1 to mongodb2.

After you have established which Service Instances you will be operating on, you will need service keys. For information on creating, obtaining and managing service keys see the Service keys section.

The next thing to do is to log into the Service Instance's Service Dashboard to set the encryption password (if it hasn't been set already) and create a backup. For more information on how to set this, please see the a9s Service Dashboard's [documentation]](/docs/develop/application-developer/common/service-dashboard/a9s-ad-common-service-dashboard-using#download-a-backup).

To find your a9s Service Dashboard URL, for the instance you want to fork from (mongodb1 in this example), run this:

cf service mongodb1 | grep -E '^|dashboard:.*' --color='always'

Then log into the a9s Service Dashboard using your Cloud Foundry credentials.

Create a backup using the a9s Service Dashboard. Download the backup to your local machine. The filename will be something like racsd92baee-1522222422893. Decrypt the backup and write its contents to a file:

cat racsd92baee-1522222422893 | openssl enc -aes256 -md md5 -d -pass 'pass:mytopsecretpassword' | gunzip -c > backup.gz

info

In case you are not able to download the backup using the a9s Dashboard, you must contact the Platform Operator.

For the next steps you will need the MongoDB tools. You can install them by following the official MongoDB installation manual.

To upload the backup to the new fork Service Instance you will need to create a tunnel, for port 27017, using an app bound to the new Service Instance. As you are creating a new instance, that you likely don't want connected to production until it has the data, its advisable to deploy a small demo app for tunneling through (you can dispose of it later). A small app can be found here, you will need to edit the manifest, then follow the section Make a Service Instance Locally Available.

To run the restore you will need the credentials for the Service Instance that will become a fork. In this example the credentials can be found like this:

cf service-key mongodb2 mykey

Then carry out the restore.

Single Service Instance

For the MongoDB restoration it is required use the mongorestore program. For information on restoration commands see the Official MongoDB documentation.

Summary:

• <original-default_database> - It is the name of the previous database present at the backup. Noteworthy, if you do not have the name of the database, it is necessary to contact the Platform Operator.
• <default_database> - It is the name of the current database when the backup will be restored.
• <backup.gz> - Backup dump previously downloaded, decrypted, and uncompressed.

mongorestore --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" \
  --gzip --archive=<backup.gz> --nsInclude='<original-default_database>.*' \
  --nsFrom='<original-default_database>.*' --nsTo='<default_database>.*'

Example:

mongorestore --uri="mongodb://a9s-brk-usr-733e61a812ea27627f991d91f4a6b48db5631294:a9se1d35f1466318718cb508be4856d33631fd8c4b9@localhost:27018/mod94cfad" \
  --gzip --archive=/tmp/mydump.gz --nsInclude='mod3ce8d.*' --nsFrom='mod3ce8d.*' --nsTo='mod94cfad.*'

If this is an SSL instance, remember to add the SSL options:

mongorestore --uri="mongodb://<username>:<password>@localhost:27017/<db-name>" \
  --gzip --archive=<backup.gz> --nsInclude='<original-default_database>.*' \
  --nsFrom='<original-default_database>.*' --nsTo='<default_database>.*' --ssl \
  --sslAllowInvalidCertificates

For information on restoration commands see the Official MongoDB documentation.

Cluster Service Instance

To restore a cluster Service Instance, you can either contact the Platform Operator or alternatively you can use the Disaster Recovery feature.

Fork an a9s MongoDB Service Instance Using the Disaster Recovery Feature

caution

As of the current release, the approach using Disaster Recovery only works when forking between two instances within the same major version of MongoDB.

Follow the steps described in Disaster Recovery to create a fork of an existing a9s MongoDB Service Instance.

Creating Local Copy of the Data

For creating a local copy of the data, you can follow these steps at Creating Local Copy of the Data.