Provisioning
Provision a IBM Cloud® Databases for MongoDB deployment through the catalog, the Cloud Databases CLI plug-in, the Cloud Databases API, or through Terraform.
Provisioning through the IBM Cloud console
Provision from the console by specifying the following parameters.
Platform
The platform that your database will be deployed on. Choose your required network and compute environment.
- IBM Cloud® - Deploy a database on the IBM Cloud platform, in a region of your choice.
Service details
- Service name: The name can be any string and is the name that is used on the web and in the CLI to identify the new deployment.
- Resource group: If you are organizing your services into resource groups, specify the resource group in this field. Otherwise, you can leave it at default. For more information, see Managing resource groups.
- Location: The deployment's public cloud region or Satellite location.
Hosting model
- Isolated: Secure single-tenant offering for complex, highly-performant enterprise workloads.
- Shared: Flexible multi-tenant offering for dynamic, fine-tuned, and decoupled capacity selections.
Databases for MongoDB Enterprise features are only available on Isolated Compute.
For more information, see Hosting models and Databases for MongoDB plans.
Resource allocation
Fine tune your resource allocation. The available options differ based on your selected hosting model.
- Isolated: Use the table to choose the machine size for each member of your deployment, and specify the disk size.
- Shared: By default, the smallest possible resource allocation is selected. This is ideal for small applications or testing. For larger allocations, select the Custom tile, which allows flexible resource configuration with 2+ cores.
The Shared Compute hosting model supports more fine-grained resource allocations that are not shown in the UI to maintain clarity. For more information, see Hosting models.
Specify the disk size depending on your requirements. It can be increased after provisioning but cannot be decreased to prevent data loss.
Service configuration
- Database version: Set only at deployment This is the deployment version of your database. We recommend running the preferred version to ensure optimal performance. For more information, see Versioning policy.
- Database edition: Set only at deployment Select either Standard or Enterprise. Note that the Enterprise plan is not available with Shared hosting. For more information, see Plans.
- Encryption: Set only at deployment If you use Key Protect, an instance and key can be selected to encrypt the deployment's disk. If you do not use your own key, the deployment automatically creates and manages its own disk encryption key.
- Endpoints: Set only at deployment Configure the Service endpoints on your deployment. The default setting is private.
A Databases for MongoDB deployment cannot have both public and private endpoints simultaneously.
After you select the appropriate settings, click Create to start the provisioning process.
Provisioning through the CLI
Create a service instance through the CLI
Before provisioning, follow the instructions provided in the documentation to install the IBM Cloud CLI tool.
-
Log in to IBM Cloud. If you use a federated user ID, it's important that you switch to a one-time passcode (
ibmcloud login --sso
), or use an API key (ibmcloud --apikey key or @key_file
) to authenticate. For more information about how to log in by using the CLI, see General CLI (ibmcloud) commands underibmcloud login
.ibmcloud login
-
Select the hosting model you want your database to be provisioned on. You can change this later.
-
Provision your database with the following command:
ibmcloud resource service-instance-create <INSTANCE_NAME> <SERVICE_NAME> <SERVICE_PLAN_NAME> <LOCATION> <RESOURCE_GROUP> -p '{"members_host_flavor": "<members_host_flavor value>"}' --service-endpoints="<Endpoint>"
For example, to provision a Databases for MongoDB Shared Compute hosting model instance, use a command like:
ibmcloud resource service-instance-create test-database databases-for-mongodb standard us-south -p '{"members_host_flavor": "multitenant", "members_memory_allocation_mb": "12288"}' --service-endpoints="private"
Provision a Databases for MongoDB Isolated instance with the same
"members_host_flavor"
-p parameter, setting it to the desired Isolated size. Available hosting sizes and theirmembers_host_flavor value
parameters are listed in Table 2. For example,{"members_host_flavor": "b3c.4x16.encrypted"}
. Note that since the host flavor selection includes CPU and RAM sizes (b3c.4x16.encrypted
is 4 CPU and 16 RAM), this request does not accept both an Isolated size selection, and separate CPU and RAM allocation selections.ibmcloud resource service-instance-create test-database databases-for-mongodb enterprise us-south -p '{"members_host_flavor": "b3c.4x16.encrypted"}' --service-endpoints="private"
The fields in the command are described in the table that follows.
Basic command format fields Field Description Flag INSTANCE_NAME
RequiredThe instance name can be any string and is the name that is used on the web and in the CLI to identify the new deployment. SERVICE_NAME
RequiredName or ID of the service. For Databases for MongoDB, use databases-for-mongodb
.SERVICE_PLAN_NAME
Requiredenterprise
orplatinum
LOCATION
RequiredThe location where you want to deploy. To retrieve a list of regions, use the ibmcloud regions
command.RESOURCE_GROUP
The Resource group name. The default value is default
.-g --parameters
JSON file or JSON string of parameters to create service instance -p members_host_flavor
To provision an Isolated or Shared Compute instance, use {"members_host_flavor": "<members_host_flavor value>"}
. For Shared Compute, specifymultitenant
. For Isolated Compute, select desired CPU and RAM configuration. For more information, see the following table or Hosting models.--service-endpoints
RequiredConfigure the Service endpoints of your deployment, either public
orprivate
.In the CLI,
service-endpoints
is a flag, not a parameter.
The members host flavor
parameter
The members_host_flavor
parameter defines your Compute sizing.
-
To provision a Shared Compute instance, specify
multitenant
. To provision an Isolated Compute instance, input the appropriate value for your desired CPU and RAM configuration.Members host flavor sizing parameter Members host flavor members_host_flavor value Shared Compute multitenant
4 CPU x 16 RAM b3c.4x16.encrypted
8 CPU x 32 RAM b3c.8x32.encrypted
8 CPU x 64 RAM m3c.8x64.encrypted
16 CPU x 64 RAM b3c.16x64.encrypted
32 CPU x 128 RAM b3c.32x128.encrypted
30 CPU x 240 RAM m3c.30x240.encrypted
You will see a response like:
Creating service instance INSTANCE_NAME in resource group default of account USER... OK Service instance INSTANCE_NAME was created. Name: INSTANCE_NAME ID: crn:v1:bluemix:public:databases-for-mongodb:us-south:a/ 40ddc34a846383BGB5b60e:dd13152c-fe15-4bb6-af94-fde0af5303f4:: GUID: dd13152c-fe15-4bb6-af94-fde0af56897 Location: LOCATION State: provisioning Type: service_instance Sub Type: Public Service Endpoints: private Allow Cleanup: false Locked: false Created at: 2023-06-26T19:42:07Z Updated at: 2023-06-26T19:42:07Z Last Operation: Status create in progress Message Started create instance operation
-
To check provisioning status, use the following command:
ibmcloud resource service-instance <INSTANCE_NAME>
When complete, you will see a response like:
Retrieving service instance INSTANCE_NAME in resource group default under account USER's Account as USER... OK Name: INSTANCE_NAME ID: crn:v1:bluemix:public:databases-for-mongodb:us-south:a/40ddc34a953a8c02f109835656860e:dd13152c-fe15-4bb6-af94-fde0af5303f4:: GUID: dd13152c-fe15-4bb6-af94-fde5654765 Location: <LOCATION> Service Name: databases-for-mongodb Service Plan Name: standard Resource Group Name: default State: active Type: service_instance Sub Type: Public Locked: false Service Endpoints: private Created at: 2023-06-26T19:42:07Z Created by: USER Updated at: 2023-06-26T19:53:25Z Last Operation: Status create succeeded Message Provisioning mongodb with version 7.17 (100%)
-
Optional: To delete a service instance, run the following command:
ibmcloud resource service-instance-delete <INSTANCE_NAME_OR_CRN>
CPU and RAM autoscaling is not supported on Cloud Databases Isolated Compute. Disk autoscaling is available. If you have provisioned an Isolated instance or switched over from a deployment with autoscaling, keep an eye on your resources using IBM Cloud® Monitoring integration, which provides metrics for memory, disk space, and disk I/O utilization. To add resources to your instance, manually scale your deployment.
The --parameters
parameter
The service-instance-create
command supports a -p
flag, which allows JSON-formatted parameters to be passed to the provisioning process. For example, you can pass Cloud Resource Names (CRNs) as parameter values, which
uniquely identify a resource in the cloud. All parameter names and values are passed as strings.
For example, if a database is being provisioned from a particular backup and the new database deployment needs a total of 12 GB of memory across three members, then the command to provision 4 GBs per member looks like:
ibmcloud resource service-instance-create databases-for-mongodb <SERVICE_NAME> standard us-south \
-p \ '{
"backup_id": "crn:v1:blue:public:databases-for-mongodb:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
"members_memory_allocation_mb": "4096"
}' --service-endpoints="private"
Provisioning through the Resource Controller API
Follow these steps to provision by using the Resource Controller API.
-
Obtain an IAM token.
-
You need to know the ID of the resource group that you would like to deploy to. Use this command to obtain a list of resource groups in your account:
curl -X GET "https://resource-controller.cloud.ibm.com/v2/resource_groups?account_id=<YOUR_ACCOUNT>" -H "Authorization: Bearer <TOKEN>"
-
You need to know the region you want to deploy to. To list all of the regions that deployments can be provisioned into from the current region, use this API command:
curl -X GET https://api.<YOUR-REGION>.databases.cloud.ibm.com/v5/ibm/regions -H 'Authorization: Bearer <TOKEN>' \
-
Select the hosting model you want your database to be provisioned on. You can change this later.
A host flavor represents fixed sizes of guaranteed resource allocations. To see which host flavors are available in your region, call the host flavors capability endpoint like this:
curl -X POST https://api.{region}.databases.cloud.ibm.com/v5/ibm/capability/flavors \ -H 'Authorization: Bearer <>' \ -H 'ContentType: application/json' \ -d '{ "deployment": { "type": "mongodb", "location": "us-south" } }'
This returns:
{ "deployment": { "type": "mongodb", "location": "us-south", "platform": "classic" }, "capability": { "flavors": [ { "id": "b3c.4x16.encrypted", "name": "4x16", "cpu": { "allocation_count": 4 }, "memory": { "allocation_mb": 16384 }, "hosting_size": "xs" }, { "id": "b3c.8x32.encrypted", "name": "8x32", "cpu": { "allocation_count": 8 }, "memory": { "allocation_mb": 32768 }, "hosting_size": "s" }, { "id": "m3c.8x64.encrypted", "name": "8x64", "cpu": { "allocation_count": 8 }, "memory": { "allocation_mb": 65536 }, "hosting_size": "s+" }, { "id": "b3c.16x64.encrypted", "name": "16x64", "cpu": { "allocation_count": 16 }, "memory": { "allocation_mb": 65536 }, "hosting_size": "m" }, { "id": "b3c.32x128.encrypted", "name": "32x128", "cpu": { "allocation_count": 32 }, "memory": { "allocation_mb": 131072 }, "hosting_size": "l" }, { "id": "m3c.30x240.encrypted", "name": "30x240", "cpu": { "allocation_count": 30 }, "memory": { "allocation_mb": 245760 }, "hosting_size": "xl" }, { "id": "multitenant", "name": "multitenant", "cpu": { "allocation_count": 0 }, "memory": { "allocation_mb": 0 }, "hosting_size": "" } ] } }
As shown, the Isolated Compute host flavors available to a Databases for MongoDB instance in the
us-south
region are:b3c.4x16.encrypted
b3c.8x32.encrypted
m3c.8x64.encrypted
b3c.16x64.encrypted
b3c.32x128.encrypted
m3c.30x240.encrypted
See below for more information about the
members_host_flavor
parameter. -
Once you have all the above information, provision a new resource instance with the IBM Cloud Resource Controller.
curl -X POST \ https://resource-controller.cloud.ibm.com/v2/resource_instances \ -H "Authorization: Bearer <TOKEN>" \ -H 'Content-Type: application/json' \ -d '{ "name": "<INSTANCE_NAME>", "target": "<targeted-region>", "resource_group": "RESOURCE_GROUP_ID", "resource_plan_id": "<SERVICE_PLAN_NAME>" "parameters": { "members_host_flavor": "<members_host_flavor_value>" "service_endpoints":"<ENDPOINT>" } }'
Example
To make a Shared Compute instance, follow this example:
curl -X POST \ https://resource-controller.cloud.ibm.com/v2/resource_instances \ -H "Authorization: Bearer <TOKEN>" \ -H 'Content-Type: application/json' \ -d '{ \ "name": "my-instance", \ "target": "us-south", \ "resource_group": "<RESOURCE_GROUP_ID>", \ "resource_plan_id": "databases-for-mongodb-standard", \ "parameters": { "members_host_flavor": "multitenant", "service_endpoints":"private", "memory": { "allocation_mb": 12288 }, "cpu": { "allocation_count": 4 } } \ }' \
Provision a Databases for Elasticsearch Isolated instance with the same
"members_host_flavor"
parameter, setting it to the desired Isolated size. Available hosting sizes and theirmembers_host_flavor value
parameters are listed in Table 2. For example,{"members_host_flavor": "b3c.4x16.encrypted"}
. Note that since the members host flavor selection includes CPU and RAM sizes (b3c.4x16.encrypted
is 4 CPU and 16 RAM), this request does not accept both, an Isolated size selection and separate CPU and RAM allocation selections.To deploy an instance with 16 GB of RAM and 4 CPU cores on Isolated Compute, see the following example. Make sure to replace the
RESOURCE GROUP ID
value with an ID found under Manage > Account > Resource groups.curl -X POST \ https://resource-controller.cloud.ibm.com/v2/resource_instances -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{ "name": "my-mongo", "target": "eu-gb", "resource_group": "0383da45d9a044r6d59d36f4689ae25d25", "resource_plan_id": "databases-for-mongodb-standard", "parameters": { "members_host_flavor":"b3c.4x16.encrypted"}, "service_endpoints":"private" }'
The fields in the command are described in the table that follows.
Field Description Flag name
RequiredThe instance name can be any string and is the name that is used on the web and in the CLI to identify the new deployment. resource_plan_id
RequiredName or ID of the service. For Databases for MongoDB, use databases-for-mongodb-enterprise
or `databases-for-mongodb-standard.target
RequiredThe location where you want to deploy. To retrieve a list of regions, use the ibmcloud regions
command.resource_group
RequiredThe Resource group name. The default value is default
.-g --parameters
JSON file or JSON string of parameters to create service instance. See below for more details -p members_host_flavor
To provision an Isolated or Shared Compute instance, use {"members_host_flavor": "<members_host_flavor value>"}
. For Shared Compute, specifymultitenant
. For Isolated Compute, select desired CPU and RAM configuration. For more information, see the table below, or Hosting models.service_endpoints
Required - The Service endpoints supported on your deployment,public
orprivate
.
The members_host_flavor
parameter
The members_host_flavor
parameter defines your Compute sizing. To provision a Shared Compute instance, specify multitenant
. To provision an Isolated Compute instance, input the appropriate value for your desired CPU
and RAM configuration.
Members host flavor | members_host_flavor value |
---|---|
Shared Compute | multitenant |
4 CPU x 16 RAM | b3c.4x16.encrypted |
8 CPU x 32 RAM | b3c.8x32.encrypted |
8 CPU x 64 RAM | m3c.8x64.encrypted |
16 CPU x 64 RAM | b3c.16x64.encrypted |
32 CPU x 128 RAM | b3c.32x128.encrypted |
30 CPU x 240 RAM | m3c.30x240.encrypted |
CPU and RAM autoscaling is not supported on Cloud Databases Isolated Compute. Disk autoscaling is available. If you have provisioned an Isolated instance or switched over from a deployment with autoscaling, keep an eye on your resources using IBM Cloud® Monitoring integration, which provides metrics for memory, disk space, and disk I/O utilization. To add resources to your instance, manually scale your deployment.
List of additional parameters
In the --parameters
object you can provide additional information to create your service instance, including:
-
backup_id
- A CRN of a backup resource to restore from. The backup must be created by a database deployment with the same service ID. The backup is loaded after provisioning and the new deployment starts up that uses that data. A backup CRN is in the formatcrn:v1:<...>:backup:<uuid>
. If omitted, the database is provisioned empty. -
version
- The version of the database to be provisioned. If omitted, the database is created with the most recent major and minor version. -
disk_encryption_key_crn
- The CRN of a KMS key (for example, Hyper Protect Crypto Services or Key Protect), which is then used for disk encryption. A KMS key CRN is in the formatcrn:v1:<...>:key:<id>
. -
backup_encryption_key_crn
- The CRN of a KMS key (for example, Hyper Protect Crypto Services or Key Protect), which is then used for backup encryption. A KMS key CRN is in the formatcrn:v1:<...>:key:<id>
.To use a key for your backups, you must first enable the service-to-service delegation.
-
members_memory_allocation_mb
- Total amount of memory to be shared between the database members within the database. For example, if the value is "12288", and there are three database members, then the deployment gets 12 GB of RAM total, giving 4 GB of RAM per member. If omitted, the default value is used for the database type is used. This parameter only applies to `multitenant'. -
members_disk_allocation_mb
- Total amount of disk to be shared between the database members within the database. For example, if the value is "30720", and there are three members, then the deployment gets 30 GB of disk total, giving 10 GB of disk per member. If omitted, the default value for the database type is used. This parameter only applies to `multitenant'. -
members_cpu_allocation_count
- Enables and allocates the number of specified cores to your deployment. For example, to use two dedicated cores per member, use"members_cpu_allocation_count":"2"
. If omitted, the default Shared Compute CPU:RAM ratios will be applied. This parameter only applies to `multitenant'.
Provisioning with Terraform
Before you begin:
- Install the Terraform CLI and the IBM Cloud Provider plug-in.
- Make sure you have an IBM Cloud API key.
Use Terraform to manage your infrastructure through the ibm_database
Resource for Terraform supports
provisioning Cloud Databases deployments.
Select the hosting model you want your database to be provisioned on. You can change this later.
Provisioning isolated compute with Terraform
Provision a Databases for MongoDB Isolated instance with the same "host_flavor"
parameter, setting it to the desired Isolated size. Available hosting sizes and their host_flavor value
parameters are listed
in Table 1. For example, {"host_flavor": "b3c.4x16.encrypted"}
. Note that since the host flavor selection includes CPU and RAM sizes (b3c.4x16.encrypted
is 4 CPU and 16 RAM), this request does not accept both, an Isolated size selection and separate CPU and RAM allocation selections.
data "ibm_resource_group" "group" {
name = "<your_group>"
}
resource "ibm_database" "<your_database>" {
name = "<your_database_name>"
plan = "standard"
location = "eu-gb"
service = "databases-for-mongodb"
resource_group_id = data.ibm_resource_group.group.id
service_endpoints = "private"
tags = ["tag1", "tag2"]
adminpassword = "password12"
group {
group_id = "member"
host_flavor {
id = "b3c.8x32.encrypted"
}
disk {
allocation_mb = 256000
}
}
users {
name = "user123"
password = "password12"
}
allowlist {
address = "172.168.1.1/32"
description = "desc"
}
}
output "ICD MongoDB database connection string" {
value = "http://${ibm_database.test_acc.ibm_database_connection.icd_conn}"
}
The host flavor
parameter
The host_flavor
parameter defines your Compute sizing.
- Shared compute - To provision a Shared Compute instance, specify
multitenant
. - Isolated compute - To provision an Isolated Compute instance, input the appropriate value for your desired CPU and RAM configuration. See the values in the following table.
Host flavor | host_flavor value |
---|---|
Shared compute | multitenant |
4 CPU x 16 RAM | b3c.4x16.encrypted |
8 CPU x 32 RAM | b3c.8x32.encrypted |
8 CPU x 64 RAM | m3c.8x64.encrypted |
16 CPU x 64 RAM | b3c.16x64.encrypted |
32 CPU x 128 RAM | b3c.32x128.encrypted |
30 CPU x 240 RAM | m3c.30x240.encrypted |
CPU and RAM autoscaling is not supported on Cloud Databases Isolated Compute. Disk autoscaling is available. If you have provisioned an Isolated instance or switched over from a deployment with autoscaling, keep an eye on your resources using IBM Cloud® Monitoring integration, which provides metrics for memory, disk space, and disk I/O utilization. To add resources to your instance, manually scale your deployment.