Using a9s MongoDB for PCF

This topic describes how to use a9s MongoDB.

Use a9s MongoDB with an Application

To use a9s MongoDB with an application, create a service instance and bind the service instance to your app. For more information about managing service instances, see Managing Service Instances with the cf CLI.

View the a9s MongoDB Service

After the service is installed, you can see the a9s-mongodb and its service plans appear in your CF marketplace. Run cf marketplace to see the service listing: bash $ cf marketplace Getting services from marketplace in org test / space test as admin... OK service plans description a9s-mongodb mongodb-single-small, mongodb-cluster-small, This is the anynines mongodb 32 service. mongodb-single-big, mongodb-cluster-big

Create a Service Instance

To provision a MongoDB database, run cf create-service.

$ cf create-service a9s-mongodb mongodb-single-small my-mongodb-service

Depending on your infrastructure and service broker utilization, it may take several minutes to create the service instance.

Run cf services to view the creation status. This command displays a list of all your service instances. To view the status of a specific service instance, run cf service NAME-OF-YOUR-SERVICE.

Bind an Application to a Service Instance

After your database is created, run cf bind-service to bind the service to your application:

$ cf bind-service a9s-mongodb-app my-mongodb-service

Restage or Restart Your Application

To enable your application to access the service instance, run cf restage or cf restart to restage or restart your application.

Obtain Service Instance Access Credentials

After a service instance is bound to an application, the credentials of your MongoDB database are stored in the environment variables of the application. Run cf env APP-NAME to display the environment variables.

You can find the credentials in the VCAP_SERVICES key.

$ cf env a9s-mongodb-app
Getting env variables for app a9s-mongodb-app in org test / space test as admin...
OK

System-Provided:
{
 "VCAP_SERVICES": {
  "a9s-mongodb": [
   {
    "credentials": {
     "default_database": "d22906",
     "dns_servers": [
      "172.28.10.32",
      "172.28.11.11",
      "172.28.12.23"
     ],
     "host_ips": [
      "172.28.25.13:27017"
     ],
     "host": [
      "d67901c.service.dc1.a9s-mongodb-consul:27017"
     ],
     "password": "a9s-brk-usr",
     "username": "a9s-password"
     "uri": "EXAMPLE-URI",
    },
    "label": "a9s-mongodb",
    "name": "my-mongodb-service",
    "plan": "mongodb-single-small",
    "tags": [
     "nosql",
     "database",
     "document store",
     "eventual consistent"
    ]
   }
  ]
 }
}
...

You can use the host_ips, username, and password values to connect to your database with a MongoDB client.

a9s MongoDB for PCF comes with its own Consul cluster to provide hostname resolving. When your DNS is configured to resolve the a9s MongoDB for PCF service instance domains you can make use of hosts or uri. For more information, see Name Resolving With Consul.

Delete an a9s MongoDB Service Instance

WARNING: Before deleting a service instance, you must back up data stored in your database. This operation cannot be undone and all the data is lost when the service is deleted.

Before you can delete a service instance, you must unbind it from all apps.

List Available Services

Run cf services to list your available services.

$ cf services

Getting services in org test / space test as admin...
OK

name                 service       plan                   bound apps        last operation
my-mongodb-service   a9s-mongodb   mongodb-single-small   a9s-mongodb-app   create succeeded

This example shows that my-mongodb-service is bound to the a9s-mongodb-app application.

Unbind a Service Instance

Run cf unbind-service to unbind the service from your application.

$ cf unbind-service a9s-mongodb-app my-mongodb-service

Delete a Service Instance

After unbinding the service, it is no longer bound to an application. Run cf delete-service to delete the service:

$ cf delete-service my-mongodb-service

It may take several minutes to delete the service. Deleting a service deprovisions the corresponding infrastructure resources. Run the cf services command to view the deletion status.

Upgrade the Service Instance to Another Service Plan

Once created, you can upgrade your service instance to another, larger service plan. A larger service plan provides more CPU, RAM and storage. For more information, see the Update a Service Instance of the Managing Service Instances with the cf CLI topic.

$ cf update-service my-mongodb-service -p a-bigger-plan

Here are the plans you can upgrade to, depending on the one you are currently using:

