1 of 10

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

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

Response

{
  "id": "templates",
  "type": "collection",
  "items": [
    {
      "id": "15c6dd2f-02d2-4987-b439-9a58dd59ecc3",
      "cores": 1,
      "ram": 1024,
      "storageSize": 30
    },
    {
      "id": "56ce4e71-b03a-42b2-85be-9a4520aa40be",
      ...
    },
    ...
  ],
  "offset": 0,
  "limit": 8,
  "_links": {}
}

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

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 Sizing.

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 storage type that is suitable for your workload.

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

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 Querying database status.

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

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.

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.

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 Users Management.

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.

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 readAnyDatabase.

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

Currently, you can only assign built-in roles. 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.

curl --include \
    --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties": {
        "username": "benjamin",
        "password": "password",
        "roles": [
          {
            "role": "readWrite",
            "database": "mydb"
          }
        ]
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users

{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "readWrite",
        "database": "mydb"
      }
    ]
  }
}

Deleting user

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

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

Getting all users

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

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/users

{
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "type": "collection",
  "items": [
    {
      "type": "user",
      "metadata": {
        "createdDate": "2020-12-10T12:37:50.000Z",
        "createdBy": "clientname@ionos.com",
        "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
      },
      "properties": {
        "username": "benjamin",
        "roles": [
          {
            "role": "readWrite",
            "database": "mydb"
          }
        ]
      }
    }
  ]
}

Getting a single user

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

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/users/benjamin

{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "readWrite",
        "database": "mydb"
      }
    ]
  }
}

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:

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

{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "readWrite",
        "database": "mydb"
      }
    ]
  }
}

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.

curl --include \
    --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "properties": {
        "roles": [
          {"database": "mydb", "role": "read"}
        ]
      }
    }' \
    https://api.ionos.com/databases/mongodb/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/benjamin

{
  "type": "user",
  "metadata": {
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "clientname@ionos.com",
    "createdByUserId": "012342f-411f-1eeb-9d07-046c59cc737e"
  },
  "properties": {
    "username": "benjamin",
    "roles": [
      {
        "role": "read",
        "database": "mydb"
      }
    ]
  }
}

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

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

Response

{
  "id": "templates",
  "type": "collection",
  "items": [
    {
      "id": "15c6dd2f-02d2-4987-b439-9a58dd59ecc3",
      "cores": 1,
      "ram": 1024,
      "storageSize": 30
    },
    {
      "id": "56ce4e71-b03a-42b2-85be-9a4520aa40be",
      ...
    },
    ...
  ],
  "offset": 0,
  "limit": 8,
  "_links": {}
}

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

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 Sizing.

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 storage type 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 Querying database status.

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.

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

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.

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)

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"
  }
}

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)

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)

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"
  }
}

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.

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"
  }
}

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.

API How-Tos

DBaaS API - OpenAPI Specification

Request parameter headers

Examples

Create a Cluster

Prerequisites

Sizing considerations

Sizing considerations

Preparing the network

Creating the cluster

Creating the cluster

Querying database status

Request

Response

Connect to cluster

Authentication

Create a Sharded Database Cluster

Create the cluster

Resource consumption

Request

Response

Modify Cluster Attributes

Renaming the database cluster

Response

Upgrading the MongoDB version

Scaling a cluster vertically (RAM, CPU, Storage)

Scaling a cluster vertically (RAM, CPU, Storage)

Scaling a cluster horizontally (Replicas)

Increasing number of shards

Setting maintenance windows

Updating users and roles

Enable the BI Connector

Modify the cluster

Request

Response

Users Management

Roles

Adding a user

Deleting user

Getting all users

Getting a single user

Modifying a single user

Changing the password

Changing the roles

Access Logs

Requesting logs

Response

Database Migration

High level plan

Preparations

A place to run mongodump and mongorestore

Check MongoDB version

Access to old cluster

User in new cluster

Dump data from old cluster

Restore data in new cluster

Restore a Database

List available snapshots of a cluster

Request

Response

Restore from backup in-place

Point in time recovery

Connect from Kubernetes

Prerequisites

Enable the BI Connector

Modify the cluster

Request

Response

Create a Cluster

Prerequisites

Sizing considerations

Sizing considerations

Preparing the network

Creating the cluster

Creating the cluster

Querying database status

Request

Response

Connect to cluster

Authentication

A place to run `mongodump` and `mongorestore`

A place to run `mongodump` and `mongorestore`