1 of 20

MongoDB

With IONOS Cloud Database as a Service (DBaaS) MongoDB, you can quickly set up and manage MongoDB database clusters. It is an open-source, NoSQL database solution that offers document based storage, monitoring, encryption, and sharding. To provision to your workload use cases, IONOS provides MongoDB editions such as Playground, Business, and Enterprise models.

Product Overview

Developer Tools

Recommended How-To's

Overview

MongoDB is a widely used NoSQL database system that excels in performance, scalability, and flexibility, making it an excellent choice for managing large volumes of data. MongoDB offers different editions tailored to meet the requirements of enterprise-level deployments, namely MongoDB Business and MongoDB Enterprise editions. You can try out MongoDB for free with the MongoDB Playground edition and further upgrade to Business and Enterprise editions.

MongoDB Playground is a free edition that offers a platform to experience the capabilities of MongoDB with IONOS. It provides one playground instance for free and each additional instances created further are charged accordingly. You can prototype and learn how best the offering suits your enterprise.

MongoDB Business is a comprehensive edition that combines the power and flexibility of MongoDB with additional features and support to address the needs of businesses across various industries. It provides an all-in-one solution that enables organizations to efficiently manage their data, enhance productivity, and ensure the reliability of their applications.

MongoDB Enterprise is a powerful edition of the popular NoSQL database system, MongoDB, specifically designed to meet the demanding requirements of enterprise-level deployments. It offers a comprehensive set of features, advanced security capabilities, and professional support to ensure the optimal performance, scalability, and reliability of your database infrastructure.

IONOS DBaaS offers you a replicated MongoDB setup in minutes.

DBaaS is fully integrated into the Data Center Designer. You may also manage it via automation tools like Terraform and Ansible.

Compatibility:

DBaaS currently supports MongoDB Playground versions 5.0 and 6.0.

DBaaS currently supports MongoDB Business versions 5.0 and 6.0.

DBaaS currently supports MongoDB Enterprise versions 5.0 and 6.0.

Locations:

Offered in the following locations: de/fra, de/txl, gb/lhr, es/vit, us/ewr, us/mci and fr/par.

Offered in the following locations: de/fra, de/txl, gb/lhr, es/vit, us/ewr, us/las, us/mci and fr/par.

Features

The MongoDB Playground, MongoDB Business, and MongoDB Enterprise editions offer the following key capabilities:

Availability: Single instance database cluster with a small cube template availability.

Security: Communication between instances and between the client and the database cluster is protected with Transport Layer Security (TLS) using Let's Encrypt.

Resources: Cluster instances are dedicated Servers, with a dedicated CPU, storage, and RAM.

Backup: Backups are disabled for this edition. You need to upgrade to MongoDB Business or MongoDB Enterprise to avail database backup capabilities.

High availability: Multi-instance database clusters across different physical hosts with automatic data replication and failure handling.

Security: Communication between instances and between the client and the database cluster is protected with Transport Layer Security (TLS) using Let's Encrypt.

Management: Efficient monitoring and management are essential for maintaining the health and performance of MongoDB deployments. IONOS MongoDB Business Edition includes powerful monitoring and management tools to simplify these tasks. The MongoDB management enables centralized monitoring, proactive alerts, and automated backups, allowing businesses to efficiently monitor their clusters and safeguard their data.

Resources: Cluster instances are dedicated Servers, with a dedicated CPU, storage, and RAM. All data is stored on high-performance directly attached NVMe devices and encrypted at rest.

Backup: Daily snapshots are kept for up to seven days.

Restore: Databases can be restored from snapshots.

Shards: Supports horizontal scalability through MongoDB sharding, which allows for data to be distributed across multiple servers. For an example of how to create a sharded cluster, see Create a Sharded Database Cluster.

Resources: Cluster instances are Virtual Servers with a boot and a data volume attached. The data volume is encrypted at rest.

BI Connector: The MongoDB Connector for BI allows you to query MongoDB data with SQL using tools such as Tableau, Power BI, and Excel. For an example of how to create a cluster with a BI Connector, see Enable the BI Connector.

Network: Clusters can only be accessed via private LANs.

High availability: Multi-instance clusters across different physical hosts with automatic data replication and failure handling.

Security: Communication between instances and between the client and the cluster is protected with Transport Layer Security (TLS) using Let's Encrypt.

Backup: Daily snapshots are kept for up to seven days.

Restore: Databases can be restored from a specific snapshot given by its ID or restored from a point in time given by a timestamp.

Offsite Backup: Backup data is stored in a location other than the deployed database cluster.

Enterprise Support: With MongoDB Enterprise, you gain access to professional support from the MongoDB team ensuring that you receive timely assistance and expert guidance when needed. IONOS offers enterprise-grade Service Level Agreements (SLAs), guaranteeing rapid response times and 24/7 support to address any critical issues that may arise.

Platform Tasks

Note: IONOS Cloud does not allow full access to the MongoDB cluster. For example, due to security reasons, you cannot use all roles and need to create users via the IONOS API.

DBaaS services offered by IONOS Cloud:

Our platform is responsible for all back-end operations required to maintain your database in optimal operational health. The following services are offered:

Database management via the DCD or the DBaaS API.
Configuring default values, for example for data replication and security-related settings.
Automated backups for 7 days.
Regular patches and upgrades during the maintenance.
Disaster recovery via automated backup.
Service monitoring: both for the database and the underlying infrastructure.

Customer database administration duties:

Tasks related to the optimal health of the database remain the responsibility of the user. These include:

choosing adequate sizing,
data organization,
creation of indexes,
updating statistics, and
consultation of access plans to optimize queries.

Terminology

Cluster: The whole MongoDB cluster is currently equal to the replica set.
Instance: A single server or replica set member inside a MongoDB cluster.

High Availability

Cluster options

To guarantee partition tolerance, only odd numbers of cluster members are allowed. For the playground edition you can only have 1 replica. All other editions allow the use of 3 replicas. Soon we will allow more than 3 replicas per cluster.

The secondary instances are automatically highly available and replicate your data between instances. One instance is the primary, which accepts write transactions, and the others are secondary, which can optionally be used for read operations.

Replication

The instances in an IONOS MongoDB cluster are members of the same replica set, so all secondary instances replicate the data from the primary instance.

By default the write concern before acknowledging a write operations is set to "majority" with j: true. The term "majority" means the write operation must be propagated to the majority of instances. In a three-instance cluster, for example, at least two instances must have the operation before the primary acknowledges it. The j option also requires that the change has already been persisted to the on-disk journal of these instances.

If data is not replicated to the majority, it may be lost in the event of a primary instance failure and subsequent rollback.

Changing the commit guarantees per transaction

You can change the write concern for single operations, for example due to performance reasons. For more information, see Write Acknowledgement.

Read preferences

You can determine which instance to use for read operations by setting the read preference on the client side, if your client supports it. For more information, see Read Preference.

If you read from the primary instance, you always get the most up-to-date data. You can spread the load by reading from secondary sources, but you might get stale data. However, you can get consistency guarantees using a Read Concern.

Maintenance Window

Maintenance window is a weekly four-hour window. All changes that may cause service interruption (like upgrades) will be executed within the maintenance windows. During maintenance window, an uncontrolled disconnections and inability to connect to cluster can happen. Such disconnections are destructive for any ongoing transactions and also clients should reconnect.

Maintenance window configuration

Maintenance window consists of two parts. The first part specifies the day of the week, while the second part specifies the expected time. Here is an example of a maintenance window configuration:

...
"maintenanceWindow": {
      "time": "15:39:01",
      "dayOfTheWeek": "Friday"
    },
 ...

For more information, see Create a Cluster.

Backup and Recovery

Backups

MongoDB Backups: A cluster can have multiple snapshots. A snapshot is a copy of the data in the cluster at a certain time and is added during the following cases:

When a cluster is created, known as initial sync which usually happens in less than 24 hours.
After a restore.
Every 24 hours, a base snapshot is taken, and every Sunday, a full snapshot is taken.

Snapshots are retained for the last seven days; hence, recovery is possible for up to a week from the current date. You can restore from any snapshot as long as it was created with the same or older MongoDB patch version.

