KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Database-MongoDB

Add Existing MongoDB Processes to Cloud Manager — MongoDB Cloud Manager

Add Existing MongoDB Processes to Cloud Manager¶

On this page

Considerations
Prerequisites
Procedures

Cloud Manager provides a wizard for adding your existing MongoDB deployments to monitoring and management. The wizard prompts you to:

Install an Automation if it doesn’t already exist
Identify the sharded cluster , the replica set , or the standalone to add. You can choose to add the deployment to Monitoring or to both Monitoring and Automation .

If you are adding a deployment that you intend to live migrate to Atlas, you need to add the deployment (and its credentials) only for Monitoring .

Considerations¶

Unique Names¶

Deployments must have unique names within the projects.

Important

Replica set, sharded cluster, and shard names within the same project must be unique. Failure to have unique names for the deployments will result in broken backup snapshots.

MongoDB Configuration Options¶

Automation doesn’t support all MongoDB options. To review which options are supported, see MongoDB Settings that Automation Supports .

TLS ¶

If you enable TLS , the FQDN for the host serving a MongoDB process must match the SAN for the TLS certificate on that host.

Caution

To prevent man-in-the-middle attacks, keep the scope of TLS certificates as narrow as possible. Although you can use one TLS certificate with many SANs , or a wildcard TLS certificate on each host, you should not. To learn more, see RFC 2818, section 3.1 .

Preferred Hostnames¶

Set up a preferred hostname if you:

Require a specific hostname, FQDN , IPv4 address or IPv6 address to access the MongoDB process, or
Must specify the hostname to use for hosts with multiple aliases.

To learn more, see the Preferred Hostnames setting in Project Settings .

Managing Windows MongoDB Services¶

If you are adding an existing MongoDB process that runs as a Windows Service to Automation, Automation:

Stops and disables the existing service
Creates and starts a new service

Authentication Credentials on Source and Destination Clusters¶

If the Cloud Manager project has MongoDB authentication settings enabled for its deployments, the MongoDB deployment you import must support the project’s authentication mechanism.

We recommend that you import to a new destination project that has no running processes and doesn’t have authentication enabled.

If the source cluster uses authentication, and the destination Cloud Manager project doesn’t have any existing managed processes, Cloud Manager enables authentication in the destination project, imports the existing keyfile from the source cluster, and uses it to authenticate the user that conducts the import process.

If the source cluster and the destination Cloud Manager project both use authentication, and the project has processes, Cloud Manager attempts to use existing authentication settings in the destination project during the import process. For the import process to succeed, authentication credentials on the source cluster and the Cloud Manager destination project must be the same.

To ensure that import is successful, before you start the import process, add the Cloud Manager destination project’s credentials on the source cluster. To learn more, see Rotate Keys for Replica Set or Rotate Keys for Sharded Clusters.

Authentication Use Cases¶

If your MongoDB deployment requires authentication, when you add the deployment to Cloud Manager for monitoring, you must provide the necessary credentials .

If the deployment doesn’t use Automation, but did use Backup, Monitoring, or both, you can find those credentials where the credentials were before updating to the MongoDB Agent.
If the deployment doesn’t use Automation, but will use Backup, Monitoring, or both:
1. Create the credentials for the MongoDB Deployment. To learn more, see Required Access for MongoDB Agent for Monitoring and Required Access for MongoDB Agent for Backup .
2. Add the credentials that you granted to those functions to Cloud Manager after you add the MongoDB processes. To learn more, see Add Credentials for Monitoring and Add Credentials for Backup .
If the deployment uses Automation, Cloud Manager uses the credentials from the MongoDB Agent. You can delete the credentials from the legacy Backup, and Monitoring Agents. The MongoDB Agent uses those credentials for its Automation, Backup, and Monitoring functions.
If the deployment will use Automation but didn’t use it before you import it, add the mms-automation user to the database processes you imported and add the user’s credentials to Cloud Manager.

To learn more, see Add Credentials for Automation .

Automation and Updated Security Settings Upon Import¶

Adding a MongoDB deployment to automation may affect the security settings of the Cloud Manager project and the MongoDB deployment.

Automation enables the Project Security Setting . If the MongoDB deployment requires authentication but the Cloud Manager project doesn’t have authentication settings enabled, when you add the MongoDB deployment to automation, Cloud Manager updates the project’s security settings to the security settings of the newly imported deployment.

The import process only updates the Cloud Manager project’s security setting if the project’s security setting is currently disabled. The import process doesn’t disable the project’s security setting or change its enabled authentication mechanism.
Automation Imports MongoDB Users and Roles . The following statements apply to situations where a MongoDB deployment requires authentication or the Cloud Manager project has authentication settings enabled.

