Update the MongoDB Version of a Deployment
- OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.
- The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.
This tutorial describes how to use the API to migrate a
MongoDB deployment to a new version of MongoDB. These steps assume you
have an existing deployment that uses a 4.0.6
version of MongoDB,
as would be the case if you used the tutorial to
Deploy a Cluster through the API.
Note
Groups and projects are synonymous terms. Your {PROJECT-ID}
is the
same as your project id. For existing groups, your group/project id
remains the same. This page uses the more familiar term group when
referring to descriptions. The endpoint remains as stated in the
document.
Consideration
The API supports most MongoDB settings and parameters for MongoDB versions 2.6 and later. To learn more, see MongoDB Settings and Automation Support.
Variables for API Resources to Update MongoDB Version
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. |
cloud.mongodb.com | string | URL of your Cloud Manager instance. |
GROUP-ID | string | Unique identifier of your project from your
project settings. |
CLUSTER-ID | string | Unique identifier of your cluster. |
Prerequisite
You must have credentials to access Cloud Manager as a user with the
Project Owner
role for the Cloud Manager project in which the
deployment exists.
Procedure
Retrieve the automation configuration from Cloud Manager.
Use the automationConfig resource to retrieve the configuration. Issue the following command, replacing the placeholders with the Variables for API Resources to Update MongoDB Version.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --request GET "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true" \ --output currentAutomationConfig.json Validate the downloaded Automation Configuration file.
Compare the
version
field of thecurrentAutomationConfig.json
with that of the Automation Configuration backup file,mms-cluster-config-backup.json
. Theversion
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.
Open the configuration document for editing.
As you edit the configuration document in the next steps, refer to the description of an automation configuration for detailed descriptions of settings.
Send the updated automation configuration.
Use the automationConfig resource to send the updated automation configuration.
Issue the following command with path to the updated configuration document and replace the placeholders with the Variables for API Resources to Update MongoDB Version.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" --request PUT "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true" \ --data @currentAutomationConfig.json
Upon successful update of the configuration, the API returns the HTTP
200 OK
status code to indicate the request has succeeded.
Confirm successful update of the automation configuration.
Retrieve the automation configuration from Cloud Manager and confirm it contains the changes. To retrieve the configuration, issue the following command, replacing the placeholders with the Variables for API Resources to Update MongoDB Version.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --request GET "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/automationConfig?pretty=true"
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 API Resources to Update MongoDB Version.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --request GET "https://cloud.mongodb.com/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.