Page last updated:

Integrating the Service With Your App

After the creation of the service and the binding of the service to the application, the environment variable VCAP_SERVICES is created. Information about the credentials are stored in this variable as shown here:

  "mongodb-2": [
      "credentials": {
        "host": "kubernetes-service-node.service.consul",
        "ports": "52181,34278,31026",
        "username": "QkHWHmwkale0D90p",
        "password": "l9uGWEC6xZmiL7KG",
        "database": "c052a0cq",
        "database_uri": "mongodb://QkHWHmwkale0D90p:l9uGWEC6xZmiL7KG@kubernetes-service-node.service.consul:52181,kubernetes-service-node.service.consul:34278,kubernetes-service-node.service.consul:31026/c052a0cq?replicaSet=rs_ca5200la-6v2f-12ch-ab72-c8d8g79630bc",
        "uri": "mongodb://QkHWHmwkale0D90p:l9uGWEC6xZmiL7KG@kubernetes-service-node.service.consul:52181,kubernetes-service-node.service.consul:34278,kubernetes-service-node.service.consul:31026/c052a0cq?replicaSet=rs_ca5200la-6v2f-12ch-ab72-c8d8g79630bc",
        "replica_set": "rs_ca5200la-6v2f-12ch-ab72-c8d8g79630bc"
      "label": "mongodb-2",
      "name": "mongodb-example",
      "plan": "small",
      "tags": [

Important: Please be aware that the number of concurrent connections to MongoDB is limited depending on the service plan you chose. You can manage this by using connection pooling.

Administrating your MongoDB instances

To connect to a running MongoDB instance with your local development tools, you can use the cf ssh feature of the cf CLI:

  • Create a local hosts entry localhost kubernetes-service-node.service.consul

  • Connect to an app in your mongodb space via cf ssh to forward the ports of all replica set slaves (get the cluster ports from database_uri in ‘cf env myapp’) `cf ssh myapp -L 40613:kubernetes-service-node.service.consul:40613 -L 46584:kubernetes-service-node.service.consul:46584 -L 38656:kubernetes-service-node.service.consul:38656

  • Modify connection string and connect via mongo cli (remove ?replicaSet parameter from the database_uri) mongo mongodb://USER:PASSWORD@kubernetes-service-node.service.consul:40613,kubernetes-service-node.service.consul:46584,kubernetes-service-node.service.consul:38656/d55a188e

Version Upgrade

New versions of MongoDB will be announced in the newsletter as soon as they are available.

The upgrade to the new version is done through the CF CLI by running the update service command. This command will always upgrade the binaries to the lastest available version.

cf update-service <service-instance-name> -c '{"featureCompatibilityVersion":"3.6"}'

You can only upgrade the service and change the feature compatibility to the new version.

Sample Application

Cloud Foundry: Spring Music Example


Our MongoDB offering consists of 3 Kubernetes containers configured as a replica set.


You will receive the role clusterMonitor on the admin DB, and the roles readWrite and dbAdmin on your DB.


Within your MongoDB service instance you can start a backup and also restore it afterwards. For more information about this feature, check the service backup guide.

If you need more fine-grained control over your backups there is also an app available that allows for automatic scheduled backups: backman - the appcloud backup manager. Any MongoDB service instance bound to this app will be automatically backed up, can be downloaded and also restored on-demand.

Best Practices for Developers

  • Write concern 2

Please read Replica Set Read and Write Semantics. We recommend a “Write Concern” of 2 in order to ensure data consistency at all times, even if the replica set temporarily consists of just 2 nodes e.g. during system maintenance.

  • Use an application driver maintained by the MongoDB team

It’s critical to find a driver that is well maintained and stays up to date with the latest MongoDB features.

  • Index early and often

Without question, the most common database performance issue is improper indexing (or a complete lack thereof). Have a look at the Indexes manual.

  • Consider a query timeout

MongoDB targets operations for termination if the associated cursor exceeds its allotted time limit. See cursor.maxTimeMS() for more details.


In accordance with the service plan you choose from the marketplace, resource limitations are enforced. Please note that exhausting those limitations comes with certain risks, and MongoDB itself only has very limited means of preventing overload / overuse.

  • Memory

If a replica set member of your MongoDB service instance exhausts the available memory, its mongod process will be killed and restarted. Luckily, the MongoDB replica set and MongoDB driver will mitigate this efficiently and without any noticeable downtime by default. However, your experience might degrade if the load isn’t reduced and this keeps happening repeatedly within a short time frame. Furthermore, backup and restore operations (both system- and user-driven) might be impacted if the replica set is not running stably. Lastly, opening connections requires approximately 1 MB of memory, i.e. it might not be possible to open additional connections, once memory is exhausted.

  • Storage

If a replica set member of your MongoDB service instance runs out of disk space, its mongod process will crash and likely not be able to recover automatically. Additionally, there’s an increased risk of data corruption if this happens.

  • Connections

The maximum number of connections provided with the service plan is not technically enforced, but must be adhered to anyway. If the maximum of connections is exceeded, proper operations can’t be guaranteed anymore. This is particularly true for the service health and availability, as well as backup and restore operations (both system- and user-driven).

View the source for this page in GitHub