> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/api-howtos/create-a-cluster.md).
# Create a Cluster
IONOS MongoDB API allows you to create a MongoDB cluster.
{% hint style="info" %}
#### 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.
{% endhint %}
In the following examples, we assume that you want to use the data center UUID `b1432c51-c20a-4f83-876f-c3a8a9e1fbec`.
{% tabs %}
{% tab title="MongoDB Business" %}
#### Sizing considerations
To list the available sizing templates using the API:
**Request**
```bash
curl --include \
--user "clientname@ionos.com:Mb2.r5oHf-0t" \
--header "Content-Type: application/json" \
https://api.ionos.com/databases/mongodb/templates
```
**Response**
```json
{
"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](/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/overview/sizing.md).
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`.
{% endtab %}
{% tab title="MongoDB Enterprise" %}
#### 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](/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/overview/sizing.md).
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](https://docs.ionos.com/support/general-information/price-list/ionos-cloud-se-de) that is suitable for your workload.
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="MongoDB Business" %}
#### 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.
{% hint style="warning" %}
**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.
{% endhint %}
#### Creating the cluster
This request creates a database cluster with three instances of MongoDB version 5.0.
{% hint style="info" %}
**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.
{% endhint %}
**Request**
```bash
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**
{% hint style="info" %}
**Note:** We will use 498ae72f-411f-11eb-9d07-046c59cc737e as example for the cluster ID in following examples.
{% endhint %}
```json
{
"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](#querying-database-status).
{% endtab %}
{% tab title="MongoDB Enterprise" %}
#### Creating the cluster
This request will create a database cluster with three instances of MongoDB version 6.0.
{% hint style="info" %}
**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`
{% endhint %}
{% hint style="info" %}
**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.
{% endhint %}
**Request**
```bash
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**
{% hint style="info" %}
**Note:** In the following examples, we use 498ae72f-411f-11eb-9d07-046c59cc737e as the cluster ID.
{% endhint %}
```json
{
"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).
{% endtab %}
{% endtabs %}
### 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.
```bash
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.
```bash
curl --include \
--user "clientname@ionos.com:Mb2.r5oHf-0t" \
--header "Content-Type: application/json" \
https://api.ionos.com/databases/mongodb/clusters
```
#### Response
```json
{
"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:
{% hint style="info" %}
**Reminder:** The connection must be performed from an extra VM.
{% endhint %}
```bash
$ 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](/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/api-howtos/users-management.md).
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 } ]
```
{% hint style="success" %}
**Result:** You now have a ready-to-use MongoDB cluster.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ionos.com/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/api-howtos/create-a-cluster.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.