Base Plan Target Plan
mongodb-single-nano mongodb-single-small
mongodb-single-medium
mongodb-single-big
mongodb-replica-small
mongodb-replica-medium
mongodb-replica-big
mongodb-single-small mongodb-single-medium
mongodb-single-big
mongodb-replica-small
mongodb-replica-medium
mongodb-replica-big
mongodb-single-medium mongodb-single-big
mongodb-replica-medium
mongodb-replica-big
mongodb-single-big mongodb-replica-big
mongodb-replica-small mongodb-replica-medium
mongodb-replica-big
mongodb-replica-medium mongodb-replica-big
mongodb-single-nano-ssl mongodb-single-small-ssl
mongodb-single-medium-ssl
mongodb-single-big-ssl
mongodb-replica-small-ssl
mongodb-replica-medium-ssl
mongodb-replica-big-ssl
mongodb-single-small-ssl mongodb-single-medium-ssl
mongodb-single-big-ssl
mongodb-replica-small-ssl
mongodb-replica-medium-ssl
mongodb-replica-big-ssl
mongodb-single-medium-ssl mongodb-single-big-ssl
mongodb-replica-medium-ssl
mongodb-replica-big-ssl
mongodb-single-big-ssl mongodb-replica-big-ssl
mongodb-replica-small-ssl mongodb-replica-medium-ssl
mongodb-replica-big-ssl
mongodb-replica-medium-ssl mongodb-replica-big-ssl

Add a Graphite Endpoint

If you want to monitor your service with Graphite, you can set an endpoint to where to information will be sent with the cf update-service command. This command expects the -c flag and a JSON string containing the graphite and metrics_prefix keys. Depending on your graphite provider, the metrics_prefix might require that each metric must start with an API key in their name. You can also change the interval within the data is send to the endpoint. To do this, modify interval; the default is 10s.

$ cf update-service my-mongodb-service -c '{ "graphite": ["yourspace.your-graphite-endpoint.com:12345"], "metrics_prefix": "your-api-key.my-cluster-mongodb", "interval": "5"}'

Add a Syslog Endpoint

The cf update-service command used with the -c flag can let you stream your syslog to a third-party service. In this case, the command expects a JSON string containing the syslog key. You can also change the interval for the syslog with the same key than for the graphite endpoint interval.

$ cf update-service my-mongodb-service -c '{ "syslog": ["logs4.your-syslog-endpoint.com:54321"], "interval": "5" }'

Cloud Foundry Application Security Groups

This topic describes how to check whether a security group was created.

Each a9s Data Service will automatically create and update Cloud Foundry security groups in order to protected service instances to be accessed by applications not running in the same Cloud Foundry applications space. To understand Security Groups, see Understanding Application Security Groups.

Get Service Instance GUID

Run cf service INSTANCE_NAME --guid to get the guid of the service instance.

$ cf service my-mongodb --guid
ca16f111-5073-40b7-973a-156c75dd3028

Check Available Security Groups

To see all available security groups, run cf security-groups.

$cf security-groups
Getting security groups as demo@anynines.com
OK

     Name                                         Organization     Space
#0   public_networks
#1   dns
#2   tcp_open
#3   guard_432fb752-876d-443b-a311-a075f4df2237   demonstrations   demo
#4   guard_ca16f111-5073-40b7-973a-156c75dd3028   demonstrations   demo

In the above example, guard_ca16f111-5073-40b7-973a-156c75dd3028 was successfully created.

Note: In some circumstances, the connection between the application and the service instance is not possible. In this case, check to see if a security group was created.

Backup and Restore Service Instances

a9s MongoDB provides an easy way to create backups and restore if needed.

Get Dashboard Address, Log In and Authorize

  1. Grap the dashboard URL with cf service SERVICE-NAME. “`bash $cf service my-mongodb

Service instance: my-mongodb Service: a9s-mongodb Bound apps: Tags: Plan: mongodb-single-small Description: This is a service creating and managing dedicated MongoDB service instances and clusters, powered by the anynines Service Framework Documentation url: Dashboard: https://a9s-mongodb-dashboard.aws.ie.a9s.eu/service-instances/ca16f111-5073-40b7-973a-156c75dd3028

Last Operation Status: update succeeded Message: Started: 2017-10-26T08:28:38Z Updated: 2017-10-26T08:28:38Z ”`

  1. Browse to the dashboard URL and authenticate on the redirected page with your Cloud Foundry credentials: authentication-page

  2. Click Authorize to approve the authorization request: authorization-page

Perform a Backup

On the dashboard, you can trigger a backup by clicking Trigger backup.

service-dashboard

After a short period of time, the backup is queued.

service-dashboard

Note: Depending on the size of the data, the backup will take some time.

Restore a Backup

  1. Open the dashboard again and select the backup you would like to restore.

  2. Click Restore and wait for the restore to trigger.

service-dashboard

Note: Depending on the size of the data, the restore will take some time.

service-dashboard

Make a Service Instance Locally Available

It is possible to access any of the a9s Data Services locally. You can connect with a local client to the service for any purpose, such as debugging. CF provides a smart way to create SSH forward tunnels through a pushed application. For more information about this feature, see the Accessing Apps with SSH section of the CF documentation.