Snapshots are stored in an IONOS S3 Object Storage bucket in the same region as your database. Databases in regions where IONOS S3 Object Storage is not available is backed up to eu-central-2.

Warning: If you destroy a MongoDB cluster, all of its snapshots are also deleted.

Offsite Backup

MongoDB Enterprise edition supports Offsite Backups, this allows backup data being stored in a location other than the deployed database cluster.

Available locations are de, eu-south-2, eu-central-2.

Info: The location can only be set during cluster creation. Changes to the backup location of a provisioned cluster will result in unexpected behaviour.

Request

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties": {
        "edition": "enterprise",
        "backup": {
          "location": "de"
        },
        ...
    }' \
    https://api.ionos.com/databases/mongodb/clusters

Recovery

Recovery is achieved via the restore jobs. A restore job is responsible to create and catalog a cluster restoration process. A valid snapshot reference is required for a restore job to recover the database. The API exposes available snapshots of a cluster.

There must be no other active restore job for the cluster to create a new one.

Warning: When restoring a database, it is advised to avoid connections to it until its restore job is complete and the cluster reaches AVAILABLE state.

Point in time recovery

This feature is available only for enterprise clusters. The restoration of cluster here includes points in time and operations log (oplog) timestamps. A custom snapshot can be created for the exact oplog timestamp that you choose to restore the database cluster is possible with point in time recovery.

For more information on restoring database from backup by using the Cloud API, see Restore a Database.

Sizing

Note: Currently, DBaaS - MongoDB does not support scaling existing clusters.

RAM

The WiredTiger cache uses only a part of the RAM; the remainder is available for other system services and MongoDB calculations. The size of the RAM used for caching is calculated as 50% of (RAM size - 1 GB) with a minimum of 256 MB. For example, a 1 GB RAM instance uses 256 MB, a 2 GB RAM instance uses 512 MB, a 4 GB instance uses 1.5 GB, and so on.

You get the best performance if your working set fits into the cache, but it is not required. The working set is the size of all indexes plus the size of all frequently accessed documents.

To view the size of all databases' indexes and documents, you can use a similar script as described in the MongoDB Atlas documentation. You must estimate what percentage of all documents are accessed at the same time based on your knowledge of the workload.

Additionally, each connection can use up to 1 MB of RAM that is not used by WiredTiger.

Disk

The disk contains:

Logs written by MongoD and MongoS (in case of a sharded cluster). They can take up to 2% of the disk space before MongoDB deletes them.
OpLogs for the last 24 hours. The size of these depends on your workload. There is no upper limit, so they can grow quite large. But they are removed after 24 hours on their own.
The data itself. Operating systems and applications are kept separately outside the configured storage and are managed by IONOS.

Limitations

Connection Limits: As each connection requires a separate thread, the number of connections is limited to 51200 connections.

CPU: The total upper limit for CPU cores depends on your quota. A single instance cannot exceed 31 cores.

RAM: The total upper limit for RAM depends on your quota. A single instance cannot exceed 230 GB.

Storage: The upper limit for storage size is 4 TB.

Backups: Storing cluster backups is limited to the last 7 days. Deleting a cluster also immediately removes all backups of it.

IP Ranges: The following IP ranges cannot be used with our MongoDB services:

172.16.0.0/12
192.168.230.0/24

DCD How-Tos

From the DCD, you can create and manage MongoDB Clusters. In the DCD > Databases, you can view the resource allocation details for your user account that shows details of CPU Cores, RAM (in GB), and Storage data. In the MongoDB, you can create database clusters in the following editions: Playground, Business, and Enterprise. Each of these editions offer varied resource allocation templates and advanced features that you could choose from that suits your enterprise needs. For information on creating a MongoDB cluster via the DCD, see Set up a MongoDB Cluster.

Note: The Database Manager is available for contract administrators, owners, and users with Access and manage DBaaS privileges only. You can set the privilege via the DCD group privileges. For more information, see Assigning Privileges to Groups.

Set Up a MongoDB Cluster

You can add a MongoDB cluster on any of the following editions: Playground, Business, or Enterprise.

Create a Cluster

Prerequisites: Before setting up a database, make sure you are working within a provisioned that contains at least one virtual machine () from which to access the database. The VM you create is counted against the quota allocated in your contract. For more information on databases quota, see .

Note: Database Manager is available for contract administrators, owners, and users with Access and manage DBaaS privileges only. You can set the privilege via the DCD group privileges.

1. In the , click the Databases menu.

2. In the Databases page, click + Add in the MongoDB Clusters section.

3. Provide an appropriate Display Name.

4. From the drop-down list, choose a Location where your data for the database cluster can be stored. You can select an available data center within the cluster's data directory to create your cluster.

5. Choose the Edition type as Playground. In this edition, you can create one playground instance for free and test MongoDB.

Note: For every additional instance that you create apart from the first instance, the charges are applicable accordingly.

6. Select the Template to use the resources for creating your MongoDB cluster. In the Playground edition, the following standard resources are available:

RAM Size (GB): 2.
vCPU: 1.
Storage Size: 50 GB.

7. Select the Database Type as the Replica Set. This database type maintains replicas of data sets and offers redundancy and high data availability.

Note: The Sharded Cluster database type is not available for selection in the Playground edition.

8. Select the Instances to host a logical database manager environment to catalog your databases. By default, one instance is offered for free in this edition.

Note: The Estimated price will be displayed based on the input. The estimated cost is exclusive, where certain variables like traffic and backup are not considered.

9. In the Cluster to Datacenter Connection section, set up the following:

Select a Data Center: Select a data center from the available list. Use the search option to enter a data center that you want to select.
LAN in the selected Datacenter: Select a LAN for the chosen data center.

10. In the Private IP/Subnet, perform the following actions:

Private IP/Subnet: Enter the private IP or subnet address in the correct format by using the available Private IPs.

Note: To know your private IP address/Subnet, you need to:

Create a single server connected to an empty private LAN and check the IP assigned to that NIC in that LAN. The DHCP in that LAN is always using a /24 subnet, so you have to reuse the first 3 IP blocks to reach your database.
To prevent a collision with the DHCP IP range, it is recommended to use IP addresses ending between x.x.x.3/24 and x.x.x.10/24 (which are never assigned by DHCP).
If you have disabled DHCP on your private LAN, then you need to discover the IP address on your own.

Click Add to save the private IP/Subnet address details.
Click Add Connection to connect the cluster to the data center.

11. Select the appropriate MongoDB Version. The IONOS Database Manager supports 5.0 and 6.0 MongoDB versions.

12. In the Maintenance Window, set the following:

Maintenance time: Set the time (in UTC) for the maintenance of the MongoDB cluster. Use the pre-defined format (hh:mm:ss) or you can use the clock. The maintenance occurs in a 4-hour-long window, adjust the time accordingly.
Maintenance day: From the dropdown menu, choose the preferred day on which the maintenance of the cluster must take place.

13. Click Save to provision the creation of the MongoDB cluster.

Result: The MongoDB cluster for the defined values is created in the Playground edition.

2. In the Databases page, click + Add in the MongoDB Clusters section.

3. Provide an appropriate Display Name.

5. Choose the Edition type as Business.

6. Select the Template to use the resources needed for creating your MongoDB cluster. In the Business edition, the resources varying from MongoDB Business XS to MongoDB Business 4XL_S are made available. Each template differs based on the RAM Size (GB), vCPU, and Storage Size.

Note: Depending on the resource limit allocation as per your contract, some of the templates may not be available for selection.

7. Select the Database Type as the Replica Set. This database type maintains replicas of data sets and offers redundancy and high availability of data.

Note: The Sharded Cluster database type is not available for selection in the Business edition.

8. Choose the Instances to host a logical database manager environment to catalog your databases. By default, one instance and three instances are possible in the Business edition.

Note: The Estimated price will be displayed based on the input. The estimated cost is exclusive, where certain variables like traffic and backup are not considered.

9. In the Cluster to Datacenter Connection section, set up the following:

Select a Data Center: Select a data center from the available list. Use the search option to enter a data center that you want to select.
LAN in the selected Datacenter: Select a LAN for your data center.

10. In the Private IP/Subnet, perform the following actions:

