> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Automation Cloud Manager Automation allows you to deploy, configure, and manage MongoDB deployments with the Cloud Manager UI. Cloud Manager Automation relies on an MongoDB Agent, which must be installed on every server in the deployment. The MongoDB Agents periodically poll the Cloud Manager service to determine the current goal, and continually report their status to Cloud Manager. ## Automation Runs Only on 64-bit Architectures Cloud Manager provides only 64-bit downloads of the MongoDB Agent. ## Using Own Hardware - If you deploy Automation manually, ensure that you have one MongoDB Agent on every server. - If you deploy the agent manually, you must create MongoDB's `dbPath` and the directory for the MongoDB binaries and ensure that the user running the agent owns these directories. If you install using the `rpm` package, the agent runs as the `mongod` user; if using the `deb` package, the agent runs as the `mongodb` user. If you install using the `tar.gz` archive file, you can run the agent as any user. ## Networking ### Connectivity to MongoDB Ports All hosts must be able to allow communication between MongoDB ports. The default is `27017`, but you can configure alternate port ranges in the Cloud Manager interface. The MongoDB Agent *must* be able to connect to `cloud.mongodb.com` on port `443` (HTTPS (Hypertext Transfer Protocol Secure)). For more information on access to ports and IP addresses, see [Security Overview.](https://www.mongodb.com/docs/cloud-manager/core/security.md) ### Intra-cluster Connectivity Issue When performing a rolling update, the MongoDB Agent tries to avoid downtime. It needs to collect state from other members of the cluster. A connectivity issue (between [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod)s and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos)es), such as hostname resolution or misconfigured firewall, may prevent the MongoDB Agent from determining the remote processes state and completing the change. To ensure all members of the cluster can communicate with each other: 1. For a non-sharded cluster: Log into each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod). From that [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) host, log into all the other members of the replica set. 2. For a sharded cluster: Log into each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod). From that [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) host, log into all the other members of the shard. Log into each [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos). From that the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) host: Log into the other [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) hosts. Log into all the other members of each shard. ### Frequent Automation Connections MongoDB Agent gathers the state from each member of the cluster every 10 seconds to ensure that the environment is in the expected state. As part of this assessment, MongoDB Agent creates a connection, checks certain files to determine state, and then closes the connection. These frequent, short-lived connections are part of MongoDB Agent's routine activity and should not impact performance. ## Automation Configuration After completing the automation configuration, ensure that the deployment plan satisfies the needs of your deployment. Check hostnames and ports before confirming the deployment. ## Sizing - Ensure that you provision hosts with enough space to run MongoDB and support the requirements of your data set. - Ensure that you provision a sufficient number of hosts to run your deployment. Each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) should run on its own host. ## Frequent Connection Timeouts The MongoDB Agent may frequently time out of connections for one or more of the following reasons: - Connection timeouts - High network latency - High server load - Large SSL keys - Insufficient CPU speed By default, connections time out after 40 seconds. MongoDB recommends gradually increasing the value of the [`dialTimeoutSeconds`](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-dialTimeoutSeconds) MongoDB Agent configuration setting to prevent frequent premature connection timeouts. However, increasing this value also increases the time required to deploy future configuration changes. Experiment with small, incremental increases until you determine the optimum value for your deployment. To learn more, see [`dialTimeoutSeconds`](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-dialTimeoutSeconds) in MongoDB Agent Connection Settings. ## Deployments A banner that displays We have detected a potential problem while deploying... appears when certain conditions apply. These are some examples. ### Deployment Change Unable to Complete / Not Proceeding If you have added or restarted a deployment and the deployment remains in the `In Progress` state for several minutes, the banner displays. At this point, you have four options: 1. Click View Diagnostics. The View Diagnostics modal displays any errors that may have happened during deployment. 2. Click View Status. The Automation Status modal displays the deployment processes, when they last reported their deployment status, what task they are trying to complete, and the deployment status. You can filter the results in the following ways: - Type a hostname in the Filter processes search bar. - Select one or more process types from the Process Type dropdown. - Select one or more automation states from the Automation State dropdown. To learn more about the status of any of the individual processes, you can click the ellipsis icon and select either View Details or View Agent Logs. - View Details shows what the deployment plan for the process is and which stage of that plan the MongoDB Agent currently is. - View Agent Logs opens a new browser window with the Deployment > Agents > Agent Logs screen shown and the contents of the MongoDB Agent log displayed by default. Click the View menu to select a different agent log. 3. Click View Agent Logs. A new browser window opens with the Deployment > Agents > Agent Logs screen shown and the contents of the MongoDB Agent log displayed by default. Click the View menu to select a different agent log. 4. Click Allow Override & Edit Configuration. If you diagnose an error and need to correct the deployment configuration, follow the procedure to [edit the deployment.](https://www.mongodb.com/docs/cloud-manager/tutorial/edit-deployment.md) If you shut down the deployment and still cannot find a solution, [remove the deployment](https://www.mongodb.com/docs/cloud-manager/tutorial/unmanage-deployment.md) from Cloud Manager. ### MongoDB Agents Are Down or Not Communicating If Automation Module of MongoDB Agent can't communicate with the Cloud Manager [`API endpoint`](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-mmsBaseUrl) or the MongoDB Server processes, Cloud Manager displays a warning banner in the Project. You can resolve this in one of two ways depending upon whether or not you expect the MongoDB Agents to be communicating: #### MongoDB Agents need to communicate If the MongoDB Agent(s) should be communicating with the Cloud Manager host or MongoDB instances, confirm the following for each MongoDB Agent: The Agent is up and running on each host. The Agent and the Cloud Manager [API endpoint](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-mmsBaseUrl) can [communicate.](https://www.mongodb.com/docs/cloud-manager/reference/troubleshooting/automation.md#std-label-automation-networking) #### MongoDB Agents Do Not Need to Communicate If Automation Module of MongoDB Agent(s) should be communicating with the Cloud Manager [`API endpoint`](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-mmsBaseUrl) or MongoDB Server processes, confirm the following for each automated MongoDB Server deployment: Click the Allow Editing & Override Current Configuration link in the warning banner. [Remove all processes](https://www.mongodb.com/docs/cloud-manager/tutorial/unmanage-deployment.md) ([`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) *and* [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos)) running on the hosts that serve the unneeded MongoDB Agents. ## MongoDB Agent Permissions A permissions issue may prevent automation from completing a change. If View Status or View Diagnostics report an permissions-related error (such as `open /data/db/mongod.lock: permission denied`), ensure that the MongoDB Agent user owns and has read and write permissions to the `dbpath` and `logpath` files. ## Remove Problematic MongoDB Hosts You can use the console or the API (Application Programming Interface) to remove stale, broken, or problematic hosts from automation. This may include the circumstance when the MongoDB Agent can't be reached. To remove a problematic host using the console: 1. In MongoDB Cloud Manager, go to the Processes page for your project. If it's 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. In the sidebar, click Processes under the Database heading. The [Processes](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fdeployment%2Flist) page displays. 2. Remove the host. Find your problematic host. Click , then Remove Server. Cloud Manager displays the Are you sure you want to remove this server> modal. Enter the provided hostname into the Enter the host name field an click Remove if you want to remove this server. **Warning:** Cloud Manager removes all monitoring data for this host when you click Remove. Cloud Manager provides no confirmation or cancellation for this action. If you don't want to remove the server, click Cancel. Click Review & Deploy to review your changes. Cloud Manager displays your proposed changes. - If you are satisfied, click Confirm & Deploy. Cloud Manager removes all processes and agents at this time. - If you want to make further configuration changes, click Cancel. To remove a problematic host using the API (Application Programming Interface): [Get the current automation config.](https://www.mongodb.com/docs/cloud-manager/reference/api/automation-config/get-automation-config.md) Edit the automation configuration JSON (Javascript Object Notation) file. Remove the stale node from [processes](https://www.mongodb.com/docs/cloud-manager/reference/api/automation-config/automation-config-parameters.md#std-label-autoconfig-mongodb-processes) and [replica sets.](https://www.mongodb.com/docs/cloud-manager/reference/api/automation-config/automation-config-parameters.md#std-label-autoconfig-mongodb-replicasets) [Update the automation config file.](https://www.mongodb.com/docs/cloud-manager/reference/api/automation-config/update-automation-config.md) Wait for a few minutes. In MongoDB Cloud Manager, go to the Agents page for your project. If it's 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. In the sidebar, click Agents under the Database heading. The [Agents](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fdeployment%2Fagents%2Fall) page displays. Confirm the host no longer appears on the list of Agents. ## Ensure TLS Certificates Contain a Subject Alternative Name **Warning:** The MongoDB Agent from [version 11.11.0.7349-1](https://www.mongodb.com/docs/cloud-manager/release-notes/mongodb-agent.md#std-label-11.11.0.7355) requires TLS (Transport Layer Security) certificates to include a value in the Subject Alternative Name field. Before upgrading to [MongoDB Agent 11.11.0.7355](https://www.mongodb.com/docs/cloud-manager/release-notes/mongodb-agent.md#std-label-11.11.0.7355) or later, make sure that all TLS (Transport Layer Security) certificates used in your MongoDB deployment contain a SAN (Subject Alternative Name). MongoDB wrote the MongoDB Agent the Go language. Go 1.17 removed the ability to use [X.509 CommonName field as a hostname](https://go.dev/doc/go1.17#crypto/x509) when no SAN (Subject Alternative Name) exists. When clients validate TLS (Transport Layer Security) certificates, the client checks the hostname or hostnames to which the certs apply from the values in the cert's SAN (Subject Alternative Name) or Subject Distinguished Name (DN) fields. When creating TLS (Transport Layer Security) certificates, some people would use the Subject Common Name (CN) field to store the hostname. CNs have limitations that make them a poor choice to store hostnames. These limits include a 64-character maximum length and no support for Name Constraints. [RFC 2818](https://tools.ietf.org/html/2818) deprecated using CN to store hostnames in May 2000. This RFC required clients to fall back to the CN if the certificate had no values in the SAN (Subject Alternative Name) field. [RFC 6125](https://tools.ietf.org/html/6125) removed the requirement in 2011. Go 1.15 disables adherence to [RFC 2818](https://tools.ietf.org/html/2818) and uses the [RFC 6125](https://tools.ietf.org/html/6125) practice of making CN optional. In practice, this change requires you to either add SAN (Subject Alternative Name) values or enable the use of CNs. Go 1.17 removes the workaround to use the CN if no SAN exists. With the current version of the MongoDB Agent, you *must* use SAN (Subject Alternative Name). To learn more, see [Fraser Tweedale's blog post on this topic](https://frasertweedale.github.io/blog-redhat/posts/2017-07-11-cn-deprecation.html) ## Store Configuration Files in Memory for Existing Clusters If you use Cloud Manager version 4.2 or versions 4.4.0 - 4.4.6, you may encounter errors when setting [`enableLocalConfigurationServer`](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-enableLocalConfigurationServer) to `true` and restarting your MongoDB Agent. This issue only affects existing clusters where [`enableLocalConfigurationServer`](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#mongodb-setting-enableLocalConfigurationServer) is set to `true` after the cluster is created. Setting this value before creating the cluster does not trigger this issue. To safely change this setting for existing clusters: 1. At the end of your MongoDB Agent [configuration file](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-settings.md#std-label-mongodb-agent-config-file-location), add: ```ini enableLocalConfigurationServer=true ``` 2. [Shut down](https://www.mongodb.com/docs/cloud-manager/tutorial/shut-down-deployment.md) each process managed by the MongoDB Agent. 3. Restart the MongoDB Agent by running the following command: ```ini service mongodb-mms-automation-agent restart ``` 4. [Restart](https://www.mongodb.com/docs/cloud-manager/tutorial/restart-processes.md) the MongoDB processes that you shut down. 5. Verify that the `automation-mongod.conf` file has the [`__rest`](https://www.mongodb.com/docs/manual/reference/expansion-directives.md#mongodb-configexpansion-configexpansion.__rest) expansion directive. For more information on storing configuration files in memory, see [Configure How the MongoDB Agent Manages Config Files and Passwords.](https://www.mongodb.com/docs/cloud-manager/reference/mongodb-agent-external-configuration.md)