Add Existing MongoDB Processes to Cloud Manager

On this page

Considerations

Prerequisites
Procedures

Cloud Manager will no longer support Automation, Backup, and Monitoring for MongoDB 3.6 and 4.0 after August 30th, 2024. Please upgrade your MongoDB deployment or migrate to Atlas.

OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.: The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.

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

Install the MongoDB Agent if you don't have it installed
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, which can result in failed import attempts. To learn more, see MongoDB Settings and Automation Support.

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.

Important

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:
  sudo systemctl is-enabled mongod.service
2. If the service is enabled, disable it:
  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:
1
In MongoDB Cloud Manager, go to the Deployment page for your project.
If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Deployment page is not already displayed, click Deployment in the sidebar.
The Deployment page displays.
2
Go to the Security page.
Click the Security tab for your deployment.
The Security page displays.
3
Click Users.

To find the password for the Cloud Manager project's MongoDB Agent user, use one of the following methods:

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:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --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 is using Username/Password authentication, add the project's Cloud Manager MongoDB Agents User mms-automation to the admin database in the MongoDB deployment to import.

db.getSiblingDB("admin").createUser(
    {
      user: "mms-automation",
      pwd: <password>,
      roles: [
        'clusterAdmin',
        'dbAdminAnyDatabase',
        'readWriteAnyDatabase',
        'userAdminAnyDatabase',
        'restore',
        'backup'
      ]
    }

When you add a cluster under Cloud Manager, Cloud Manager automatically enables log rotation, which could collide with your existing logRotate configuration for mongod or mongos logs. To prevent this collision, do the following:
- Disable your logRotate configuration for mongod or mongos processes.
- Remove the systemLog.logRotate and systemLog.logAppend options from the mongod or mongos process configuration to use the default of Cloud Manager.
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.
To successfully import an existing replica set to Cloud Manager, the instance must be healthy.

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:

In MongoDB Cloud Manager, go to the Deployment page for your project.

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Deployment page is not already displayed, click Deployment in the sidebar.
The Deployment page displays.

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:

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.

In MongoDB Cloud Manager, go to the Deployment page for your project.

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Deployment page is not already displayed, click Deployment in the sidebar.
The Deployment page displays.

Go to the Security page.

Click the Security tab for your deployment.

The Security page displays.

Go to the Security Settings dialog for your deployment.

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

Continue through the modal until you see the Configure Cloud Manager Agents page.

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

The required values depend upon whether you are connecting to a Linux-served KDC or Windows Active Directory Server.

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. 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 LDAPv3 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. 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:

In MongoDB Cloud Manager, go to the Deployment page for your project.

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Deployment page is not already displayed, click Deployment in the sidebar.
The Deployment page displays.

Go to the Monitoring Settings dialog for your deployment.

Click , 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. Provide the Monitoring's LDAP Group DN only if you use LDAP Authorization. Each Monitoring should have and use its own LDAP Group DN.

The required values depend upon whether you are connecting to a Linux-served KDC or Windows Active Directory Server.

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. 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 LDAPv3 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. 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:

In MongoDB Cloud Manager, go to the Continuous Backup page for your project.

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Click Continuous Backup in the sidebar.
The Continuous Backup page displays.

For your deployment, Click , 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. Provide the Backup's LDAP Group DN only if you use LDAP Authorization. Each Backup should have and use its own LDAP Group DN.

The required values depend upon whether you are connecting to a Linux-served KDC or Windows Active Directory Server.

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. 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 LDAPv3 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. You only need to provide Backup's LDAP Group DN if you use LDAP Authorization.

Back

Use a Migration Host

Deploy a Replica Set

Considerations

Unique Names

Important

MongoDB Configuration Options

Important

Preferred Hostnames

Managing Windows MongoDB Services

Authentication Credentials on Source and Destination Clusters

Authentication Use Cases

Automation and Updated Security Settings Upon Import

Examples of Imported Users

Prerequisites

In MongoDB Cloud Manager, go to the Deployment page for your project.

Go to the Security page.

Click Users.

Example

Important

Procedures

Add MongoDB Processes

In MongoDB Cloud Manager, go to the Deployment page for your project.

Click Add and select Existing MongoDB Deployment.

Follow the prompts to add the deployment.

Add Authentication Credentials to your Deployment

Add Credentials for Automation

Add the MongoDB Agent user to your databases.

In MongoDB Cloud Manager, go to the Deployment page for your project.

Go to the Security page.

Go to the Security Settings dialog for your deployment.

Click Edit Credentials.

Continue through the modal until you see the Configure Cloud Manager Agents page.

Add the appropriate credentials:

Add Credentials for Monitoring

In MongoDB Cloud Manager, go to the Deployment page for your project.

Go to the Monitoring Settings dialog for your deployment.

Click Credentials.

Add the appropriate credentials:

Add Credentials for Backup

In MongoDB Cloud Manager, go to the Continuous Backup page for your project.

For your deployment, Click , then click Edit Credentials.

Add the appropriate credentials: