IBM Cloud Docs
Provisioning

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:

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.

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 Version policy.
  • Database Edition: Set only at deployment Select either "Standard" or "Enterprise".
    Note that the Enterprise plan is not possible for 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: Configure the Service Endpoints on your deployment.

A 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

Before provisioning, follow the instructions provided in the documentation to install the IBM Cloud CLI tool.

  1. 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 ke(ibmcloud --apikey key or @key_file) to authenticate. For more information about how to log through the CLI, see General CLI commands.

    ibmcloud login
    
  2. Select the hosting model you want your database to be provisioned on. You can change this later. Provision a Databases for MongoDB Shared Compute instance with a command like:

    ibmcloud resource service-instance-create <INSTANCE_NAME> <SERVICE_NAME> <SERVICE_PLAN_NAME> <LOCATION> <SERVICE_ENDPOINTS_TYPE> <RESOURCE_GROUP> -p `{"members_host_flavor": "multitenant"}`
    

    Provision a Databases for MongoDB Isolated Compute instance with the same "members_host_flavor" -p parameter, which is instead set to the Isolated size. Available hosting sizes are listed in Table 2, as the host_flavor value parameter. For example: {"members_host_flavor": "b3c.4x16.encrypted"}

    ibmcloud resource service-instance-create <INSTANCE_NAME> <SERVICE_NAME> <SERVICE_PLAN_NAME> <LOCATION> <SERVICE_ENDPOINTS_TYPE> <RESOURCE_GROUP> -p `{"members_host_flavor": "<host_flavor value>"}`
    

    The fields in the provision command are described in the table that follows.

    Table 1. Basic command format fields
    Field Description Flag
    NAME Required The 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 Required Name or ID of the service. For Databases for MongoDB, use databases-for-mongodb.
    SERVICE_PLAN_NAME Required Standard plan (standard) or Enterprise plan (enterprise).
    LOCATION Required The location where you want to deploy. To retrieve a list of regions, use the ibmcloud regions command.
    SERVICE_ENDPOINTS_TYPE Configure the Service Endpoints of your deployment, either public or private. The default value is public. A MongoDB deployment cannot have both public and private endpoints simultaneously. This parameter cannot be changed after provisioning.
    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
    host_flavor For Shared Compute, specify multitenant. To provision an Isolated Compute instance, use {"members_host_flavor": "<host_flavor value>"}. The host_flavor value parameter defines your Isolated Compute sizing. For more information, see Hosting models.

The host_flavor parameter defines your Compute sizing. Input the appropriate value for your desired size. To provision a Shared Compute instance, specify multitenant. All other options place you on different Isolated Compute sizes.

Table 2. Host flavor sizing parameter
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.

  1. 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-east: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:     public
    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 4.4 (100%)
    
  2. (Optional) Deleting a service instance Delete an instance by running a command like this one:

    ibmcloud resource service-instance-delete <INSTANCE_NAME>
    

The --parameters parameter

The service-instance-create command supports a -p parameter, 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 9 GB of memory across three members, then the command to provision 3 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": "3072"
}'

Provisioning through the Resource Controller API

Follow these steps to provision using the Resource Controller API.

  1. Obtain an IAM token from your API token.

  2. You need to know the ID of the resource group that you would like to deploy to. This information is available through the IBM Cloud CLI.

    Use a command like:

    ibmcloud resource groups
    
  3. 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 the Cloud Databases CLI plug-in.

    The command looks like:

    ibmcloud cdb regions --json
    

    You should also determine which hosting model you want your database to be provisioned on. You can change this later. The host_flavor parameter defines your sizing; to provision a Shared Compute instance and select flexible resources according to Shared Compute guidelines, specify multitenant. All other options place you on different Isolated Compute sizes.

Table 1. Host Flavor sizing parameter
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

After you have all the information, provision a new resource instance with the IBM Cloud Resource Controller. The following example creates a Mongodb database on Isolated Compute, with a size of 4 CPU by 16 RAM.

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance",
    "target": "blue-us-south",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "databases-for-mongodb-standard"
    "parameters": {"members_host_flavor": "b3c.4x16.encrypted"}
  }'

The parameters name, target, resource_group, and resource_plan_id are all required.

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

  • 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 format crn: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 format crn: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 format crn: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 "6144", and there are three database members, then the deployment gets 6 GB of RAM total, giving 2 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 dedicated cores to your deployment. For example, to use two dedicated cores per member, use "members_cpu_allocation_count":"2". If omitted, the default value "Shared CPU" uses compute resources on shared hosts. This parameter only applies to `multitenant'.

  • service-endpoints - The Service Endpoints supported on your deployment, public or private. A MongoDB deployment cannot have both public and private endpoints simultaneously. This parameter cannot be changed after provisioning.

    In the CLI, service-endpoints is a flag, not a parameter.

Provisioning with Terraform

Use Terraform to manage your infrastructure through the ibm_database Resource for Terraform supports provisioning Cloud Databases deployments.

Before executing a Terraform script on an existing instance, use the terraform plan command to compare the current infrastructure state with the desired state defined in your Terraform files. Any alteration to the resource_group_id, service plan, version, key_protect_instance, key_protect_key, backup_encryption_key_crn attributes recreates your instance. For a list of current argument references with the Forces new resource specification, see the ibm_database Terraform Registry.

Select which hosting model you would like to place your database on. You can change this later. Note that the host_flavor parameter defines your hosting model. To provision a Shared Compute instance, specify multitenant. All other options place you on different Isolated Compute sizes.

Table 1. Host Flavor sizing parameter
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

To provision an instance through the Isolated Compute hosting model:

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
  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 Etcd database connection string" {
  value = "http://${ibm_database.test_acc.ibm_database_connection.icd_conn}"
}

To provision an instance through the Shared Compute hosting model:

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
  tags              = ["tag1", "tag2"]
  adminpassword                = "password12"
  group {
    group_id = "member"
    host_flavor {
      id = "multitenant"
    },
    cpu {
      allocation_count = 3
    }
    memory {
      allocation_mb = 2048
    }
    disk {
      allocation_mb = 256000
    }
  }
  users {
    name     = "user123"
    password = "password12"
  }
  allowlist {
    address     = "172.168.1.1/32"
    description = "desc"
  }
}
output "ICD Etcd database connection string" {
  value = "http://${ibm_database.test_acc.ibm_database_connection.icd_conn}"
}

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.