Create a Cluster
This How-To shows you how to create a MongoDB cluster using the IONOS API.
Before creating a cluster, you already need to have:
- a data center
- a private LAN in that data center
- at least one client server connected to the private LAN. In order to connect to your cluster, clients must be able to resolve public DNS entries.
You need to provide the UUID of the data center. The easiest way to retrieve the UUID is through the Cloud API:
curl --include \
--user "[email protected]:Mb2.r5oHf-0t" \
--header "Content-Type: application/json" \
"https://api.ionos.com/cloudapi/v6/datacenters?depth=1"
{
"id" : "datacenters",
"type" : "collection",
"href" : "https://api.ionos.com/cloudapi/v6/datacenters",
"items" : [ {
"id" : "b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
"type" : "datacenter",
"href" : "https://api.ionos.com/cloudapi/v6/datacenters/b1432c51-c20a-4f83-876f-c3a8a9e1fbec",
"metadata" : {
...
},
"properties" : {
"name" : "example-datacenter",
"description" : "",
"location" : "de/txl",
...
},
"entities" : {
...
}
}, {
"id" : "ad6eb12c-f297-4b91-bf65-7e1af7aebd8d",
"type" : "datacenter",
...
} ]
}
In the following examples, we assume that you want to use the data center UUID
b1432c51-c20a-4f83-876f-c3a8a9e1fbec.Currently, there is no automatic IP address management for database cluster. For creating the MongoDB cluster, you need to specify as many free IP addresses as the number of instances in your cluster. Currently the only supported subnet is /24.
You need to make sure that the IP addresses are not used by other servers in your LAN:
- If you rely on IONOS-provided DHCP, you must pick IP addresses of the subnet that is assigned to you by IONOS. To find the subnet, you can look at the network interface (NIC) configuration. To prevent a collision with the DHCP IP range, pick an IP between
x.x.x.3/24andx.x.x.10/24. IP addresses in that range are never assigned by the IONOS DHCP. - 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 yourself that it is not used anywhere else.
So 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 for example provide us the IP addresses 10.1.1.3/24, 10.1.1.4/24 and 10.1.1.5/24. Please 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.Caution: You cannot delete a LAN while a database cluster is still attached. If you want to delete the LAN, please delete the database cluster first.
To list the available sizing templates using the API:
curl --include \
--user "[email protected]:Mb2.r5oHf-0t" \
--header "Content-Type: application/json" \
https://api.ionos.com/databases/mongodb/templates
{
"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, please refer to our documentation on sizing.
Currently, we don't support to change instance size 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.This request will create a database cluster with three instances of MongoDB version 5.0.
Note: Only contract admins and owners can create and change database clusters. In contrast, the running database cluster can be accessed from all servers in the specified LAN.
curl --include \
--request POST \
--user "[email protected]:Mb2.r5oHf-0t" \
--header "Content-Type: application/json" \
--data-binary '{
"metadata": {},
"properties":
{
"mongoDBVersion": "5.0",
"instances": 3,
"templateID": "15c6dd2f-02d2-4987-b439-9a58dd59ecc3",
"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"]
}
]
}
}' \
https://api.ionos.com/databases/mongodb/clusters
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": "[email protected]",
"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",
"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": "15:39:01",
"dayOfTheWeek": "Friday"
},
"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. See the next section on how to determine when your cluster is ready.
You may have noticed that the
state is BUSY and that the database cluster is not yet reachable. 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.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" \
https://api.ionos.com/databases/mongodb/clusters/498ae72f-411f-11eb-9d07-046c59cc737e
If you don't 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 "[email protected]:Mb2.r5oHf-0t" \
--header "Content-Type: application/json" \
https://api.ionos.com/databases/mongodb/clusters
{
"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": {}
}
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:
$ 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: 5.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>
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 can't 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 User Management.
Let's assume you've created a user
jdoeionos on database example with the role readWrite on example. Then you can authenticate like this:... test> use example
switched to db example
... example> db.auth("jdoeionos", passwordPrompt())
{ ok: 1 }
and can afterwards 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 } ]
Congratulations: you now have a ready to use MongoDB cluster!
Last modified 5mo ago