Private IP/Subnet: Enter the private IP or subnet address in the correct format by using the available Private IPs. Depending on the number of instances selected in step 8, you need to enter one private IP/Subnet address detail for every instance.

Note: To know your private IP address/Subnet, you need to:

Create a single server connected to an empty private LAN and check the IP assigned to that NIC in that LAN. The DHCP in that LAN is always using a /24 subnet, so you have to reuse the first 3 IP blocks to reach your database.
To prevent a collision with the DHCP IP range, it is recommended to use IP addresses ending between x.x.x.3/24 and x.x.x.10/24 (which are never assigned by DHCP).
If you have disabled DHCP on your private LAN, then you need to discover the IP address on your own.

Click Add to save the private IP/Subnet address details.
Click Add Connection to connect the cluster to the data center.

11. Select the appropriate MongoDB Version. The IONOS Database Manager supports 5.0 and 6.0 MongoDB versions.

12. In the Maintenance Window, set the following:

Maintenance time: Set the time (in UTC) for the maintenance of the MongoDB cluster. Use the pre-defined format (hh:mm:ss) or you can use the clock. The maintenance occurs in a 4-hour-long window, adjust the time accordingly.
Maintenance day: From the dropdown menu, choose the preferred day on which the maintenance of the cluster must take place.

13. Click Save to provision the creation of the MongoDB cluster.

Result: The MongoDB cluster for the defined values is created in the Business edition.

1. In the DCD, click the Databases menu.

2. In the Databases page, click + Add in the MongoDB Clusters section.

3. Provide an appropriate Display Name.

5. Choose the Edition type as Enterprise.

6. Choose the following resources for creating each node of your MongoDB cluster. The total billed resources will be these values multiplied by the number of instances and the number of shards (if applicable).

CPU Cores: You can choose between 1 and 31 CPU cores using the slider or choose from the available shortcut values.
RAM Size (GB): Values of up to 230 GB RAM sizes are possible. Select the RAM size using the slider or choose from the available shortcut values.
Storage Size: Set the storage size value to at least 100 GB in case of SSD Standard and Premium storage types for optimal performance of the database cluster. You can configure the storage size to a maximum of 4 TB.

7. Select the Database Type from the following:

Replica Set: Maintains replicas of datasets; offers redundancy and high availability of data.
Sharded Cluster: Maintains collection of datasets that are distributed across many shards (servers) and hence offers horizontal scalability. Define the Amount of Shards between two to a maximum of thirty-two shards.

Note: For sharded clusters, an additional three config server instances are created with sizing of two cores, 4 GB of memory, and 40 GB of storage each. These instances are excluded from the billed resources.

8. Choose the Instances to host a logical database manager environment to catalog your databases. By default, three instances are possible in the Enterprise edition.

Note: The Estimated price will be displayed based on the input. The estimated cost is exclusive, where certain variables like traffic and backup are not considered.

9. In the Cluster to Datacenter Connection section, set up the following:

Select a Data Center: Select a data center from the available list. Use the search option to enter a data center that you want to select.
LAN in the selected Datacenter: Select a LAN for your data center.

10. In the Private IP/Subnet, perform the following actions:

Private IP/Subnet: Enter the private IP or subnet address in the correct format by using the available Private IPs. Depending on the number of instances selected in step 8, you need to enter one private IP/Subnet address detail for every instance.

Note: To know your private IP address/Subnet, you need to:

Create a single server connected to an empty private LAN and check the IP assigned to that NIC in that LAN. The DHCP in that LAN is always using a /24 subnet, so you have to reuse the first 3 IP blocks to reach your database.
To prevent a collision with the DHCP IP range, it is recommended to use IP addresses ending between x.x.x.3/24 and x.x.x.10/24 (which are never assigned by DHCP).
If you have disabled DHCP on your private LAN, then you need to discover the IP address on your own.

Click Add to save the private IP/Subnet address details.
Click Add Connection to connect the cluster to the data center.

11. Select the appropriate MongoDB Version. The IONOS Database Manager supports 5.0 and 6.0 MongoDB versions.

12. Choose a Backup Location that is explicitly the location of your backup (region). You can have off-site backups by using a region that is not included in your database region.

13. Toggle on the Enable BI Connector to enable the MongoDB Connector for Business Intelligence (BI) to query a MongoDB database by using SQL commands to aid in the data analysis. If you do not want to use BI Connector, you can toggle off this setting.

14. In the Maintenance Window, set the following:

Maintenance time: Set the time (in UTC) for the maintenance of the MongoDB cluster. Use the pre-defined format (hh:mm:ss) or you can use the clock. The maintenance occurs in a 4-hour-long window, adjust the time accordingly.
Maintenance day: From the dropdown menu, choose the preferred day on which the maintenance of the cluster must take place.

15. Click Save to provision the creation of the MongoDB cluster.

Result: The MongoDB cluster for the defined values is created in the Enterprise edition.

Update a MongoDB Cluster

You can update an existing MongoDB cluster on any of the following editions: Playground, Business, or Enterprise.

Edit a Cluster

Prerequisites: Make sure the MongoDB database cluster is added by following the steps in Set up a MongoDB Cluster.

Note: All the available MongoDB clusters that are part of your contract are listed under the MongoDB Clusters section on the Databases page.

1. In the Data Center Designer, click the Databases menu.

2. In the Databases page under the MongoDB Clusters section, click the database cluster that is added for the Playground edition.

Note: From this page, you can perform the following actions: Copy connection URI and User Management .

4. In the Edit Form, you can update the following cluster details:

Display Name: Edit the name of the MongoDB cluster.
Edition: You can upgrade the existing cluster edition from Playground to either Business or Enterprise.
Template: Based on the edition selected, choose from the list of templates you want to update the cluster with.
Instances: Depending on the edition and template selected, you would see the allowed number of instances you could choose from. For example, if the existing cluster is updated to Business edition and a MongoDB Business S template is selected, then, you could choose to edit the number of instances to either one or three instances.

Note: The Estimated price will be displayed based on the input. The estimated cost is exclusive, where certain variables like traffic and backup are not considered.

Delete an existing IP address.
Add new Private IP/Subnet List.

6. In the Maintenance Window, you can edit the following details:

Maintenance time: Choose the appropriate time from the clock displayed.
Maintenance day: From the dropdown list, modify the preferred day on which the maintenance of the cluster must take place.

7. Click Save to provision your changes.

Result: The existing MongoDB cluster is updated with the newly defined values. You can review the updated cluster details under the Properties section.

Next steps: In editing a cluster, you can also perform the following actions:

In the User Management section, click Add to create and manage user roles for the MongoDB cluster. For more information, see Roles.

Note: Database snapshots are not available for clusters in the Playground edition. For more information, see Features.

1. In the Data Center Designer, click the Databases menu.

2. In the Databases page under the MongoDB Clusters section, click the database cluster that is added for the Business edition.

4. In the Edit Form, you can update the following cluster details:

Display Name: Edit the name of the MongoDB cluster.
Edition: You can upgrade the existing cluster edition from Business to Enterprise.
Template: Based on the edition selected, choose from the list of templates you want to update the cluster with.
Instances: Depending on the edition and template selected, you would see the allowed number of instances you could choose from. For example, if the existing cluster is updated to Business edition and a MongoDB Business L template is selected, then, you could choose to edit the instances to either one or three instances.

Note: The Estimated price will be displayed based on the input. The estimated cost is exclusive, where certain variables like traffic and backup are not considered.

Delete an existing IP address.
Add new Private IP/Subnet List.

6. In the Maintenance Window, you can edit the following details:

Maintenance time: Choose the appropriate time from the clock displayed.
Maintenance day: From the dropdown list, modify the preferred day on which the maintenance of the cluster must take place.

7. Click Save to provision your changes.

Result: The existing MongoDB cluster is updated with the newly defined values. You can review the updated cluster details under the Properties section.

Next steps: In editing a cluster, you can also perform the following actions:

In the User Management section, click Add to create and manage user roles for the MongoDB cluster. For more information, see Roles.
In the Snapshots section, restore the data in the cluster from the selected snapshot. For more information, see Restore a MongoDB Cluster via the DCD.

Note: When you delete a cluster, all of its backup data is also immediately deleted.

