Navigation
This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.

Rotate a Key File with the API

On this page

You can programmatically rotate a key file by updating a project’s automation configuration.

To rotate a key file using the Ops Manager API:

  1. Retrieve the current configuration.
  2. Add the new key file that you want to use with the auth.newKey setting.
  3. Replace the entire configuration using PUT. You must use PUT. Do not use PATCH.

When all MongoDB Agents use the new key, Ops Manager replaces the value of auth.key with the new key that you provided in auth.newKey and removes auth.newKey from the automation configuration.

Prerequisites

  • You must have access to the API. To learn more, see Configure API Access.
  • Your API key must have the Project Automation Admin or Project Owner role.
  • Authentication must be enabled.
  • At least one cluster in the project must be configured with the clusterAuthMode option set to keyFile or sendKeyFile.
  • All clusters in the project must be running MongoDB version 4.2 or higher.

Variables for Automation Config API Resources

The API resources use one or more of these variables. Replace these variables with your desired values before calling these API resources.

Name Type Description
PUBLIC-KEY string Your public API Key for your API credentials.
PRIVATE-KEY string Your private API Key for your API credentials.
<OpsManagerHost>:<Port> string URL of your Ops Manager instance.
GROUP-ID string Unique identifier of your project from your Project Settings.
CLUSTER-ID string Unique identifier of your cluster.

Procedure

1

Retrieve and validate the automation configuration from Ops Manager.

  1. Use the automationConfig resource to retrieve the configuration. Issue the following command, replacing the placeholders with the Variables for Automation Config API Resources.

    copy 
    curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true" \
     --output currentAutomationConfig.json

  2. Validate the downloaded Automation Configuration file.

    Compare the version field of the currentAutomationConfig.json with that of the Automation Configuration backup file, mms-cluster-config-backup.json. The version value is the last element in both JSON documents. You can find this file on any host running the MongoDB Agent at:

    • Linux and macOS: /var/lib/mongodb-mms-automation/mms-cluster-config-backup.json
    • Windows: %SystemDrive%\MMSAutomation\versions\mms-cluster-config-backup.json

    If the version values match, you are working with the current version of the Automation Configuration file.

2

Add your new key file to the automation configuration file you downloaded.

  1. Open currentAutomationConfig.json in your preferred text editor.

  2. Add the auth.newKey field. Set this field’s value to the new key file that you want Ops Manager to use.

    Note

    The sample configuration below is truncated for readability.

    {
  "auth": {
    "disabled": "false",
    "key": "<your-old-key>",
    "newKey": "<your-new-key>"
  }
}

If you’re updating the MongoDB Agent, see Update Agent Versions before continuing with this procedure.

3

Send the updated automation configuration.

Use the automationConfig resource to send the updated automation configuration.

Issue the following command, replacing {configuration-document} with path to the updated configuration document and the placeholders with the Variables for Automation Config API Resources.

copy 
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --header "Content-Type: application/json"
     --request PUT "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true" \
     --data '
         @{configuration_document}
       '

Upon successful update of the configuration, the API returns the HTTP 200 OK status code to indicate the request has succeeded.

4

Confirm successful update of the automation configuration.

Retrieve the automation configuration from Ops Manager and confirm it contains the changes. To retrieve the configuration, issue the following command, replacing the placeholders with the Variables for Automation Config API Resources.

copy 
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true"
5

Check the deployment status to ensure goal state is reached.

Use the automationStatus resource to retrieve the deployment status. Issue the following command, replacing the placeholders with the Variables for Automation Config API Resources.

copy 
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{PROJECT-ID}/automationStatus?pretty=true"

Confirm that the values of all the lastGoalVersionAchieved fields in the processes array match the goalVersion field. To learn about deployment status, see Get Automation Status of Latest Plan.

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