# Modify Cluster Attributes

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

| **Quick Links**:                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------- |
| [<mark style="color:blue;">**Renaming the database cluster**</mark>](#renaming-the-database-cluster)                                   |
| [<mark style="color:blue;">**Upgrading the MongoDB version**</mark>](#upgrading-the-mongodb-version)                                   |
| [<mark style="color:blue;">**Updating users and roles**</mark>](#updating-users-and-roles)                                             |
| [<mark style="color:blue;">**Setting maintenance windows**</mark>](#setting-maintenance-windows)                                       |
| [<mark style="color:blue;">**Scaling a cluster vertically (RAM, CPU, Storage)**</mark>](#scaling-a-cluster-vertically-ram-cpu-storage) |
| [<mark style="color:blue;">**Scaling a cluster horizontally (Replicas)**</mark>](#scaling-a-cluster-horizontally-replicas)             |

### Renaming the database cluster

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

{% hint style="info" %}
Note: The sample UUID is <mark style="color:red;">d02de413-d5af-4104-a6f9-3a3c2766ee61</mark>
{% endhint %}

```bash
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

```json
{
  "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.

{% hint style="info" %}
Changing the version of a running MongoDB cluster via the API is not allowed.
{% endhint %}

{% tabs %}
{% tab title="MongoDB Business" %}

#### 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 [<mark style="color:blue;">Cubes</mark>](https://api.ionos.com/docs/cloud/v6/#tag/Templates); each template exposes a combination of resource sizes that can be assigned to any of your clusters.

{% hint style="info" %}
Note: You can get a list of available [<mark style="color:blue;">MongoDB Templates via the API</mark>](https://api.ionos.com/docs/mongodb/v1/#tag/Templates).

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

{% endhint %}

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

```bash
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
```

```json
{
  "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 [<mark style="color:blue;">MongoDB Replication mechanism</mark>](https://www.mongodb.com/docs/manual/replication/). 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.

{% hint style="info" %}
Note: Be prepared for a possible downtime in case of a cluster with only one replica.
{% endhint %}

{% hint style="info" %}
**Note:** Decreasing storageSize to a size lower than your consumed storage is not allowed.
{% endhint %}
{% endtab %}

{% tab title="MongoDB Enterprise" %}

#### 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`.

```bash
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
```

```json
{
  "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"
  }
}
```

{% hint style="info" %}
**Note:** Decreasing storageSize to a size lower than your consumed storage is not allowed.
{% endhint %}
{% endtab %}
{% endtabs %}

### 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):

```bash
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
```

```json
{
  "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.

{% hint style="info" %}
**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.
{% endhint %}

For more information, see [<mark style="color:blue;">Replica Set Elections</mark>](https://www.mongodb.com/docs/manual/core/replica-set-elections/).

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

```bash
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
```

```json
{
  "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 [<mark style="color:blue;">Users Management</mark>](https://docs.ionos.com/cloud/~/revisions/1AlFSZBNMIBgs7fiOwFD/managed-services/database-as-a-service/mongodb/api-howtos/users-management).