Getting started with Databases for MongoDB

Gen 2

This tutorial guides you through the steps to quickly start using Databases for MongoDB on the Gen 2 platform by provisioning an instance, setting up a secure connection through a VSI and VPE, and enabling logging and monitoring.

Follow these steps to complete the tutorial:

Follow these steps to complete the tutorial:

Follow these steps to complete the tutorial:

Follow these steps to complete the tutorial:

Before you begin

Step 1: Choose your plan

Databases for MongoDB on Gen 2 platform currently offers only the Databases for MongoDB Standard plan, which is a fully managed NoSQL database service based on the MongoDB Community Edition.

Step 2: Provision through the console

  1. Log in to the IBM Cloud console.
  2. Click the Databases for MongoDB service in the catalog.
  3. In Service details, configure the following:
    • Location - Select a location that supports Gen 2.
    • 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.
  4. Resource allocation - Specify the initial RAM, disk, and cores for your databases. The minimum sizes of memory and disk are selected by default. With dedicated cores, your resource group is given a single-tenant host with a minimum reserve of CPU shares. Your deployments are then allocated the number of cores that you specify. Once provisioned, disk cannot be scaled down.
  5. In Service configuration, configure the following:
    • Database version Set only at deployment - The deployment version of your database. To ensure optimal performance, run the preferred version. The latest minor version is used automatically and currently the only option for Gen 2 databases.
    • Encryption - 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.
  6. Click Create. The Cloud Databases Resource list page opens.
  7. When your instance has been provisioned, click the instance name to view more information.

Step 2: Provision through the CLI

You can provision a Databases for MongoDB instance by using the CLI. If you don't already have it, you need to install the IBM Cloud CLI.

  1. Log in to IBM Cloud with the following command:

    ibmcloud login

    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 using the CLI, see General CLI (ibmcloud) commands under ibmcloud login.

  2. Create a Databases for MongoDB instance.

    To create an instance from the CLI, run the following command:

    ibmcloud resource service-instance-create <INSTANCE_NAME> <SERVICE_NAME> <SERVICE_PLAN_NAME> <LOCATION> -g <RESOURCE_GROUP>

    The fields in the command are described in the following table.

    Basic command format fields
    Field Description Flag
    INSTANCE_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-gen2.
    SERVICE_PLAN_NAME Required Standard plan (standard)
    LOCATION Required The 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

Step 2: Provision through the resource controller API

Using APIs

Use the Cloud Databases API to work with your Databases for MongoDB instance. The resource controller API is used to provision an instance.

You will need an API key to perform actions via the API. Follow these steps to create an IBM Cloud API key that enables you to use the API to provision infrastructure into your account. You can create up to 20 API keys.

For security reasons, the API key is only available to be copied or downloaded at the time of creation. If the API key is lost, you must create a new API key.

Follow these steps to provision a Databases for MongoDB instance using the Resource Controller API. Obtain an IAM token from your API token.

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

  2. Once you have all the 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 <>' \
   -H 'Content-Type: application/json' \
     -d '{
      "name":"my-instance",
      "target":"ca-mon",
      "resource_group":"5c49eabc-f5e8-5881-a37e-2d100a33b3df",
      "resource_plan_id":"databases-for-mongodb-gen2-standard",
      "dataservices":{
         "mongodb":{
            "storage_gb":10,
            "host_flavor":"b3c.8x32.encrypted"
         },
         "encryption":{
            "disk":"crn:v1..."
         },
         "version":"8.0"
      }
   }'

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

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

  • storage_gb - Total amount of disk in Gigabytes to be shared between the database members within the database. For example, if the value is 30, 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.

Step 2: Provision through Terraform

Use Terraform to manage your infrastructure through the ibm_database Resource for Terraform.

Step 3: Create the Manager user and generate credentials

The Manager user

As part of provisioning a new instance in IBM Cloud®, you can use the service credential console page to create a user with different roles (Manager and Writer).

Databases for MongoDB instances no longer include a default admin user. Instead, you create a user with the Manager or Writer role using the IBM Cloud® service credential interface — via UI or CLI. These users come with necessary credentials to connect to and manage the instance.

The Manager user functions as an admin-like user and is automatically granted the below priviliges:

   "dbAdminAnyDatabase",
	"readWriteAnyDatabase",
	"readAnyDatabase",
	"clusterMonitor",
	"clusterManager",
	"backup",
	"restore"

Change the user password in the UI

Changing the user password is not supported via the IBM Cloud console on Gen 2.

Create the manager user in the CLI

Use one of the following commands from the IBM Cloud CLI Cloud Databases plug-in to create the Manager user.

ibmcloud resource service-key-create <service_key_name> Manager --instance-name <instance_name>

ibmcloud resource service-key-create <service_key_name> Manager --instance-id <guid>

Delete the user in the CLI

Use the following command from the IBM Cloud CLI Cloud Databases plug-in to delete the created user.

ibmcloud resource service-key-delete <service_key_name>

Change the manager password in the CLI

Changing a user password is not supported via the CLI on Gen 2.

Step 4: Set up context-based restrictions

Context-based restrictions give account owners and administrators the ability to define and enforce access restrictions for IBM Cloud resources based on the context of access requests. Access to Cloud Databases resources can be controlled with context-based restrictions and Identity and Access Management (IAM) policies.

Step 5: Create a connection

The Connect tab in Gen 2 provides guided instructions for creating a secure connection to your Databases for MongoDB deployment.

Because Gen 2 supports private endpoints only, all connections are established through the IBM Cloud® private network. The Create a connection view walks you through the required setup to connect securely from your infrastructure, such as a Virtual Server Instance (VSI), by using Virtual Private Endpoint (VPE) gateway.

This guided experience is designed to help you configure a production-ready, secure connection without exposing your database to the public internet.

Step 6: Connect IBM Cloud Monitoring

You can use IBM Cloud® Monitoring to get operational visibility into the performance and health of your applications, services, and platforms. IBM Cloud Monitoring provides administrators, DevOps teams, and developers full stack telemetry with advanced features to monitor and troubleshoot, define alerts, and design custom dashboards.

For more information about how to use Monitoring with Databases for MongoDB, see Monitoring integration.

You cannot connect IBM Cloud Monitoring by using the CLI. Use the console to complete this task.

Step 7: Connect IBM Cloud Logs Activity Tracker

IBM Cloud® Activity Tracker Event Routing allows you to view, and audit service activity to comply with corporate policies and industry regulations. Activity Tracker Event Routing records user-initiated activities that change the state of a service in IBM Cloud. Use Activity Tracker Event Routing to track how users and applications interact with the Databases for MongoDB service.

To get up and running with Activity Tracker Event Routing, see [Getting Started with Activity Tracker Event Routing]/docs/atracker?topic=atracker-getting-started){: external}.

Activity Tracker Event Routing can have only one instance per location. To view events, you must access the web UI of the Activity Tracker Event Routing service in the same location where your service instance is available. For more information, see Launch the web UI. Events are formatted according to the Cloud Auditing Data Federation (CADF) standard. For further details of the information they include, see CADF standard.

You cannot connect Activity Tracker Event Routing by using the CLI. Use the console to complete this task.

Next steps