If the MongoDB deployment contains users or user-defined roles, you can choose to import these users and roles for Cloud Manager to manage. The imported users and roles are Synced to all managed deployments in the Cloud Manager project.
- If you set the project’s Enforce Consistent Set value to Yes , Cloud Manager deletes from the MongoDB deployments those users and roles that are not imported.
- If you set the project’s Enforce Consistent Set value to No , Cloud Manager stops managing non-imported users and roles in the project. These users and roles remain in the MongoDB deployment. To manage these users and roles, you must connect directly to the MongoDB deployment.
If you don’t want the Cloud Manager project to manage specific users and roles, use the Authentication & Users and Authentication & Roles pages to remove these users and roles during import before you confirm and deploy the changes. To learn more, see Manage or Unmanage MongoDB Users .

If the imported MongoDB deployment already has mms-backup-agent and mms-monitoring-agent users in its admin database, the import process overrides these users’ roles with the roles for mms-backup-agent and mms-monitoring-agent users as set in the Cloud Manager project.
Automation Applies to All Deployments in the Project . The project’s updated security settings, including all users and roles managed by the Cloud Manager project, apply to all deployments in the project, including the imported MongoDB deployment.

Cloud Manager restarts all deployments in the project with the new setting, including the imported MongoDB deployment. After import, all deployments in the project use the Cloud Manager automation keyfile upon restart.

The deployment that you import must use the same keyfile as the existing processes in the destination project or the import process may not proceed. To learn more, see Authentication Credentials on Source and Destination Clusters .

If the existing deployments in the project require a different security profile from the imported process, create a new project into which you can import the source MongoDB deployment.

Examples of Imported Users¶

The following examples apply to situations where the MongoDB deployment requires authentication or the Cloud Manager project has authentication settings enabled.

If you import the MongoDB users and custom roles, once the Cloud Manager project begins to manage the MongoDB deployment, the following happens, regardless of the Enforce Consistent Set value:

The Cloud Manager project enables authentication, manages imported users and roles, and syncs the new users and roles to all its managed deployments.
The MongoDB deployment’s access control is enabled and requires authentication. The MongoDB deployment has all users and roles that the Cloud Manager project manages. These users and roles have Synced set to Yes .

If you don’t import the MongoDB users and custom roles, once the Cloud Manager project begins to manage the MongoDB deployment, the following happens:

If Enforce Consistent Set is set to Yes :

The Cloud Manager project enables authentication and doesn’t change its managed users and roles.
The MongoDB deployment’s access control is enabled and requires authentication.
Cloud Manager deletes the non-imported MongoDB users and roles from the deployment.
The MongoDB deployment has all users and roles that the Cloud Manager project manages. These users and roles have Synced set to Yes .

If Enforce Consistent Set is set to No :

The Cloud Manager project enables authentication and doesn’t change its security settings, including users and roles.
The MongoDB deployment’s access control is enabled and requires authentication.
The non-imported MongoDB users and roles remain in the MongoDB deployment.
The MongoDB deployment has all users and roles managed by the Cloud Manager project. These users and roles have Synced set to Yes .

Prerequisites¶

