Creating Local Copy of the Data

This document describes how to discover who is the primary of an a9s MongoDB service instance and how to create and restore a dump of this service instance.

All a9s MongoDB versions support the following guide.

Dependencies

First, you will need to install the MongoDB tools. You can check the official MongoDB documentation on how to install it: https://docs.mongodb.com/manual/installation. The steps below have only been tested with MongoDB 4.2 Tools.

  • mongo: The MongoDB client.
  • mongodump: The MongoDB client to create dumps of the service.
  • mongorestore: The MongoDB client to restore dumps to a service.

Create a Service Key

You will need to access the MongoDB instance, to be able to do it, you will need credentials. You can either use the credentials used by the application bound to the service with cf env <app> or create a new service key with cf create-service-key <service-name> <key-name>, in this case, you can check the service key with cf service-key <service-name> <key-name>.

You will need to know the uri and the default_database to use on the next steps.

If you have access to the service instance directly, use the credentials from the key or the credentials from the app environment. The examples bellow use localhost, assuming that it is not possible to access the service instance directly.

Create an SSH Tunnel

If it is not possible to access the service instance directly, you can create a tunnel to your app using cf ssh, and access the service using this tunnel.

For this step, you will need an app that is bind to the service instance. After pushing the app and binding it to the service, check the credentials, and tunnel the connection to any node belonging to the service instance.

$ cf ssh <app-name> -L 27017:<a9s-mongodb-host>:27017

Example:

$ cf ssh bindingo -L 27017:mod57756-mongodb-0.node.dc1.a9ssvc:27017

If you can access the service instance directly, you can use the Service host to connect and skip the SSH tunnel creation.

Access the MongoDB Service

You can access the MongoDB service directly with:

$ mongo "mongodb://<username>:<password>@localhost:27017/<default_database>"

Since you are tunneling the connection from your local machine to the service instance, use localhost instead of the host given in the credentials.

Example:

$ mongo "mongodb://a9s-brk-usr-715a028ce02165651096e011d5e02b1d0b392d26:a9se7970e2a142a958a93fddd14e2be6a156b03b757@localhost:27017/mod57756"

Primary of the Cluster (optional)

As long as your cluster (if using a cluster) is healthy, it should be ok to take a copy of any of the nodes, since replication is in place they should have the same view of the data. However, we suggest creating a copy from the primary node.

To discover the primary node of the Service, access the a9s MongoDB instance and execute the following command on any node of the cluster:

rs0:<role>> rs.isMaster()

Check for the field "primary" and use the address in this field to create the tunnel, as mentioned above.

Create a MongoDB Dump

The command bellow will take a copy of the specified database to your local machine using the tunnel created above: Use the credentials from cf env or from the generated service key (cf service-key <service-name> <key-name>)

$ mongodump --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" \
--gzip --archive=<dump-file>.gz

Example:

mongodump --uri="mongodb://a9s-brk-usr-a4471fa5b387767b7208edbaafda64d97b52bb91:a9s6718f1c870161b852a2b096458008f95e3a2d31e@localhost:27017/mod3ce8d" \
--gzip --archive=/tmp/mydump.gz

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

$ mongodump --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" --ssl \
--sslAllowInvalidCertificates --gzip --archive=<dump-file>.gz

Restore a MongoDB Dump

When restoring your local copy (dump file) to a new MongoDB service, you can use the mongorestore command as follows:

$ mongorestore --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" \
--gzip --archive=<output-file>.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=<output-file>.gz --nsInclude='<original-default_database>.*' --nsFrom='<original-default_database>.*' \
--nsTo='<default_database>.*' --ssl --sslAllowInvalidCertificates