1. In the Data Center Designer, click the Databases menu.

2. In the Databases page, click the database cluster that is added for the Enterprise edition.

4. In the Edit Form, you can update the following cluster details:

Display Name: Edit the name of the MongoDB cluster.
Edition: You can only view the existing cluster edition set as Enterprise.

Note: At this time, it is not possible to downgrade from the Enterprise edition to any other edition.

CPU Cores: Update the number of CPU cores between 1 and 31 cores using the slider or choose from the available shortcut values.
RAM Size (GB): Update RAM size for up to 230 GB is possible. Select the RAM size using the slider or choose from the available shortcut values.
Instances: Choose from three, five, or seven instances to host a logical database manager environment to catalog your databases.

Note: At this time, downscaling of instances is not supported.

Note: The Estimated price will be displayed based on the input. The estimated cost is exclusive, where certain variables like traffic and backup are not considered.

Delete an existing IP address.
Add new Private IP/Subnet List.

6. Toggle on or off the Enable BI Connector. It is advised to enable the MongoDB Connector for Business Intelligence (BI) to query a MongoDB database by using SQL commands to aid in the data analysis.

7. Update the offsite Backup Location to allow backup data to be stored in a location other than the deployed database cluster. Available backup locations: de, eu-south-2, eu-central-2.

8. In the Maintenance Window, you can edit the following details:

Maintenance time: Choose the appropriate time from the clock displayed.
Maintenance day: From the dropdown list, modify the preferred day on which the maintenance of the cluster must take place.

9. Click Save to provision your changes.

Result: The existing MongoDB cluster is updated with the newly defined values. You can review the updated cluster details under the Properties section.

Next steps: In editing a cluster, you can also perform the following actions:

In the User Management section, click Add to create and manage user roles for the MongoDB cluster. For more information, see Roles.
In the Snapshots section, restore the data in the cluster from the selected snapshot. For more information, see Restore a MongoDB Cluster via the DCD.

Note: When you delete a cluster, all of its backup data is also immediately deleted.

Restore a MongoDB Cluster

You can restore a MongoDB cluster by using a snapshot reference. A cluster can have multiple snapshots for backup and are retained for seven days; hence, cluster recovery is possible for up to a week from the current date. For more information, see Backup and Recovery.

MongoDB database cluster backups are available only in the following editions: MongoDB Business and MongoDB Enterprise.

Note: Backups are disabled for the Playground edition.

Restore a Cluster

Note: All the available MongoDB clusters that are part of your contract are listed under the MongoDB Clusters section on the Databases page.

1. In the Data Center Designer, click the Databases menu.

2. In the Databases page under the MongoDB Clusters section, click the database cluster that is added for the Business edition.

3. In the Snapshots section, choose the snapshot you want to use for restoring the database cluster from the list of available snapshots.

Note: Each snapshot displays the following details:

Version: The MongoDB version number of the database cluster.
Created: A date and time when the database snapshot was created. For more information on instances when the snapshots are added, see Backups.
Size: Snapshot database cluster size (in MB).

4. Click Restore on the snapshot selected for restoring the data in the cluster.

5. Confirm the database restore from the snapshot by entering your password and clicking Yes, I'm sure.

Result: The database restore from the selected snapshot is successfully initiated.

Note:

The operation of database restore from the snapshot cannot be undone once confirmed. For more information, see Backup and Recovery.
You cannot initiate a new database restore of a cluster from a snapshot when a restore is already in progress.

1. In the Data Center Designer, click the Databases menu.

2. In the Databases page under the MongoDB Clusters section, click the database cluster that is added for the Enterprise edition.

3. In the Snapshots section, choose from the following two options to restore a database cluster:

1. Restore by time: Restores the database cluster from a specific point-in-time of the database backup.

Choose the backup time from the calendar displayed and click Save. The number of hours in the past from which the backup is possible is between 1 and 24 hours. The default value is 24 hours.

Confirm the database restore from the snapshot by entering your password and clicking Yes, I'm sure.

2. Restore: Choose the snapshot you want to use for restoring the database cluster from the list of available snapshots.

Click Restore.

Confirm the database restore from the snapshot by entering your password and clicking Yes, I'm sure.

Note: Each snapshot displays the following details:

Version: The MongoDB version number of the database cluster.
Created: A date and time when the database snapshot was created. For more information on instances when the snapshots are added, see Backups.
Size: Snapshot database cluster size (in MB).

Result: The database restore from the selected snapshot is successfully initiated.

Note:

The operation of database restore from the snapshot cannot be undone once confirmed. For more information, see Backup and Recovery.
You cannot initiate a new database restore of a cluster from a snapshot when a restore is already in progress.

API How-Tos

The Cloud API lets you manage MongoDB database clusters programmatically by using the conventional HTTP requests. The creation of MongoDB cluster functionality that is available in the IONOS Cloud DCD is also available through the API.

You can also use the Cloud API to perform the following actions: modify cluster attributes, create sharded clusters, enable the BI connector, manage user access to clusters, access logs, migration of databases, and restore a database cluster.

DBaaS API - OpenAPI Specification

Endpoint: https://api.ionos.com/databases/mongodb

To make authenticated requests to the API, you need to include a few fields in the request headers. Following are the relevant request parameters and descriptions:

Request parameter headers

Header

Required

Type

Description

Examples

We use curl in our examples, as this tool is available on Windows 10, Linux and macOS. Please refer to our blogpost about curl on Windows if you encounter any problems:

Create a Cluster

IONOS MongoDB API allows you to create a MongoDB cluster.

Prerequisites

Before creating a cluster, make sure you have:

A data center.
Private LAN in that data center.
At least one client-server is connected to the private LAN. To connect to your cluster, clients must be able to resolve public DNS entries.

In the following examples, we assume that you want to use the data center UUID b1432c51-c20a-4f83-876f-c3a8a9e1fbec.

Sizing considerations

To list the available sizing templates using the API:

Request

Response

Currently, we do not support changing instance sizes for single instance clusters. You would need to create a new cluster for this.

For the following examples, we assume that you want to create a small test cluster and therefore chose the template 15c6dd2f-02d2-4987-b439-9a58dd59ecc3.

Sizing considerations

CPU, RAM, storage, and storage type are provided and not limited by a set of predefined templates as in the business edition.

Currently, we don't support changing the cluster storage size for single instance clusters. You would need to create a new cluster to change the cluster storage size.

Preparing the network

Currently, the database cluster does not have automatic IP address management, and the only supported subnet is /24. To create a MongoDB cluster, specify as many free IP addresses as the number of instances in your cluster. Make sure that the IP addresses are not used by other servers in your LAN. You can choose the IP address by using one of the following methods:

You can choose the IP addresses of the subnet assigned to you by IONOS if you rely on IONOS-provided DHCP. The Network Interface Card (NIC) configuration contains information about the subnet. To prevent a collision with the DHCP IP range, choose an IP address between x.x.x.3/24 and x.x.x.10/24. The IONOS DHCP never assigns IP addresses in that range.
If you run your own DHCP, select IP addresses that cannot be assigned by your DHCP server.
If you assign IP addresses manually, you may use any IP addresses in that subnet and need to make sure that it is not used anywhere else.

For example, assume your private LAN uses the IP range 10.1.1.0/24 and you want a cluster with three instances. Then, you could provide us with the IP addresses 10.1.1.3/24, 10.1.1.4/24 and 10.1.1.5/24. Note that the prefix length (/24) still is the same as for the whole subnet. We only use the single IPs that you specify, but we need the prefix length to configure routing correctly.

Warning: You cannot delete a LAN while a database cluster is still attached. If you want to delete the LAN, then first delete the database cluster.

Creating the cluster

This request creates a database cluster with three instances of MongoDB version 5.0.

Note: Only contract administrators and owners can create and change database clusters. In contrast, the running database cluster can be accessed from all servers in the specified LAN.

Request

Response

Note: We will use 498ae72f-411f-11eb-9d07-046c59cc737e as example for the cluster ID in following examples.

Creating the cluster

This request will create a database cluster with three instances of MongoDB version 6.0.

