Create a MongoDB Cluster

IONOS Cloud 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.

Sizing considerations

To list the available sizing templates using the API:

Endpoint

Use the following endpoint to list templates: https://api.ionos.com/databases/mongodb/templates

Request

curl --include \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \

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.

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 Cloud if you rely on IONOS Cloud-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 Cloud 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.

Create a cluster

This request creates a database cluster with three instances of MongoDB version 7.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.

Endpoint

Use the following endpoint to create a MongoDB Business cluster: https://api.ionos.com/databases/mongodb/clusters

Note: The sample data center UUID is b1432c51-c20a-4f83-876f-c3a8a9e1fbec.

Request

curl --include \
    --request POST \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
      "metadata": {},
      "properties": {
        "type": "replicaset",
        "edition": "business",
        "mongoDBVersion": "7.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"
       }
      }
    }' \

Response

{
  "type": "cluster",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "metadata": {
    "state": "BUSY",
    "health": "UNKNOWN",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "[email protected]",
    "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 Query database status.

Create a 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.

Endpoint

Use the following endpoint to create a MongoDB Enterprise cluster: https://api.ionos.com/databases/mongodb/clusters

Note: The sample data center UUID is b1432c51-c20a-4f83-876f-c3a8a9e1fbec.

Request

curl --include \
    --request POST \
    --user "[email protected]: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"
       }
      }
    }' \

Response

{
  "type": "cluster",
  "id": "498ae72f-411f-11eb-9d07-046c59cc737e",
  "metadata": {
    "state": "BUSY",
    "health": "UNKNOWN",
    "createdDate": "2020-12-10T12:37:50.000Z",
    "createdBy": "[email protected]",
    "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 Query database status.

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

Endpoint

Use the following endpoint to query a database cluster: https://api.ionos.com/databases/mongodb/clusters/{clusterId}

Note: The sample cluster UUID is 498ae72f-411f-11eb-9d07-046c59cc737e.

Request

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

curl --include \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \

If you do not know your MongoDB cluster-ID, you can also list all clusters and find the one you want to query the status of.

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

curl --include \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \

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": "[email protected]",
        "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 a 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 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 5b8acdcc-22c6-11ed-bc22-c65c3b0754bf [primary] test>

Authentication

Connecting to a MongoDB cluster does not 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 Cloud MongoDB clusters happens completely via the IONOS Cloud API. For more information, see Users Management.

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

... example> db.auth("jdoeionos", "yourPassword")

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.

PreviousMongoDB v1 API NextCreate a Sharded Database Cluster

Last updated 8 hours ago

Was this helpful?

Good afternoon

hashtagPrerequisites

hashtagSizing considerations

hashtagEndpoint

hashtagRequest

hashtagResponse

hashtagSizing considerations

hashtagPreparing the network

hashtagCreate a cluster

hashtagEndpoint

hashtagRequest

hashtagResponse

hashtagCreate a cluster

hashtagEndpoint

hashtagRequest

hashtagResponse

hashtagQuery database status

hashtagEndpoint

hashtagRequest

hashtagResponse

hashtagConnect to a cluster

hashtagAuthentication

Prerequisites

Sizing considerations

Endpoint

Request

Response

Sizing considerations

Preparing the network

Create a cluster

Endpoint

Request

Response

Create a cluster

Endpoint

Request

Response

Query database status

Endpoint

Request

Response

Connect to a cluster

Authentication