For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Update the Automation Configuration

A project's automation configuration determines the goal state of its MongoDB processes and agents. The MongoDB Agent builds the deployment according to the goals specified.

To update the configuration:

  1. Retrieve the current configuration.

    You can use the /groups/{PROJECT-ID}/automationConfig endpoint to get the full configuration, or use the /groups/{PROJECT-ID}/automationConfig/noSecrets endpoint to get the configuration with sensitive information redacted, such as passwords or key values.

    Note the value of the version field in the response body.

  2. Make changes to a copy of the current configuration, changing only those items you want modified.

    Keep the version field set to the value that you noted in the previous step.

  3. Submit your new configuration using PUT, with the updated configuration in the request body. You must use PUT. Do not use PATCH.

    Starting in Ops Manager 8.0.28 and 9.0.2, if another user or process published a change after you retrieved the configuration, Ops Manager rejects the request with a 409 AUTOMATION_CONFIG_CONCURRENT_MODIFICATION error. Retrieve the configuration again, reapply your changes, and resubmit the request.

    When you submit updates, Ops Manager makes internal modifications to the data and then saves your new configuration version.

Important

An automation configuration might contain sensitive information, including passwords or key values. To update a project's automation configuration without updating any fields that contain sensitive information, use the /groups/{PROJECT-ID}/automationConfig/noSecrets endpoint.

Note

Some parameters cannot be updated through the automationConfig endpoint. To learn more, see:

To make updates to the MongoDB Agent other than hostname, you must do so through a different endpoint.

To see a tutorial on how to update an automation configuration, see Update a Project's Automation Configuration.

The MongoDB Agents continuously poll Ops Manager for changes to the configuration and fetch configuration updates when they occur. The Agents then adjust the states of their live processes to match.

Warning

Making changes to the automation configuration using a PUT request can cause cluster downtime. Test your changes in lower environments before you apply them to production environments.

Starting in Ops Manager 8.0.28 and 9.0.2, Ops Manager protects against concurrent modifications by checking the version field in your request body. If the value does not match the current configuration version, Ops Manager rejects the request with a 409 AUTOMATION_CONFIG_CONCURRENT_MODIFICATION error. Always include the version field in your request body. If you omit it, Ops Manager cannot detect that your copy is out of date, and the request overwrites any changes published after you retrieved the configuration. In earlier versions, Ops Manager applies the later modification without checking the version.

Warning

Update Agent Username before Enabling Authentication

The automation configuration provides the sole means to enabling authentication on your clusters using the API. To enable authentication, first call the following endpoints with "username": "mms-automation":

After you call these endpoints, retrieve the automation configuration again so that your PUT request body contains the current version value.

This resource requires the Project Automation Admin role.

Base URL: https://{OPSMANAGER-HOST}:{PORT}/api/public/v1.0

PUT /groups/{PROJECT-ID}/automationConfig
Name
Type
Necessity
Description

PROJECT-ID

string

Required

Unique identifier of the group that owns the automation configuration.

The following query parameters are optional:

Name
Type
Necessity
Description
Default

pretty

boolean

Optional

Flag indicating whether the response body is in a prettyprint format.

false

envelope

boolean

Optional

Flag that indicates whether to wrap the response in an envelope.

Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

For endpoints that return one result, the response body includes:

  • status: HTTP response code

  • content: Expected response body

false

To review these parameters, see Automation Configuration Parameters.

To review these parameters, see Automation Configuration Parameters.

The following replaces the automation configuration with the updated configuration saved in /Users/admin/updated-conf.json. For an example of an updated configuration document, see Example Automation Configuration.

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --include \ --request PUT "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true" \ --data-binary "@/Users/admin/updated-conf.json"
HTTP/1.1 401 UnauthorizedContent-Type: application/json;charset=ISO-8859-1Date: {dateInUnixFormat}WWW-Authenticate: Digest realm="MMS Public API", domain="", nonce="{nonce}", algorithm=MD5, op="auth", stale=falseContent-Length: {requestLengthInBytes}Connection: keep-alive
HTTP/1.1 200 OKVary: Accept-EncodingContent-Type: application/jsonStrict-Transport-Security: max-age=300Date: {dateInUnixFormat}Connection: keep-aliveContent-Length: {requestLengthInBytes}X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}

To review an example of this configuration, see Example Automation Configuration.