Note: The use of these enterprise attributes. edition specifies an enterprise edition. cores specifies the number of CPUs. ram specifies the RAM amount in MB. storageSize specifies the storage amount in MB. storageType specifies the storage type. The possible values are HDD, SSD Standard, and SSD Premium

Note: Only contract administrators and owners can create and change database clusters. However, the running database cluster can be accessed from all servers in the specified LAN.

Request

Response

Note: In the following examples, we use 498ae72f-411f-11eb-9d07-046c59cc737e as the cluster ID.

Querying database status

You may have noticed that the state is BUSY and that the database cluster is unreachable. This is because the cloud creates a completely new cluster and needs to provision new instances. This process runs asynchronously in the background and might take several minutes.

You can poll the API to see when the state switches to AVAILABLE and health to HEALTHY meaning a fully functional cluster.

Request

To query a single cluster, you require the id from your "create" response.

If you do not know your MongoDB cluster-ID, you can also list all clusters and look for the one for which to query the status.

Response

Connect to cluster

Now that the cluster is available, you can connect to your MongoDB cluster using the mongo shell tool and the connection string from the API response and should see the mongo shell prompt:

Reminder: The connection must be performed from an extra VM.

Authentication

Connecting to a MongoDB cluster doesn't require authentication. However, nearly all other operations with a cluster require authentication. For example, when you try to list all databases:

Assume you have created a user jdoeionos on database example with the role readWrite on example. Then you can authenticate like this: and can afterward write and read data:

Result: You now have a ready-to-use MongoDB cluster.

Create a Sharded Database Cluster

This section shows you how to create a MongoDB sharded cluster using the IONOS API. This feature is available only for enterprise clusters.

For information about prerequisites to retrieve the data center UUID, query database status, connect to the cluster, and prepare the network, see Create a Cluster.

Create the cluster

This request creates a MongoDB version 6.0 sharded database cluster of two shards with three replicas each. The size of each node is specified in the request.

Note: The use of shards in the request identifies the number of shards, while type defines the cluster as a sharded cluster.

Note: Only contract administrators and owners can create and change database clusters. In contrast, the running database cluster can be accessed from all servers in the specified LAN.

Resource consumption

In total, six database nodes are created, and consequently, the number of billed resources is 24 cores, 12 GB memory, and 120 GB storage.

Note: In addition, a set of three config servers is created with two cores, 4 GB memory, and 40 GB storage each. These are excluded from the billed resources.