First, you must have an application bound to the service. To do this, see Bind an Application to a Service Instance.

Note: `cf ssh` support must be enabled in the platform. Your administrator can tell you whether it is enabled.

Get the Service URL and Credentials

You must first follow the procedure in Obtain Service Instance Access Credentials to get the hostname of the service and the user credentials.

$ cf env a9s-mongodb-app
Getting env variables for app a9s-mongodb-app in org test / space test as admin...
OK

System-Provided:
{
  "VCAP_SERVICES": {
   "a9s-mongodb": [
    {
      "credentials": {
       "default_database": "d22906",
       "dns_servers": [
        "172.28.10.32",
        "172.28.11.11",
        "172.28.12.23"
       ],
       "host_ips": [
        "172.28.25.13:27017"
       ],
       "host": [
        "d67901c.service.dc1.a9s-mongodb-consul:27017"
       ],
       "password": "a9s-brk-usr",
       "username": "a9s-password"
       "uri": "EXAMPLE-URI",
     },
     "label": "a9s-mongodb",
     "name": "my-mongodb-service",
     "plan": "mongodb-cluster-small"
    }
   ]
  }
}
...

Note the host d67901c.service.dc1.a9svs, the username a9s-brk-usr, and the password a9s-password. You will need these in the next step.

Create a Tunnel to The Service

With cf ssh, you can create am SSH forward tunnel to the management dashboard. Use port 27017 to connect to the a9s MongoDB Instance.

$ cf ssh a9s-mongodb-app -L 27017:d67901c.service.dc1.a9svs:27017
vcap@956aaf4e-6da9-4f69-4b1d-8e631a403312:~$

When the SSH tunnel is open, you can access the instance using the address localhost:27017.

Note: Be sure to close the session by running exit.

Service keys

To gain access to the service manually rather than binding apps to it, you can use service keys.

Creating a Service Key

To create a key to the service instance mongodb1 called mykey, run the following command:

cf create-service-key mongodb1 mykey

Listing Service Keys

To list all the keys for the mongodb1 service instance, run the following command:

cf service-keys mongodb1

Accessing Service Keys

To obtain the key mykey from the mongodb1 service instance, run the following command:

cf service-key mongodb1 mykey

Deleting Service Keys

To delete the key mykey from the service instance mongodb1, run the following command:

cf delete-service-key mongodb1 mykey

Creating a Fork of a Service Instance

The procedure of forking a service instance involves creating a backup of a service instance, modifying the backup, and restoring it to a different service instance.

For this process, you will need a service instance you want to fork, and a new service instance(s) you want to fork to. For help creating new service instances, see Create a Service Instance. 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-mongodb34   mongodb-nano                create succeeded
mongodb2   a9s-mongodb34   mongodb-nano                create succeeded

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

Now that 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 Service Keys.

Log in to the service instance dashboard to set the encryption password, if it has not already been set, and create a backup. Do the following:

  1. To find the dashboard URL for the instance you want to fork from (mongodb1 in this example), run the following command: bash cf service mongodb1 | grep -E '^|dashboard:.*' --color='always'

  2. Log in to the dashboard using your Cloud Foundry credentials.

  3. Set a encryption password for the backups using Change Backup Settings in the service instance dashboard.

  4. Create a backup using the dashboard.

  5. Download the backup to your local machine. The filename will be something like racsd92baee-1522222422893.

  6. Decrypt the backup and write its contents to a file: shell $ cat racsd92baee-1522222422893 | openssl enc -aes256 -d -pass 'pass:mytopsecretpassword' > backup.tar

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 must 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 do not want connected to production until it has the data, it is advisable to deploy a small demo app for tunneling through (you can dispose of it later). A small app can be found at https://github.com/anynines/simple_node_mongo_example. You will need to edit the manifest, then follow the section Make a Service Instance Locally Available.

Before the backup data can be restored, you must extract it.

tar -vxf backup.tar

Extracting the backup will create a folder that contains the files needed for the restore. You will see the folder name with the output from the tar command, named something like racsd92baee-1522222422893.

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 by running the following command:

cf service-key mongodb2 mykey

Carry out the restore by running the following command:

mongorestore -h localhost:27017 -u mongodb2-mykey-username -p mongodbd2-mykey-password extracted-backup-folder/mongodb1-database/ -d mongodb2-mykey-default_database

mongorestore will report that it is ignoring files these files concern users and roles. You can restore users and roles for specific databases in which case the bson files will not be ignored. For information on restoration commands, see the Official mongoDB documentation.

Your data has now been restored from one service instance to another. Close your SSH tunnel and clean up any temporary app instances.

Create a pull request or raise an issue on the source for this page in GitHub