• Create or Import a MongoDB Deployment >
• Add Existing MongoDB Processes to Cloud Manager

Add Existing MongoDB Processes to Cloud Manager

Cloud Manager provides a wizard for adding your existing MongoDB deployments to monitoring and management. The wizard prompts you to install an Automation if none exists, and then prompts you to identify the cluster, the replica set, or the standalone to add. You can choose to add the deployment to Monitoring or to both Monitoring and Automation.

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

Though you can use one TLS certificate with many SANs or a wildcard TLS certificate on each host, you should not. You should follow RFC 2818, section 3.1: keep the scope of TLS certificates as narrow as possible. This prevents man-in-the-middle attacks.

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

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.

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

• 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:

  • Create the credentials to the MongoDB Deployment.
    • Required Access for MongoDB Agent for Monitoring
    • Required Access for MongoDB Agent for Backup
  • Add the credentials you granted those functions to Cloud Manager after you add the MongoDB processes.
    • Add Credentials for Monitoring
    • Add Credentials for Backup

• If the deployment uses Automation, Cloud Manager uses the credentials from the legacy Automation 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 did not prior to being imported, you need to 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 or the MongoDB deployment or both.

Enables Cloud Manager Project Security Setting

If the MongoDB deployment requires authentication but the Cloud Manager project does not have authentication settings enabled, upon successful addition of the MongoDB deployment to automation, the project’s security settings will have the security settings of the newly imported deployment.

Note

The import process only enables the Cloud Manager project’s security setting if the project’s security setting is currently not enabled. If the project’s security setting is currently enabled, the import process does not disable the project’s security setting or change its enabled authentication mechanism.

Imports MongoDB Users and Roles

Note

The following applies for situations where at least either the 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 the Enforce Consistent Set value for the Cloud Manager project is YES, users and roles not imported are deleted from the MongoDB deployment.

If the Enforce Consistent Set value for the Cloud Manager project is No, non-imported users and roles are not managed by Cloud Manager project but remain in the MongoDB deployment. To manage these users and roles, you must connect directly to the MongoDB deployment.

If importing users and roles, before you confirm and deploy the changes, you can, from the Authentication & Users and Authentication & Roles screens, remove specific users and roles from being imported by unmanaging these users. For details on unmanaging MongoDB users, 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 procedure overrides the roles of these users with the roles for mms-backup-agent and mms-monitoring-agent users as set in the Cloud Manager project.

Applies to All Deployments in Cloud Manager Project

The project’s updated security settings, including all users and roles managed as part of 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. All deployments in the project will use the Cloud Manager automation keyfile upon restart.

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

Examples of Imported Users

Note

The following applies for situations where at least either the MongoDB deployment requires authentication or the Cloud Manager project has authentication settings enabled.

If you choose to import the MongoDB users and custom roles, once Cloud Manager project manages the MongoDB deployment, regardless of the value of Enforce Consistent Set:

Enforce Consistent Set	Results
Yes or No	Cloud Manager project: Authentication is enabled. Manages the imported users and roles. Syncs the new users and roles to all its managed deployments. The MongoDB deployment: Has access control enabled and requires authentication. All users and roles that the Cloud Manager project manages (i.e. has Synced set to Yes ) exist in the MongoDB deployment.

If you choose not to import the users, once Cloud Manager project manages the MongoDB deployment:

Enforce Consistent Set	Results
Yes	Cloud Manager project: Authentication is enabled. Has no changes to its managed users and roles. The MongoDB deployment: Has access control enabled and requires authentication. The non-imported MongoDB users and roles will be deleted from the MongoDB deployment. All users and roles that the Cloud Manager project manages (i.e. has Synced set to Yes ) exist in the MongoDB deployment.
No	Cloud Manager project: Authentication is enabled. Has no changes to its security settings, including users and roles. The MongoDB deployment: Has access control enabled and requires authentication. The non-imported MongoDB users and roles remain in the MongoDB deployment. All users and roles managed by the Cloud Manager project (i.e. has Synced set to Yes ) exist in the MongoDB deployment.

Prerequisites

• If the Cloud Manager project does not 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, you can use the UI, the API or the configuration backup file:

    Using the UI

    1. Navigate to Deployment, Security, and then Authentication & TLS/SSL

    2. Click Edit Settings.

    3. Click Next until you see the Configure Cloud Manager Agents page.

    4. Click Show to the right of the MongoDB Agent Password field.

       The MongoDB Agent’s password displays.

    Using the API

    Use the Automation Configuration Resource endpoint:

    copy

    curl --user "{username}:{apiKey}" --digest \
      --header "Accept: application/json" \
      --include \
      --request GET "<host>/api/public/v1.0/groups/<Group-ID>/automationConfig"
    

    Using the Cloud Manager Configuration Backup file

    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

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

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:

1

Navigate to the Deployment page for your project.

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

2

Click Add New and select Existing MongoDB Deployment.

3

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 to learn in which situations you must add Automation, Monitoring, or Backup credentials for your new deployment.

Note

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

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 did not before you imported it to Cloud Manager:

1

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.

2

Navigate to the Authentication & TLS Settings dialog for your deployment.

1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
3. If it is not already displayed, click Deployment in the sidebar.
4. Click the Security tab.
5. Click the Authentication & SSL tab.
6. Click Edit Settings.

3

Click Edit Credentials.

4

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

5

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.

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

• Linux KDC
• Windows Active Directory

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 LDAPv3 distinguished name derived from the MongoDB Agent’s PEM Key file.
MongoDB Agent PEM Key file	Provide the path and filename for the MongoDB Agent’s PEM Key file on the server on the line for the appropriate operating system.
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:

1

Navigate to the Monitoring Settings dialog for your deployment.

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

2

Click Credentials.

3

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.

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

• Linux KDC
• Windows Active Directory

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

1

Navigate to the Continuous Backup page for your project.

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

2

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

3

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.

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

• Linux KDC
• Windows Active Directory

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

←   Provision a Migration Host Deploy a Replica Set  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.