Request

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties":
        {
        "mongoDBVersion": "6.0",
        "instances": 3,
        "location": "de/fra",
        "displayName": "a good name for a database",
        "connections": [
          {
            "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
            "lanId": "28",
            "cidrList": ["10.1.1.3/24", "10.1.1.4/24", "10.1.1.5/24"]
          }
        ],
        "type": "sharded-cluster",
        "shards": 2,
        "edition": "enterprise",
        "cores": 4,
        "ram": 2048,
        "storageSize": 20000,
        "storageType": "HDD"
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters

Response

Note: We will use 498ae72f-411f-11eb-9d07-046c59cc737e as example for the cluster ID in following examples.

{
  "type": "cluster",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "metadata": {
    "state": "BUSY",
    "health": "UNKNOWN",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "displayName": "a good name for a database",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
        "lanId": "28",
        "cidrList": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "instances": 3,
    "shards": 2,
    "edition": "enterprise",
    "cores": 4,
    "ram": 2048,
    "storageSize": 20000,
    "storageType": "HDD",
    "type": "sharded-cluster",
    "maintenanceWindow": {
      "time": "15:39:01",
      "dayOfTheWeek": "Friday"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

At this point, you have created your first MongoDB sharded cluster. The deployment of the database takes several minutes. For more information about determining if your cluster is ready, see Querying database status.

When the cluster is ready, add the role enableSharding to a user in order to allow shard management capabilities. For managing user roles, see Changing the roles. Only users with enableSharding role can shard a collection. For more information, see shardCollection.

Modify Cluster Attributes

Once the MongoDB cluster is up and running, you can customize several attributes.

Renaming the database cluster

With the PATCH request, you can change the name of your database cluster.

Note: The sample UUID is d02de413-d5af-4104-a6f9-3a3c2766ee61

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "displayName": "an even better name!"
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/d02de413-d5af-4104-a6f9-3a3c2766ee61

Response

{
  "type": "cluster",
  "id": "d02de413-d5af-4104-a6f9-3a3c2766ee61",
  "metadata": {
    "state": "AVAILABLE",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e",
    "lastModifiedDate": "2020-12-18T21:37:50.000Z",
    "lastModifiedBy": "clientname@ionos.com",
    "lastModifiedByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "displayName": "an even better name!",
    "location": "de/fra"
  },
  ...
}

Upgrading the MongoDB version

DBaaS supports MongoDB versions 5.0 and 6.0. We keep the MongoDB minor version up to date with the MongoDB's latest release for that major version.

Changing the version of a running MongoDB cluster via the API is not allowed.

Scaling a cluster vertically (RAM, CPU, Storage)

DBaaS allows you to scale up and down the size of your database instances. Database instance sizes are managed similarly to Cubes; each template exposes a combination of resource sizes that can be assigned to any of your clusters.

Note: You can get a list of available MongoDB Templates via the API.

curl --include \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    https://api.ionos.com/databases/mongodb/templates

To change the template, issue a PATCH request containing the MongoDB Template ID:

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "templateID": "6b78ea06-ee0e-4689-998c-fc9c46e781f6"
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/d02de413-d5af-4104-a6f9-3a3c2766ee61

{
  "type": "cluster",
  "id": "d02de413-d5af-4104-a6f9-3a3c2766ee61",
  "metadata": {
    "state": "BUSY",
    "health": "DEGRADED",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "type": "replicaset",
    "edition": "business",
    "displayName": "Represents database name",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
        "lanId": "28",
        "cidrList": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "templateID": "15c6dd2f-02d2-4987-b439-9a58dd59ecc3",
    "instances": 3,
    "maintenanceWindow": {
      "time": "16:30:59",
      "dayOfTheWeek": "Monday"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

The provisioning engine will delete a secondary replica and create a new server of the desired size. Once ready, it will replicate the existing data to this new server via the MongoDB Replication mechanism. During this procedure, the cluster should operate normally. When the provisioning engine identifies the new server is complete and healthy, it will continue the rollout for every remaining secondary replica up to the primary.

Note: Be prepared for a possible downtime in case of a cluster with only one replica.

Note: Decreasing storageSize to a size lower than your consumed storage is not allowed.

Scaling a cluster vertically (RAM, CPU, Storage)

MongoDB for the Enterprise Edition allow you to freely choose the amount of CPU, RAM and Storage for your cluster. Additionally, you can also choose between the following available StorageTypes: HDD, SSD and SSD Premium.

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "edition": "enterprise",
        "cores": 2,
        "ram": 2048,
        "storageSize": 10240,
        "storageType": "HDD"
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/d02de413-d5af-4104-a6f9-3a3c2766ee61

{
  "type": "cluster",
  "id": "d02de413-d5af-4104-a6f9-3a3c2766ee61",
  "metadata": {
    "state": "BUSY",
    "health": "HEALTHY",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "type": "replicaset",
    "edition": "enterprise",
    "cores": 2,
    "ram": 2048,
    "storageSize": 10240,
    "storageType": "HDD",
    "displayName": "Represents database name",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
        "lanId": "28",
        "cidrList": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "instances": 3,
    "maintenanceWindow": {
      "time": "16:30:59",
      "dayOfTheWeek": "Monday"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

Note: Decreasing storageSize to a size lower than your consumed storage is not allowed.

Scaling a cluster horizontally (Replicas)

DBaaS allows you to scale up and down the number of database replicas. Increased replica count may result in a cluster with improved availability, performance (capacity to handle more data reads), and fault tolerance for upgrades. A new IP address must be provided for each new instance. To do so, send a PATCH request with the new instances count (supported values are: 1, 3):

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "instances": 3,
        "connections": [
          {
            "datacenterId": "b72ebcf5-6158-4ddb-8f65-31b20d82b6c7",
            "lanId": "2",
            "cidrList": [
              "10.7.222.3/24",
              "10.7.222.4/24",
              "10.7.222.5/24"
            ]
          }
       ]
      }
    }' \
    https://api.ionos.com/cloudapi/databases/mongodb/clusters/d02de413-d5af-4104-a6f9-3a3c2766ee61

{
  "type": "cluster",
  "id": "d02de413-d5af-4104-a6f9-3a3c2766ee61",
  "metadata": {
    "state": "BUSY",
    "health": "HEALTHY",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "type": "replicaset",
    "edition": "enterprise",
    "cores": 2,
    "ram": 2048,
    "storageSize": 10240,
    "storageType": "HDD",
    "displayName": "Represents database name",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b72ebcf5-6158-4ddb-8f65-31b20d82b6c7",
        "lanId": "2",
        "cidrList": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "instances": 3,
    "maintenanceWindow": {
      "time": "16:30:59",
      "dayOfTheWeek": "Monday"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

The patch example takes a previous cluster with one replica and adds two more replicas to it. The two new IP addresses are added to the connection properties cidrList, and the instances property receives the total number of replicas.

New servers are provisioned and added one at a time to the pool of replicas, implying an incremental rollout.

Downgrading a cluster follows the same pattern, with replica sets being removed one at a time and the desired replica set is reached.

Note: Only MongoDB Business edition provides an option to downscale the number of instances. Scaling down may result in one or more failovers and the disruption of open connections.

For more information, see Replica Set Elections.

Increasing number of shards

DBaaS allows you to increase the number of shards for MongoDB Enterprise sharded clusters. An increased shard count increases the overall storage of the cluster.

Note: We recommend you to review the Considerations before adding shards.

To increase the number of shards, send a PATCH request with the new shards count as shown in the following request:

Note: You can increase the number of shards to a maximum of 100.

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "shards": 3
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/d02de413-d5af-4104-a6f9-3a3c2766ee61

The following is a sample response:

{
  "type": "cluster",
  "id": "d02de413-d5af-4104-a6f9-3a3c2766ee61",
  "metadata": {
    "state": "BUSY",
    "health": "HEALTHY",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "displayName": "Represents database name",
    "location": "de/fkb",
    "connections": [
      {
        "datacenterId": "b72ebcf5-6158-4ddb-8f65-31b20d82b6c7",
        "lanId": "2",
        "cidrList": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "mongoDBVersion": "6.0",
    "instances": 3,
    "maintenanceWindow": {
      "dayOfTheWeek": "Thursday",
      "time": "08:53:15"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com",
    "backup": {},
    "edition": "enterprise",
    "cores": 1,
    "ram": 2048,
    "storageSize": 10240,
    "storageType": "SSD Standard",
    "shards": 3,
    "biConnector": {
      "enabled": false
    },
    "type": "sharded-cluster"
  }
}

The PATCH example modifies a previously created sharded cluster and sets the number of shards to three.

New shards added this way are created by provisioning new servers and adding them to the sharded cluster. Each shard has the number of servers provided by the instances field. Sharded collections' data will then be distributed to the new shards. For more information, see Balancer Internals.

Note: Decreasing shards is currently not possible.

Setting maintenance windows

If you do not specify a maintenance window when creating your database, a random window is assigned. You can update the window at any time, as shown in the example.

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "maintenanceWindow": {
          "dayOfTheWeek": "Sunday",
          "time": "03:30:00"
        }
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/d02de413-d5af-4104-a6f9-3a3c2766ee61

{
  "type": "cluster",
  "id": "d02de413-d5af-4104-a6f9-3a3c2766ee61",
  "metadata": {
    "state": "BUSY",
    "health": "HEALTHY",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "maintenanceWindow": {
      "dayOfTheWeek": "Sunday",
      "time": "03:30:00"
    },
    "type": "replicaset",
    "edition": "enterprise",
    "cores": 2,
    "ram": 2048,
    "storageSize": 10240,
    "storageType": "HDD",
    "displayName": "Represents database name",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b72ebcf5-6158-4ddb-8f65-31b20d82b6c7",
        "lanId": "2",
        "cidrList": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "instances": 3,
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

If your cluster only has one replica, you may experience a brief outage while your database instance is being updated during this maintenance window. In a replicated cluster, secondaries are updated first and rolled out one by one; each rollout must be complete and healthy before the next one can begin.

Maintenance windows are used to update the cluster's MongoDB minor version. Other maintenance updates related to the cluster infrastructure and security might take place during a maintenance window.

Updating users and roles

The user management for IONOS MongoDB clusters happens completely via the IONOS API. Creation or modification of users from within MongoDB itself is not allowed. For more information, see Users Management.

Enable the BI Connector

This section shows you how to enable the BI Connector on an existing cluster.

Note: This feature is only available for enterprise clusters.

Modify the cluster

The BI Connector is enabled by modifying a cluster attribute with a PATCH request.

Set biConnector.enabled to true to enable the BI Connector for this cluster.
You can disable it at any time by setting this attribute to false again.

Note: Only contract administrators and owners can create and change database clusters. In contrast, the running database cluster can be accessed from all servers in the specified LAN.

Request

In the following example, a random value 498ae72f-411f-11eb-9d07-046c59cc737e is used as the cluster ID.

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "biConnector": {
          "enabled": true
        }
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/498ae72f-411f-11eb-9d07-046c59cc737e

Response

200 Successful operation

The patched resource is returned.
The biConnector property now includes the host and port attributes needed to connect to the BI Connector. These are read-only attributes and cannot be changed.
At this point, you have enabled the BI Connector on your database.

Note: After the BI Connector is enabled, it may take a few minutes until the connector is ready for connections.

{
  "type": "cluster",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "metadata": {...},
  "properties": {
    ...
    "biConnector": {
      "enabled": true,
      "host": "r1.m-65f4a879f126e3c4.mongodb.de-fra.ionos.com",
      "port": 27015
    },
    ...
  }
}

Users Management

For MongoDB clusters, you have to manage users via the IONOS API and creating users inside the database is not possible. This document shows you in detail how to create, view, and delete users.

Roles

In MongoDB most roles are scoped to a database. For example you grant readWrite permissions on database mydb. The exception are roles that grant permissions to all databases, for example .

Assignable roles have several restrictions to avoid customers breaking out of their database or breaking internal stuff:

Currently, you can only assign . Out of those currently only read, readWrite, readAnyDatabase, readWriteAnyDatabase, dbAdmin, dbAdminAnyDatabase and clusterMonitor are supported.
Roles with the suffix *AnyDatabase are granted only on the admin database, which is the main user management database.
Roles read, readWrite and dbAdmin cannot be granted on config and local databases.

Adding a user

When creating a user you need to consider the following:

All users are created in the admin database.
The combination of username and database must be unique within the MongoDB cluster.
You can only change the assigned roles and the password of a user.
You can't have more than 100 users in a cluster.

To add users to a MongoDB cluster, use the POST request for each user.

Deleting user

To delete a user from MongoDB cluster, use the DELETE request as follows:

Getting all users

To get a list of all users defined in MongoDB cluster, use the GET request as follows:

Getting a single user

To get a specific user in a MongoDB cluster, use the GET request as follows:

Modifying a single user

Changing the password

To update the password of a specific user in a MongoDB cluster, use the PATCH request as follows:

Changing the roles

To update the assigned roles of a specific user in a MongoDB cluster, use the PATCH request with the new list of assigned roles. Note that the request replaces the old role list, meaning that any existing roles missing from the patch will be deleted.

Access Logs

Every running MongoDB instance collects logs from MongoD. Currently, there is no option to change this configuration. The log messages are shipped to a central storage location with a retention policy of 30 days.

Using the cluster ID, you can access the logs for that cluster via the API.

Requesting logs

The endpoint for fetching logs has four optional query parameters:

Parameter

Description

Default value

Possible values

If you omit all parameters, you will get the most recent 100 log messages.

The following example shows how to receive only the first two messages after 12:00 a.m. on January 5, 2022:

curl --include \
    --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    "https://api.ionos.com/databases/mongodb/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/logs?start=2022-01-05T12:00:00Z&end=2022-01-05T13:00:00Z&direction=FORWARD&limit=2"

Response

The response contains the log messages separated per instance and looks similar to this:

{
  "instances": [
    {
      "name": "ionos-498ae72f-411f-11eb-9d07-046c59cc737e-by6qu3m-1",
      "messages": [
        {
          "time": "2022-01-05T12:00:29.793Z",
          "message": "{\"t\":{\"$date\":\"2022-01-05T12:00:29.793+00:00\"},\"s\":\"I\",  \"c\":\"NETWORK\",  \"id\":22943,   \"ctx\":\"listener\",\"msg\":\"Connection accepted\",\"attr\":{\"remote\":\"127.0.0.1:42562\",\"uuid\":\"4ff7c691-8aaa-4ef6-a37d-21386adcbdb0\",\"connectionId\":10751,\"connectionCount\":40}}"
        },
        {
          "time": "2022-01-05T12:00:29.794Z",
          "message": "{\"t\":{\"$date\":\"2022-01-05T12:00:29.794+00:00\"},\"s\":\"I\",  \"c\":\"NETWORK\",  \"id\":22944,   \"ctx\":\"conn10751\",\"msg\":\"Connection ended\",\"attr\":{\"remote\":\"127.0.0.1:42562\",\"uuid\":\"318a7948-4860-4420-ad64-5cd6178f990f\",\"connectionId\":10751,\"connectionCount\":40}}"
        }
      ]
    }
  ]
}

Database Migration

This How-to shows you how to migrate your MongoDB data from one cluster to another one. For example how to migrate from your existing on-premise MongoDB cluster to the IONOS MongoDB cluster.

This migration requires some downtime, as you need to stop write operations to your old cluster during dumping the data.

High level plan

The steps for a migration are as follows:

Preparations
Stop writes to old cluster - start of downtime
Dump data from old cluster using mongodump
Optionally: copy dump
Restore data into new cluster using mongorestore
Use the new cluster - end of downtime

Preparations

A place to run `mongodump` and `mongorestore`

You need one machine that can access the old cluster, that can run mongodump, and one machine that can access the new cluster, that can run mongorestore.

Both can happen on the same machine. If they're two different machines, you need a way to copy the data dump from one machine to the other.

Check MongoDB version

Both clusters need to be running the same major version. You can see the version in the greeting if you connect with mongosh or you can query it with db.version().

Access to old cluster

If your old cluster has access control enabled, you need a user with permissions for find to all databases. Easiest is to grant the backup role to the user that you want to use for dumping the data.

You can then verify that you can connect by using the command for mongodump mentioned in the section "Dump old data" and then aborting the dump with Ctrl-C.

User in new cluster

You need one user with write permissions to all databases that your dump contains.

Additionally you can't restore the users and roles via mongorestore. So you have to create all the users with their credentials and roles via the IONOS API. You can list all the users and roles in your old cluster with db.system.users.find() in the admin database and can then create them in the new cluster according to the documentation on User Management. You can't see the plain text password on your old cluster, so you need to collect them from wherever you stored them.

Dump data from old cluster

Caution: The use of --oplog isn't possible because it requires elevated privileges on restoring. Therefore you need to make sure that no write operations happen during the dump. Otherwise you get an inconsistent dump.

You can dump the data from the old cluster with this command:

mongodump --host="hostname:port" \
  --username="username" --password="password" \
  --authenticationDatabase "admin" \
  --gzip --archive=mongodb.dump

Optionally you can limit data using --db, --collection, or --query flags to only dump specific databases, collections, or documents.

Restore data in new cluster

You can restore the dumped date in the new cluster with this command:

mongorestore --uri "mongodb+srv://username:password@cluster1.example.mongodb.net" \
  --gzip --archive=mongodb.dump \
  --nsExclude "admin.system.*"

admin.system.* resources are excluded, since you can't modify users and roles from inside MongoDB in an IONOS MongoDB cluster. You need to use the IONOS API for them.

Restore a Database

You can restore a database cluster in-place from a previous snapshot.

List available snapshots of a cluster

To restore from a snapshot you will need to provide a snapshot ID. You can request a list of all available snapshots:

Our chosen clusterId is: cc54e0f2-5e49-42bf-97e8-089c2eff0264

Request

curl --include \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    https://api.ionos.com/databases/mongodb/clusters/cc54e0f2-5e49-42bf-97e8-089c2eff0264/snapshots

Response

{
  "type": "collection",
  "id": "cc54e0f2-5e49-42bf-97e8-089c2eff0264",
  "items": [
    {
      "type": "snapshot",
      "id": "e2044962-294a-4c99-b076-414b2a387c58",
      "properties": {
        "mongoDBVersion": "5.0",
        "size": 150,
        "creationTime": "2020-12-10T13:37:50+01:00"
      }
    }
  ],
  "offset": 0,
  "limit": 10,
  "_links": {}
}

Restore from backup in-place

You can now create a restore job for the chosen cluster. Your database will not be available during the restore operation. In order to successfully create a restore job, no other active restore job must exist.

Note: To restore a cluster in-place you can only use snapshots from that cluster.

Note: The cluster will have a BUSY state and must not receive connections.

Restore snapshot request

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "snapshotId": "e2044962-294a-4c99-b076-414b2a387c58",
    }' \
    https://api.ionos.com/databases/mongodb/clusters/cc54e0f2-5e49-42bf-97e8-089c2eff0264/restore

Response

The API will respond with a 202 Accepted status code if the request is successful.

Point in time recovery

Use the recovery target point in time which specifies the exact oplog timestamp that you choose to restore the database cluster.

Point in time recovery request

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "recoveryTargetTime": "2023-04-21T13:37:50+01:00",
    }' \
    https://api.ionos.com/databases/mongodb/clusters/cc54e0f2-5e49-42bf-97e8-089c2eff0264/restore

Response

The API will respond with a 202 Accepted status code if the request is successful.

Note: Check the cluster details in order to see the progress of the restoration.

Connect from Kubernetes

This guide shows you how to connect to a MongoDB cluster from your managed Kubernetes cluster.

Prerequisites

Before connecting to a MongoDB cluster from your managed Kubernetes, make sure you have:

A data center with id xyz-my-datacenter.
A private LAN with id 3.
A MongoDB cluster connected to LAN 3, with the connection string mongodb+srv://m-xyz-example.mongodb.de-txl.ionos.com.
A Kubernetes cluster with id xyz-my-k8s-cluster.
ionosctl set up with your IONOS credentials.

Note: In this guide, we use DHCP to assign IP addresses to node pools. Therefore, it is important that the database is in the same subnet that is used by the DHCP server.

1.To enable connectivity, connect the node pools to the private LAN with the MongoDB cluster.

ionosctl k8s nodepool create --cluster-id xyz-my-k8s-cluster --datacenter-id xyz-my-datacenter --lan-ids 3 --dhcp=true --name=my_nodepool

2. Wait for the node pool to become available. To test the connectivity you can create a pod that contains the MongoDB tool mongosh. If you have multiple node pools, make sure to schedule the pod on one of the node of the node pools that are attached to the private LAN.

# pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: connectivity-test
  labels:
    role: connectivity-test
spec:
  containers:
  - name: mongo
    image: mongo
    stdin: true
    tty: true
    command:
      - "/bin/bash"

3. Create the pod by using the following command:

kubectl apply -f pod.yaml

4. Attach the pod to the cluster by using the following command:

kubectl attach -it connectivity-test
If you do not see a command prompt, try pressing enter.
root@connectivity-test:/# mongosh "mongodb+srv://m-xyz-example.mongodb.de-txl.ionos.com"
Current Mongosh Log ID:	631063ca901a9459bab0b4d4
Connecting to:		mongodb+srv://m-xyz-example.mongodb.de-txl.ionos.com/?appName=mongosh+1.5.4
Using MongoDB:		5.0.10
Using Mongosh:		1.5.4

For mongosh information, see: https://docs.mongodb.com/mongodb-shell/


To help improve our products, anonymous usage data is collected and sent to MongoDB periodically (https://www.mongodb.com/legal/privacy-policy).
You can opt-out by running the disableTelemetry() command.

Enterprise a0def940-2455-11ed-a564-7a0f508690ac [primary] test>

Result: You see the database is accepting connections.

If you see connection issues, make sure that the node is properly connected to the LAN. To debug the node, use a debugging container.

kubectl debug node/$(kubectl get po connectivity-test -o jsonpath="{.spec.nodeName}") -it --image=busybox

Create a Cluster

IONOS MongoDB API allows you to create a MongoDB cluster.

Prerequisites

Before creating a cluster, make sure you have:

A data center.
Private LAN in that data center.
At least one client-server is connected to the private LAN. To connect to your cluster, clients must be able to resolve public DNS entries.

In the following examples, we assume that you want to use the data center UUID b1432c51-c20a-4f83-876f-c3a8a9e1fbec.

Sizing considerations

To list the available sizing templates using the API:

Request

Response

Choose the sizing that fits your use case and specify it on cluster creation. For more information about how to calculate resource usage, see .

Currently, we do not support changing instance sizes for single instance clusters. You would need to create a new cluster for this.

For the following examples, we assume that you want to create a small test cluster and therefore chose the template 15c6dd2f-02d2-4987-b439-9a58dd59ecc3.

Sizing considerations

CPU, RAM, storage, and storage type are provided and not limited by a set of predefined templates as in the business edition.

CPU, RAM, storage, and the number of database clusters are counted against quotas. For more information about how to calculate resource usage, see .

Currently, we don't support changing the cluster storage size for single instance clusters. You would need to create a new cluster to change the cluster storage size.

Database performance depends on the storage type ( HDD, SSD and SSD Premium). Choose the that is suitable for your workload.

Preparing the network

You can choose the IP addresses of the subnet assigned to you by IONOS if you rely on IONOS-provided DHCP. The Network Interface Card (NIC) configuration contains information about the subnet. To prevent a collision with the DHCP IP range, choose an IP address between x.x.x.3/24 and x.x.x.10/24. The IONOS DHCP never assigns IP addresses in that range.
If you run your own DHCP, select IP addresses that cannot be assigned by your DHCP server.
If you assign IP addresses manually, you may use any IP addresses in that subnet and need to make sure that it is not used anywhere else.

Warning: You cannot delete a LAN while a database cluster is still attached. If you want to delete the LAN, then first delete the database cluster.

Creating the cluster

This request creates a database cluster with three instances of MongoDB version 5.0.

Note: Only contract administrators and owners can create and change database clusters. In contrast, the running database cluster can be accessed from all servers in the specified LAN.

Request

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties": {
        "type": "replicaset",
        "edition": "business",
        "mongoDBVersion": "5.0",
        "instances": 3,
        "templateID": "15c6dd2f-02d2-4987-b439-9a58dd59ecc3",
        "location": "de/fra",
        "displayName": "Represents database name",
        "connections": [
          {
            "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
            "lanId": "28",
            "cidrList": ["10.1.1.3/24", "10.1.1.4/24", "10.1.1.5/24"]
          }
        ],
        "maintenanceWindow": {
           "time": "16:30:59",
           "dayOfTheWeek": "Monday"
       }
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters

Response

Note: We will use 498ae72f-411f-11eb-9d07-046c59cc737e as example for the cluster ID in following examples.

{
  "type": "cluster",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "metadata": {
    "state": "BUSY",
    "health": "UNKNOWN",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "type": "replicaset",
    "edition": "business",
    "displayName": "Represents database name",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
        "lanId": "28",
        "cidr": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "templateID": "15c6dd2f-02d2-4987-b439-9a58dd59ecc3",
    "instances": 3,
    "maintenanceWindow": {
      "time": "16:30:59",
      "dayOfTheWeek": "Monday"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

At this point, you have created your first MongoDB cluster. The deployment of the database takes several minutes. To determine when your cluster is ready, see .

Creating the cluster

This request will create a database cluster with three instances of MongoDB version 6.0.

Note: Only contract administrators and owners can create and change database clusters. However, the running database cluster can be accessed from all servers in the specified LAN.

Request

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties": {
        "mongoDBVersion": "6.0",
        "instances": 3,
        "location": "de/fra",
        "displayName": "Represents database name",
        "connections": [
          {
            "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
            "lanId": "28",
            "cidrList": ["10.1.1.3/24", "10.1.1.4/24", "10.1.1.5/24"]
          }
        ]
        "edition": "enterprise",
        "type": "replicaset",
        "cores": 4,
        "ram": 2048,
        "storageSize": 20000,
        "storageType": "HDD",
        "maintenanceWindow": {
           "time": "16:30:59",
           "dayOfTheWeek": "Monday"
       }
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters

Response

Note: In the following examples, we use 498ae72f-411f-11eb-9d07-046c59cc737e as the cluster ID.

{
  "type": "cluster",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "metadata": {
    "state": "BUSY",
    "health": "UNKNOWN",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "displayName": "Represents database name",
    "location": "de/fra",
    "connections": [
      {
        "datacenterId": "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
        "lanId": "28",
        "cidr": [
          "10.1.1.3/24",
          "10.1.1.4/24",
          "10.1.1.5/24"
        ]
      }
    ],
    "edition": "enterprise",
    "type": "replicaset",
    "cores": 4,
    "ram": 2048,
    "storageSize": 20000,
    "storageType": "HDD",
    "instances": 3,
    "maintenanceWindow": {
      "time": "16:30:59",
      "dayOfTheWeek": "Monday"
    },
    "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
  }
}

At this point, you have created your first MongoDB cluster. The deployment of the database takes several minutes. To determine when your cluster is ready, see .

Querying database status

You can poll the API to see when the state switches to AVAILABLE and health to HEALTHY meaning a fully functional cluster.

Request

To query a single cluster, you require the id from your "create" response.

curl --include \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    https://api.ionos.com/databases/mongodb/clusters/498ae72f-411f-11eb-9d07-046c59cc737e

If you do not know your MongoDB cluster-ID, you can also list all clusters and look for the one for which to query the status.

curl --include \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    https://api.ionos.com/databases/mongodb/clusters

Response

{
  "type": "collection",
  "id": "clusters",
  "items": [
    {
      "type": "cluster",
      "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
      "metadata": {
        "state": "AVAILABLE",
        "health": "HEALTHY",
        "createdDate": "2020-12-10T12:37:50.000Z",
        "createdBy": "david.sertic@ionos.com",
        "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e",
      },
      "properties": {
        "displayName": "a good name for a database",
        "location": "de/fra",
        "connectionString": "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com",
      ...
      }
    }
  ],
  "offset": 0,
  "limit": 1,
  "_links": {}
}

Connect to cluster

Now that the cluster is available, you can connect to your MongoDB cluster using the mongo shell tool and the connection string from the API response and should see the mongo shell prompt:

Reminder: The connection must be performed from an extra VM.

$ mongosh "mongodb+srv://m-65f4a879f126e3c4.mongodb.de-fra.ionos.com"
Current Mongosh Log ID: 6304db914f263ebcb3ddaaf2
Connecting to:    mongodb+srv://m-65f4a879f126e3c4.mongodb.de-txl.ionos.com/?appName=mongosh+1.5.4
Using MongoDB:    6.0.10
Using Mongosh:    1.5.4

For mongosh info see: https://docs.mongodb.com/mongodb-shell/


To help improve our products, anonymous usage data is collected and sent to MongoDB periodically (https://www.mongodb.com/legal/privacy-policy).
You can opt-out by running the disableTelemetry() command.

Enterprise 5b8acdcc-22c6-11ed-bc22-c65c3b0754bf [primary] test>

Authentication

Connecting to a MongoDB cluster doesn't require authentication. However, nearly all other operations with a cluster require authentication. For example, when you try to list all databases:

> show dbs
MongoServerError: command listDatabases requires authentication

You cannot create or modify users from within MongoDB itself. The user management for IONOS MongoDB clusters happens completely via the IONOS API. You can read more about this in the documentation on .

Assume you have created a user jdoeionos on database example with the role readWrite on example. Then you can authenticate like this: and can afterward write and read data:

... example> db.exampleCollection.insertOne( { x: 1 } );
{
  acknowledged: true,
  insertedId: ObjectId("6304deee5c8e10bbd2c099a9")
}
... example> show dbs
example  40.00 KiB
... example> db.exampleCollection.find()
[ { _id: ObjectId("6304deee5c8e10bbd2c099a9"), x: 1 } ]

Result: You now have a ready-to-use MongoDB cluster.