If mongod is enabled as a service on the deployment, a race condition might result where systemd starts mongod on reboot, rather than the Automation. To prevent this issue, ensure the mongod service is disabled before you add your deployment to Automation:
1. Verify whether the mongod service is enabled:
copy
copied
```
sudo systemctl is-enabled mongod.service
```
1. If the service is enabled, disable it:
copy
copied
```
sudo systemctl disable mongod.service
```
If the Cloud Manager project doesn’t have authentication settings enabled but the MongoDB process requires authentication, add the MongoDB Agent user for the Cloud Manager project with the appropriate roles. The import process displays the required roles for the user. The added user becomes the project’s MongoDB Agent user.
If the Cloud Manager project has authentication settings enabled, add the Cloud Manager project’s MongoDB Agent user to the MongoDB process.
- To find the MongoDB Agent user, click Deployments , then Security , then Users .
- To find the password for the Cloud Manager project’s MongoDB Agent user, use one of the following methods:
  - Using the UI
  - Using the API
  - Using the Configuration Backup file
  Follow the steps in the Add MongoDB Processes procedure to launch the wizard in the UI. When you reach the modal that says Do you want to add automation to this deployment? :
  
  Select Add Automation and Configure Authentication .
  
  Click Show Password .
  Use the Automation Configuration Resource endpoint:
  
  copy
  copied
  
  curl --user "{username}:{apiKey}" --digest \ --header "Accept: application/json" \ --include \ --request GET "<host>/api/public/v1.0/groups/<Group-ID>/automationConfig"
  Open the mmsConfigBackup file in your preferred text editor and find the autoPwd value.
  
  Example
  
  If the Cloud Manager project has Username/Password mechanism selected for its authentication settings, add the project’s Cloud Manager MongoDB Agents User mms-automation to the admin database in the MongoDB deployment to import.
  
  copy
  copied
  
  db.getSiblingDB("admin").createUser( { user: "mms-automation", pwd: <password>, roles: [ 'clusterAdmin', 'dbAdminAnyDatabase', 'readWriteAnyDatabase', 'userAdminAnyDatabase', 'restore', 'backup' ] }
The import process requires that the authentication credentials and keyfiles are the same on the source and destination clusters. To learn more, see Authentication Credentials on Source and Destination Clusters .

Important

If you are adding a sharded cluster, you must create this user through the mongos and on every shard. That is, create the user both as a cluster wide user through mongos as well as a shard local user on each shard.

Procedures¶

Add MongoDB Processes¶

To add existing MongoDB processes to Cloud Manager:

Navigate to the Deployment page for your project.¶

If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
If it is not already displayed, click Deployment in the sidebar.

Click Add and select Existing MongoDB Deployment .¶

Follow the prompts to add the deployment.¶

Add Authentication Credentials to your Deployment¶

After you add existing MongoDB process to Cloud Manager, you might have to add authentication credentials for the new deployments if authentication is enabled for the project into which you imported the deployment. See Authentication Use Cases to learn in which situations you must add Automation, Monitoring, or Backup credentials for your new deployment.

If you are adding a deployment that you intend to live migrate to Atlas, you need to add the deployment (and its credentials) only for Monitoring .

Select the authentication mechanism that you want to use:

SCRAM-SHA
LDAP
Kerberos
X.509

Add Credentials for Automation¶

To add credentials for a deployment that will use Automation but didn’t use it before you imported it to Cloud Manager:

Add the MongoDB Agent user to your databases.¶

The MongoDB Agent user performs automation tasks for your MongoDB databases. Make sure this MongoDB user has the proper privileges .

Navigate to the Security Settings dialog for your deployment.¶

If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
If it is not already displayed, click Deployment in the sidebar.
Click the Security tab.
Click the Settings tab.
Perform one of the following actions:
- If this is your first time configuring TLS , authentication, or authorization settings for this project, click Get Started .
- If you have already configured TLS authentication, or authorization settings for this project, click Edit .

Click Edit Credentials .¶

Add the appropriate credentials:¶

Setting	Value
MongoDB Agent Username	Enter the MongoDB Agent username.
MongoDB Agent Password	Enter the password for MongoDB Agent Username.

Setting	Value
MongoDB Agent LDAP Username	Enter the LDAP username.
MongoDB Agent LDAP Password	Enter the password for MongoDB Agent’s LDAP Username.
MongoDB Agent LDAP Group DN	Enter the Distinguished Name for the MongoDB Agent’s LDAP Group. Note Provide the MongoDB Agent’s LDAP Group DN only if you use LDAP Authorization. Each MongoDB Agent should have and use its own LDAP Group DN .

Setting	Value
Monitoring Kerberos Principal	Kerberos Principal.
Monitoring Keytab Path	Absolute file Ppath to the MongoDB Agent’s Keytab.
Monitoring LDAP Group DN	Enter the Distinguished Name for the MongoDB Agent’s LDAP Group. The LDAP Group DN is then created as a role in MongoDB to grant the MongoDB Agent the appropriate privileges. Note You only need to provide the LDAP Group DN if you use LDAP Authorization.

Setting	Value
MongoDB Agent Username	Active Directory user name.
MongoDB Agent Password	Active Directory password.
Domain	NetBIOS name of a domain in Active Directory Domain Services. Must be in all capital letters.

Setting	Value
MongoDB Agent Username	Enter the LDAP v3 distinguished name derived from the MongoDB Agent’s PEM Key file.
TLS/SSL CA File Path	The path on disk that contains the trusted certificate authority (CA) certificates in PEM format. These certificates verify the server certificate returned from any MongoDB instances running with TLS / SSL . You must enter at least one TLS / SSL CA file path.
MongoDB Agent PEM Key file	If your MongoDB deployment requires client certificates, on the line for the appropriate operating system, provide the path and `.pem` filename for the client certificate used by the MongoDB Agent’s PEM Key file on the server. You must enter a value for at least one MongoDB Agent PEM Key File.
MongoDB Agent PEM Key Password	Provide the password to the PEM Key file if it was encrypted.
MongoDB Agent LDAP Group DN	Enter the Distinguished Name for the MongoDB Agent’s LDAP Group. Note You only need to provide MongoDB Agent’s LDAP Group DN if you use LDAP Authorization.

Add Credentials for Monitoring¶

To add credentials for a deployment that will not use Automation but will use Monitoring:

Navigate to the Monitoring Settings dialog for your deployment.¶

If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
If it is not already displayed, click Deployment in the sidebar.
Click ellipsis icon , then click Monitoring Settings next to the deployment for which you want to view monitoring settings.

Click Credentials .¶

Add the appropriate credentials:¶

Setting	Value
Monitoring Username	Enter the Monitoring username.
Monitoring Password	Enter the password for Monitoring Username.

Setting	Value
Monitoring LDAP Username	Enter the LDAP username.
Monitoring LDAP Password	Enter the password for Monitoring’s LDAP Username.
Monitoring LDAP Group DN	Enter the Distinguished Name for the Monitoring’s LDAP Group. Note Provide the Monitoring’s LDAP Group DN only if you use LDAP Authorization. Each Monitoring should have and use its own LDAP Group DN .

Setting	Value
Monitoring Kerberos Principal	Kerberos Principal.
Monitoring Keytab Path	Absolute file Ppath to the Monitoring’s Keytab.
Monitoring LDAP Group DN	Enter the Distinguished Name for the Monitoring’s LDAP Group. The LDAP Group DN is then created as a role in MongoDB to grant the Monitoring the appropriate privileges. Note You only need to provide the LDAP Group DN if you use LDAP Authorization.

Setting	Value
Monitoring Username	Active Directory user name.
Monitoring Password	Active Directory password.
Domain	NetBIOS name of a domain in Active Directory Domain Services. Must be in all capital letters.

Setting	Value
Monitoring Username	Enter the LDAP v3 distinguished name derived from the Monitoring’s PEM Key file.
Monitoring PEM Key file	Provide the path and filename for the Monitoring’s PEM Key file on the server on the line for the appropriate operating system.
Monitoring PEM Key Password	Provide the password to the PEM Key file if it was encrypted.
Monitoring LDAP Group DN	Enter the Distinguished Name for the Monitoring’s LDAP Group. Note You only need to provide the Monitoring’s LDAP Group DN if you use LDAP Authorization.

Add Credentials for Backup¶

To add credentials for a deployment that will not use Automation but will use Backup:

Navigate to the Continuous Backup page for your project.¶

If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Project menu in the navigation bar.
Click Continuous Backup in the sidebar.

For your deployment, Click ellipsis icon , then click Edit Credentials .¶

Add the appropriate credentials:¶

Setting	Value
Backup Username	Enter the Backup username.
Backup Password	Enter the password for Backup Username.

Setting	Value
Backup LDAP Username	Enter the LDAP username.
Backup LDAP Password	Enter the password for Backup’s LDAP Username.
Backup LDAP Group DN	Enter the Distinguished Name for the Backup’s LDAP Group. Note Provide the Backup’s LDAP Group DN only if you use LDAP Authorization. Each Backup should have and use its own LDAP Group DN .

Setting	Value
Monitoring Kerberos Principal	Kerberos Principal.
Monitoring Keytab Path	Absolute file Ppath to the Backup’s Keytab.
Monitoring LDAP Group DN	Enter the Distinguished Name for the Backup’s LDAP Group. The LDAP Group DN is then created as a role in MongoDB to grant the Backup the appropriate privileges. Note You only need to provide the LDAP Group DN if you use LDAP Authorization.

Setting	Value
Backup Username	Active Directory user name.
Backup Password	Active Directory password.
Domain	NetBIOS name of a domain in Active Directory Domain Services. Must be in all capital letters.

Setting	Value
Backup Username	Enter the LDAP v3 distinguished name derived from the Backup’s PEM Key file.
Backup PEM Key file	Provide the path and filename for the Backup’s PEM Key file on the server on the line for the appropriate operating system.
Backup PEM Key Password	Provide the password to the PEM Key file if it was encrypted.
Backup LDAP Group DN	Enter the Distinguished Name for the Backup’s LDAP Group. Note You only need to provide Backup’s LDAP Group DN if you use LDAP Authorization.

MongoDB Compatibility Matrix — MongoDB Cloud Manager

MongoDB Compatibility Matrix¶

On this page

MongoDB Versions Compatible with Cloud Manager
Agent Compatibility
MongoDB Deployment Types

This page describes compatibility between Cloud Manager features and MongoDB.

Cloud Manager support for End of Life MongoDB versions

Cloud Manager doesn’t support Backup, Monitoring, or Automation for versions earlier than MongoDB 3.6.

MongoDB Versions Compatible with Cloud Manager¶

Cloud Manager can automate deployments running MongoDB versions 3.6 or later.
Cloud Manager can monitor deployments running MongoDB versions 2.6 or later.
Cloud Manager can back up deployments running MongoDB versions 2.6 or later.

Backup Considerations for MongoDB Versions¶

To learn more about backup considerations specific to MongoDB 4.4 and later and 4.2 and earlier, see Backup Considerations .

To learn more about MongoDB versioning, see MongoDB Versioning in the MongoDB Manual.

Agent Compatibility¶

Monitoring Compatibility¶

To monitor a deployment running MongoDB 3.6 or later release series, you must use Monitoring Agent version 2.7.0 or later.

Automation PowerPC Compatibility¶

To manage PowerPC Linux-based hosts, you must use Automation Agent 3.2.7.1927 or later.

MongoDB Deployment Types¶

Using Cloud Manager, you can configure all MongoDB deployment types: sharded clusters, replica sets, and standalones.

The shards in a sharded cluster must be replica sets. That is, a shard cannot be a standalone mongod . If you must run a shard as a single mongod (which provides no redundancy or failover), run the shard as a single-member replica set.

Note

You may not upgrade a sharded MongoDB deployment to version 3.4 if the deployment uses mirrored mongod instances as config servers. To allow the sharded deployment to be upgraded, see Convert Config Servers to a Replica Set . The conversion requires that the sharded deployment run MongoDB version 3.2.4 or later. Deployments running previous versions must upgrade to version 3.2.4 before an upgrade to version 3.4.

Read article

Stop Monitoring a Process — MongoDB Cloud Manager

Stop Monitoring a Process¶

On this page

Understand the Objectives
Complete the Prerequisites
Follow These Steps

This tutorial shows you how to stop monitoring a process . Once you stop monitoring a process, Cloud Manager stops displaying its status and tracking its metrics.

Understand the Objectives¶

Learn how to use the Cloud Manager Administration API to:

Find the host ID for the process.
Stop monitoring the process that matches the host ID.
Verify that Cloud Manager no longer monitors the process.

Complete the Prerequisites¶

Complete these prerequisites before you complete the tutorial.

Configure your access to the Cloud Manager Administration API .
Get the permissions needed to change monitoring settings. You need one of the following roles:
- Project Monitoring Admin
- Project Owner
Terminate the backups for the process before you stop monitoring it.

Follow These Steps¶

Complete all the following steps to use the API to stop monitoring a process.

Find the host ID for the process.¶

Use the Get One Host by Hostname and Port resource to find the process and retrieve the id value.

Learn What This Step Does¶

The Get One Host by Hostname and Port resource uses the hostname and port you specify to find the process. Then, it returns information about this process. You can find the id needed for the next step in the response.

Issue This Command¶

Copy the following curl command. Paste it into your preferred terminal or console. Replace the displayed placeholders with these values:

Placeholder	Description
`{PUBLIC-KEY}`	Public part of your API key.
`{PRIVATE-KEY}`	Private part of your API key.
`{PROJECT-ID}`	Unique identifier of the project that owns the host.
`{HOSTNAME}`	Primary hostname that Cloud Manager uses to connect to the instance. This may be a hostname, an FQDN , an IPv4 address, or an IPv6 address.
`{PORT}`	Port on which the process listens.

Replace the placeholders in the command, then execute it.

copy

        curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts/byName/{HOSTNAME}:{PORT}"

Copy the Host’s ID¶

In the response body, copy the value returned in the id field. You need the value for the next step.

Example

        
              copy
              
               copied
              
             {
  "alertsEnabled" : true,
  "aliases": [ "server1.example.com:27017", "203.0.113.3:27017" ],
  "authMechanismName" : "SCRAM-SHA-1",
  "clusterId" : "<cluster-ID-1>",
  "created" : "2021-04-22T19:56:50Z",
  "groupId" : "<project-ID-1>",
  "hasStartupWarnings" : false,
  "hidden" : false,
  "hostEnabled" : true,
  "hostname" : "server1.example.com",
  "id" : "{HOST-ID}",
  "ipAddress": "203.0.113.3",
}

Stop monitoring the process that matches the host ID.¶

Use the Stop Monitoring One Host resource to stop monitoring the host.

Learn What This Step Does¶

The Stop Monitoring One Host resource doesn’t actually delete the host. The resource deletes the host from the list of hosts that Cloud Manager monitors. This removes the process from monitoring.

Issue This Command¶

Copy the following curl command. Paste it into your preferred terminal or console. Replace the displayed placeholders with these values:

Placeholder	Description
`{PUBLIC-KEY}`	Public part of your API key.
`{PRIVATE-KEY}`	Private part of your API key.
`{PROJECT-ID}`	Unique identifier of the project that owns the host.
`{HOST-ID}`	Unique identifier of the host for the process. Use the `id` from step 1.

Replace the placeholders in the command, then execute it.

copy

        curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request DELETE "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts/{HOST-ID}"

Verify that Cloud Manager no longer monitors the process.¶

Use the Get One Host by Hostname and Port resource again to attempt to find the process using its hostname and port. Then, verify that details returns No host with hostname and port {HOSTNAME}:{PORT} exists in group {PROJECT-ID} .

Learn What This Step Does¶

The Get One Host by Hostname and Port resource uses the hostname and port you specify to find the process. Then, it returns information about this process. You can tell that Cloud Manager doesn’t monitor the process if the details value in the response is No host with hostname and port {HOSTNAME}:{PORT} exists in group {PROJECT-ID} . This means that Cloud Manager can’t find the host in the list of processes that it monitors.

Issue This Command¶

Copy the following curl command. Paste it into your preferred terminal or console. Replace the displayed placeholders with these values:

Placeholder	Description
`{PUBLIC-KEY}`	Public part of your API key.
`{PRIVATE-KEY}`	Private part of your API key.
`{PROJECT-ID}`	Unique identifier of the project that owns the host.
`{HOSTNAME}`	Primary hostname that Cloud Manager uses to connect to this instance. This may be a hostname, an FQDN, an IPv4 address, or an IPv6 address.
`{PORT}`	Port on which the process listens.

Replace the placeholders in the command, then execute it.

copy

        curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts/byName/{HOSTNAME}:{PORT}"

Check the Response Details¶

In the response body, check the value returned in the details field. If details returns No host with hostname and port {HOSTNAME}:{PORT} exists in group {PROJECT-ID} , you succeeded. Cloud Manager no longer monitors the process.

Read article

Public API Principles — MongoDB Cloud Manager

Public API Principles ¶

On this page

HTTP Methods
JSON
Linking
Lists
Envelopes
Pretty Printing
Response Codes
Errors
Authentication
Automation
Additional Information

The Cloud Manager Public API follows the REST architecture principles to expose internal resources that provide programmatic access to Cloud Manager’s features.

As with changes made through the web interface, changes made through the API are subject to Cloud Manager pricing . If you add servers and incur charges, you must have a valid credit card on file with Cloud Manager or risk having your account locked .

The API has the following features:

JSON entities: All entities are expressed in JSON .
Key-based access: Each Cloud Manager user or application needing to connect to Cloud Manager must generate an API key before accessing the Cloud Manager API .
Digest authentication: To ensure that your Public API Key is never sent over the network, API requests are authenticated using HTTP Digest Authentication.
Browsable interface: Using a consistent linking mechanism, you can browse the entire API by starting at the root resource and following links to related resources.
User Access Control: Each Cloud Manager user’s API capabilities match the permissions that their Cloud Manager Roles grant.

Example

A user with the Project Read Only role cannot modify any resource within that project whether through the Cloud Manager UI or the API .
API Network Whitelist: The Cloud Manager API supports a per-user API Whitelist for restricting API access to specific IP or CIDR addresses. For Cloud Manager users with a non-empty API whitelist, all API access must originate from a whitelisted IP address. An empty API whitelist grants access to all API endpoints from any IP address, except those that explicitly require whitelisting for access.

HTTPS Only: You can only access the API via HTTPS , ensuring all data sent over the network is fully encrypted using TLS .

HTTP Methods ¶

All resources support a subset of these common HTTP Methods:

Method	Purpose
`GET`	Retrieve the JSON representation of a resource.
`POST`	Create a new resource using the provided JSON representation.
`PUT`	Replace a resource with the provided JSON representation.
`PATCH`	Update the specified fields in a resource using the provided JSON representation.
`DELETE`	Remove a resource.
`HEAD`	Retrieve the response header without the JSON representation of the resource.

JSON ¶

All entities are represented in JSON . The following rules for requests and conventions of responses apply:

Request Rules¶

Apply the Correct Content Type Header

When sending JSON to the server via


      
       POST

PUT

, make sure to specify the correct content type request header:


      
       Content-Type:
      
      
       application/json

Set Dates as ISO 8601 Strings

When sending dates to the server (as query parameters or fields in POST or PATCH request entities), use dates formatted according to the ISO 8601 standard. If you don’t specify a time zone, Cloud Manager assumes UTC . Include a time zone designator to avoid any ambiguity.

Example

September 27, 2018 is expressed as 2018-09-27 .
September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as 2018-09-27T16:00-04:00 .

In some cases, a timestamp is returned as a JSON representation of a BSON timestamp, most notably in the backup resources. This representation of a BSON timestamp provides a JSON document as an object with two fields:

Field	Definition
`date`	Seconds since the UNIX Epoch
`increment`	An incrementing 32-bit integer ordinal for operations within a given second.

Example

The third operation at September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as

copy

{ date: 2018-09-27T16:00-04:00, increment: 3 }

Response Conventions¶

Rejects Invalid Fields

Invalid fields are rejected rather than ignored .

Example

You attempt to create a new entity and misspell one of the fields, or if you attempt to update an existing entity and include a field that cannot be modified, the Cloud Manager responds with an HTTP 400 status code and an error message stating which field was invalid.

Returns Dates as ISO 8601 Strings

All dates are returned as ISO 8601-formatted strings designated in UTC .

Labels Field to Disambiguate Units

Fields that contain numeric values in a particular unit are named so as to disambiguate the unit being used.

Example

A host’s uptime is returned in millseconds, so the name of the host entity field is uptimeMsec .

Returns Default Values for Fields without Other Values

Fields that do not have a current value are returned with an appropriate default value.

Example

Cloud Manager does not have any statistics for a newly discovered host, so any statistics-related fields have a value of zero.

Fields that do not have a sensible default value are omitted from the entity.

Example

A host that is not using authentication omits the username field from the returned entity.

Returns Fields in Alphabetical Order

The fields in the JSON documents that the Cloud Manager returns are in alphabetical order. The order could change. Do not depend on the order of the fields.

Linking¶

Each resource includes one or more links to sub-resources and/or related resources.

Example

A host has a link to the project it belongs to, the replica set it belongs to, and so on.

Links are placed in the links field of an entity, which is an array of link relation objects. Each link relation has two fields:

Field	Definition
`rel`	Name (or type) of the relation. Many of these are considered Extension Relation Types and are prefixed by `http://mms.mongodb.com` .
`href`	Target URL .

All entities include at least one link relation called self , which is simply its own URL . When an entity is part of a list (i.e., when requesting all hosts in a project), then it only includes the self link relation.

Example

This is a portion of a host resource with a few links:

     
           copy
           
            copied
           
          {
  "id": "xxx",
  "projectId": "yyy",
  "hostname": "mongodb.example.com",
  "port": 27017,
  "links": [
    {
      "rel": "self",
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx/hosts/yyy"
    },
    {
      "rel": "http://mms.mongodb.com/project",
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
    }
  ]
}

To learn more, see the Web Linking Specification.

Note

Although the Web Linking Specification describes a format for including links in the HTTP response headers, it is not required. To make the API easily browsable, it includes the links in the response body rather than in the response headers.

Lists¶

Some resources return a list of entities.

Example

You can request a list of all hosts in a project .

When a list of entities is expected in a response, the results are returned in batches bounded by two query parameters:

Field	Definition
`pageNum`	Page number (1-based). Defaults to 1 if not specified.
`itemsPerPage`	Number of items to return per page, up to a maximum of 500. Defaults to 100 if not specified.

The response entity contains three fields:

Field Definition

Field	Definition
`totalCount`	Total number of items in the entire result set. Example If a project has a total of 57 hosts, and you make a request with `pageNum=6` and `itemsPerPage=10` , then `totalCount` is 57 .
`results`	Result set, which is an array of entity documents.
`links`	Contains one to three link relations: `previous` for the previous page of results (omitted for the first page); `next` for the next page of results (omitted for the last page); `self` for the current page (always present).


       
        totalCount

Total number of items in the entire result set.

Example

If a project has a total of 57 hosts, and you make a request with pageNum=6 and itemsPerPage=10 , then totalCount is 57 .

results Result set, which is an array of entity documents.


       
        links

Contains one to three link relations:

previous for the previous page of results (omitted for the first page);
next for the next page of results (omitted for the last page);
self for the current page (always present).

If you make a request for a list of entities and there are no results, then the API responds with an HTTP 200 status code and an empty results array. It does not respond with a 404 in this case, since the list of entities may not be empty at some point in the future.

If you had requested a list of entities in a context that does not exist (i.e., the list of hosts for a non-existent project), then this results in a an HTTP 404 response status.

Example

This is an HTTP response for the second page of 10 hosts in a project with a total of 57 hosts:

copy

{

  "totalCount": 57,
  "results": [
    {
      "id": "yyy",
      "projectId": "xxx",
      // additional host properties...
    },
    // additional host documents...
  ],
  "links": [
    {
      "rel" : "self",
      "href" : "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?pageNum=2&itemsPerPage=10"
    },
    {
      "rel": "previous",
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=1"
    },
    {
      "rel": "next",
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=3"
    }
  ]
}

Envelopes¶

Some clients may not be able to access the HTTP response headers and/or status code. In that case, you can request that the response include an envelope , which is simply an extra layer of information in the JSON document that contains any relevant details that would normally be in the response headers.

By default, the API does not include the response in an envelope. To request one, simply add the query parameter envelope=true .

For responses that contain a single entity, the envelope contains two fields:

Field	Definition
`status`	HTTP status code.
`content`	Requested entity.

For responses that contain a list of entities, there is already an envelope that wraps the results, so specifying envelope=true as a query parameter in this case only adds the status field to the existing envelope.

Pretty Printing¶

By default, extraneous whitespace is stripped from the JSON that Cloud Manager returns. To ask for pretty-printed JSON , simply append the pretty=true query parameter to any request:

copy

     curl --user '{USERNAME}:{APIKEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/api/public/v1.0?pretty=true"

    

Note

All the examples in this document show pretty-printed JSON for clarity, although some example URL s may not contain this additional query parameter .

Response Codes¶

Responses utilize the standard HTTP response codes, including:

Code	Meaning	Notes
200	OK	The request was successful. This is the typical response to a successful `GET` request.
201	Created	A new resource was created. This is the typical response to a successful `POST` request.
202	Accepted	A request for an asynchronous operation was accepted.
400	Bad Request	Something was wrong with the client request.
401	Unauthorized	Authentication is required but was not present in the request. Typically this means that the digest authentication information was omitted from the request, the provided credentials are incorrect, or the user associated with the given API key is not allowed to access the requested resource.
403	Forbidden	Access to the specified resource is not permitted.
404	Not Found	The requested resource does not exist.
405	Method Not Allowed	The HTTP method is not supported for the specified resource. Keep in mind that each resource may only support a subset of HTTP methods. Example You are not allowed to `DELETE` the root resource.
409	Conflict	This is typically the response to a request to create or modify a property of an entity that is unique when an existing entity already exists with the same value for that property. Example If you attempt to create a project with the same name as an existing project, the request fails.
5xx	Various server errors	Something unexpected went wrong. Try again later and consider notifying Cloud Manager Support.

Errors¶

When a request results in an error, the response body contains a JSON document with additional details about what went wrong. The document contains five fields:

Field	Data Type	Definition
`detail`	string	Human-readable description of the API request error.
`error`	integer	HTTP status code .
`errorCode`	string	Named constant representing the API request error as shown in Cloud Manager Administration API Error Codes .
`parameters`	array of strings	List of parameters passed in the API request.
`reason`	string	HTTP status code definition .

Example

Cloud Manager returns this response body for an incorrectly formatted request:

     
          {
  "detail" : "Cannot find resource /api/public/v1.0/softwareComponents/version.",
  "error" : 404,
  "errorCode" : "RESOURCE_NOT_FOUND",
  "parameters" : [ "/api/public/v1.0/softwareComponents/version" ],
  "reason" : "Not Found"
}

To review the list of codes, see Cloud Manager Administration API Error Codes .

Authentication¶

As previously mentioned, the Cloud Manager API uses HTTP Digest Authentication. The details of digest authentication are beyond the scope of this document, but it essentially requires a username and a password which are hashed using a unique server-generated value called a nonce . The username is the username of a registered Cloud Manager account, and the password is a Public API Key associated with that account.

Keep the following points in mind:

The server-generated nonce is used by the client to hash the username and password before sending them back to the server to authenticate a request. The nonce is only valid for a short amount of time as per the digest authentication specification. This is to prevent replay attacks, so you cannot cache a nonce and use it forever.

Using digest authentication in combination with HTTPS provides an extra layer of security by ensuring that a password is never transmitted back to the server.

Some resource methods require even more security and are additionally protected by whitelists that allow access to the resource only from the IP addresses listed. Each user configures their own whitelist of IP addresses that allow access to the resource.
The Cloud Manager has a concept of roles , which allow more fine-grained control of the operations a user is allowed to perform. The API resources also enforce the same authorization rules, so the resources and methods that can be accessed by an API key are governed by the roles granted to the associated user.

Example

To DELETE a host, the user that owns the API key used to make the request must be a Project Monitoring Admin or Project Owner in the project to which the host belongs.

Many resources are tied to a project (former known as a group ), as evidenced by URL s of the following form:
copy
copied
```
/api/public/v1.0/groups/{PROJECT-ID}/
```
For these resources, the user tied to the API key must be a member of the project. Otherwise Cloud Manager responds with an HTTP 401 error.

Automation¶

The Automation Configuration Resource and Get Automation Status of Latest Plan resources provide endpoints that let you modify a project’s deployment and retrieve deployment status. You can modify a deployment by sending a new automation configuration to Cloud Manager. The automation configuration is where you describe and configure the MongoDB processes to be deployed. Cloud Manager refers to this as the deployment’s “goal state.” When you submit a new automation configuration through the API , the Automations adjust the current state of the system to match the goal state.

Important

There is no protection in the API to prevent concurrent modifications. If two administrators both start with a configuration based on the current version, make their own modifications, and then submit their modifications, the later modification wins.

Rate Limiting¶

Certain resources are subject to rate limiting.

For resources that are rate limited, Cloud Manager allows up to 100 requests per minute per project . Keep in mind that a Public API Key is assigned to a Cloud Manager user, but that user may access multiple projects.

Example

Consider two users: A and B.

User A belongs to project X, and user B belongs to projects X and Y.

At 1:00:00pm, User A makes 50 requests to a rate limited resource in project X, all of which complete by 1:00:20pm.
At 1:00:30pm, User B attempts to make 60 requests to a rate limited resource in project X.

Since User A has already used up 50 requests within the 1:00pm minute for project X, the last 10 requests User B attempts to make are rejected. However, User B can make requests to a rate limited resource in project Y, since each project maintains a separate request counter.
At 1:01pm, requests to project X may proceed, because the request counter used for rate limiting reset each minute.

If you exceed the rate limit, the API returns an HTTP 429 Too Many Requests response code.

Additional Information¶

See Cloud Manager Administration API Resources for a complete reference of all resources available in the Cloud Manager Public API .

Read article

Welcome to Knowledge Base!

KB at your finger tips

Database-MongoDB