BLOGAnnounced at MongoDB.local NYC 2024: A recap of all announcements and updates — Learn more >

Automation Beta Get Started Guide

I. Notes on the Automation architecture

  • Automation Agents
  • An Automation agent must be running on every server you wish to run an Automation-managed MongoDB process
  • All MongoDB process for a particular replica set or cluster must be Automation-managed.  You cannot Automation-manage, for example, one node of a replica set.
  • The configuration file on the server identifies the agent to MMS
  • the Automation Agent uses your MMS group’s unique ID and API Key (you will set this in a config file) to identify itself
  • The Automation Agent pulls configuration from MMS
  • the Automation Agent “phones home” to the hosted MMS service which maintains configuration metadata.
  • Agent brings its server to goal state (if it has the necessary permissions, and space)
  • the Automation Agent then proceeds with a set of instructions given to it via MMS on its local machine, including downloading binaries and deploying processes.

II. Features and Limitations

Supported Features

The following actions are supported, with limitations listed below

  1. Deploy new MongoDB processes on existing hardware (standalones, replica sets, or sharded clusters)
  • To do this, start by installing an Automation Agent on each server.
  • Then use the MMS UI to configure your deployment across those  
  • many standard (but not all) MongoDB configuration options are available in the deployment UI

  1. Import existing existing standalones or replica sets  (that is,“attach” Automation to system already running)
  • Prerequisites:
  1. All processes must first be monitored by MMS Monitoring
  2. The displayed name for each process in the cluster displayed in MMS Monitoring must match “hostname -f“ on the server.
  3. For Replica Sets, the displayed name for each process’s host in rs.conf() must match “hostname -f“ on the processes’ respective server.
  4. There must be a single Automation Agent installed on each server that hosts one or more processes in the cluster.
  5. The Automation Agent must be run as the same user as your MongoDB processes.
  • Although functionality to import sharded clusters is available, this is in “alpha”, and we do not recommend using this in production.
  1. Use MMS to Auto-Provision servers on AWS (which you can then deploy MongoDB processes onto, as described above)


  • Windows deployments are not supported
  • Configuration options not supported include:
  • auth
  • SSL
  • systemLog.verbosity
  • master/slave configuration
  • and more, including undocumented command line options
  • Shards must contain replica sets (no standalone shards currently supported).
  • You cannot currently choose which server an Arbiter or Hidden secondary will reside on after deployment of a replica set, or which server each member of a sharded cluster will be deployed on.
  • Removing nodes from a replica set, or shards from a cluster is not supported

III. How To: Deploy new MongoDB processes on existing hardware

Install the Automation Agent on Each Server

  • In the MMS UI, navigate to “Settings” > “Automation Agent”
  • Click the operating system you’re installing on and follow instructions

Configure Your Deployment In MMS

  • In the UI, navigate to the “Automation” > “Deployment” panel.
  • Click “+Add” and choose New “Standalone“, “Replica Set“, or “Sharded Cluster“
  • Fill in details
  • click “Show Member Options“ for replica set member configuration
  • click “Advanced options” to add other configuration options
  • Click Apply
  • Click “Review Changes”
  • Click “Confirm & Deploy”

IV. How To: Attach Automation To an Existing Cluster

  • Go the Automation -> Deployment tab.
  • Click the green Add button and choose “Manage Existing“
  • Check the box next to the name of your Cluster and choose “Start Import“
  • At this point, MMS will request that your Automation Agents connect to each process and send back detailed information about that process. (E.g. all its command line arguments)
  • You'll see a progress dialog, and then you can click “Confirm Import“
  • At this point, MMS will render a preview of what it thinks your cluster looks like.  Explore and make sure it looks good.

  • Click “Review Changes“ and then “Confirm and Deploy“
  • At this point, the Automation Agents will perform a rolling restart of your cluster to bring it “under their control“.   This will be done in a safe, rolling manner.... but depending on your application characteristics may still result in a service “blip“.  (For example, a client gradually pulling in results from a cursor containing thousands of results would be interrupted.)

What if something goes wrong?

  • There are two ways to back out.
  • The preferred method is to go back to “Automation -> Deployment“. Click “Edit Configuration“. Then click on the name of your Cluster. In the grey panel, choose the gear icon and select “Unmanage“. Review/Deploy that change. The Automation Agents will “let go“ and go back to doing nothing.
  • The Automation Agents can also simply be shut down

V. How To: Use MMS to Auto-Provision Servers on AWS

  • Configure an AWS Security Group with
  • SSH open to all IPs
  • “mongodb ports“ open within the Security Group (e.g. ports 27000-28000 for example)
  • In the UI, navigate to “Settings“ > “Automation Settings“
  • Click “Add AWS Configuration“ and fill in the details associated with your AWS account
  • Click “Add SSH Key” and fill in the details
  • Navigate to “Automation” > “Provisioning”
  • Click “+Add“ > “Provision EC2 Machine(s)“
  • Follow steps to provision, including choosing AMI and instance type
  • Provisioning may take a few minutes
  • Eventually confirm that Provisioned machines show up as eligible for deployment by navigating to  “Automation“ > “Deployment“ and
  • click “Server View“ to see eligible servers
  • click “Automation Agents” to confirm active Agents run on all provisioned hosts.
  • To deploy, follow steps under “Configure Your Deployment In MMS” above.

VI. Troubleshooting

Networking Troubleshooting

  • the agents must be able to reach via http
  • all mongods in a multi-node deployment must be able to communicate with each other on their respective ports

Permissions Troubleshooting

  • the agent is run by the same user that runs the mongod processes, and that user must have the following permissions set:
  • write and execute permissions on /var/lib/mongodb-mms-automation for downloading binaries
  • write permissions on /var/log/mongodb-mms-automation/ for writing log files
  • write permissions on /<yourDataDir> for writing the data
  • the agent must be able to spin up mongod processes with write permissions on /<yourDataDir>

You can also access the automation documentation here:

We look forward to hearing about your experience!

The MongoDB Team