Skip to content

[ONPREM-2564] - Add docs on how to go from 4.4 to 7.0 #9776

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 21, 2025
Merged

[ONPREM-2564] - Add docs on how to go from 4.4 to 7.0 #9776

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7f190d2
Add docs on how to go from 4.4 to 7.0
imlogang Nov 19, 2025
7cb5114
style and formatting
rosieyohannan Nov 20, 2025
9283811
Add curly brackets around manual response
imlogang Nov 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 175 additions & 34 deletions docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,95 +1,236 @@
= Upgrade MongoDB
:page-platform: Server 4.9, Server Admin
:page-description: Learn how to upgrade MongoDB up to v4.4.15 in an installation of CircleCI server 4.9.
:page-description: Learn how to upgrade MongoDB up to v7.0.15 in an installation of CircleCI server 4.9.
:experimental:

MongoDB is a database service used by CircleCI server. This page describes how to upgrade MongoDB to version `4.4.15`.
MongoDB is a database service used by CircleCI server. This page describes how to upgrade MongoDB from version `3.6.22` to `7.0.15`.

MongoDB `3.6.22` is shipped with CircleCI server 4.9.

[#prerequisites]
== Prerequisites
[#upgrade-mongodb-to-4.4]
== Upgrade MongoDB to 4.4

* Ensure backups have been taken. You will need a backup of MongoDB to restore to in case anything goes wrong during the upgrade progress
* You are prepared to modify the `values.yaml`
* `helm upgrade` will work from your system to upgrade the cluster
* MongoDB root password is available
[#prerequisites-4.4]
=== Prerequisites

[#script-upgrade]
== Scripted upgrade
We have created a shell script which may be used to upgrade your cluster's MongoDB instance link:https://github.com/CircleCI-Public/server-scripts/tree/main/upgrade-mongo-to-4.4[here].
If you wish, you may use the following instructions to manually upgrade your cluster's MongoDB
* Ensure backups have been taken. You need a backup of MongoDB to restore in case anything goes wrong during the upgrade progress.
* You are able to modify your `values.yaml` file.
* `helm upgrade` works from your system to upgrade the cluster.
* Your MongoDB root password is available

[#manual-upgrade]
== Manual upgrade
[#script-upgrade-4.4]
=== Scripted upgrade
We have created a shell script that you can use to upgrade your cluster's MongoDB instance link:https://github.com/CircleCI-Public/server-scripts/tree/main/upgrade-mongo-to-4.4[here].

=== 1. Upgrade from MongoDB 3.6 to 4.0
Alternatively, you can use the following instructions to manually upgrade your cluster's MongoDB:

[#manual-upgrade-4.4]
=== Manual upgrade

==== 1. Upgrade from MongoDB 3.6 to 4.0

. Your `values.yaml` should contain the following snippet:
+
```yaml
[source,yaml]
----
mongodb:
image:
tag: 3.6.22-debian-9-r38
```
----
+
To begin the upgrade process, change the tag to `4.0.27-debian-9-r118`:
+
```yaml
[source,yaml]
----
mongodb:
image:
tag: 4.0.27-debian-9-r118
```
----

. Run `helm upgrade` to update your installation.

. Once the `helm upgrade` has completed and MongoDB has rolled, you will need to `exec` into the pod (with the root password handy) to modify the compatibility version. (Be sure to replace `<password>` with your MongoDB root password.)
+
```bash
kubectl exec -it mongodb-0 -- mongo -u root -p <password>
[source,console]
----
$ kubectl exec -it mongodb-0 -- mongo -u root -p <password>
db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )
```
----

. You should get a `{ "ok" : 1 }` response from Mongo. Exit out of the MongoDB shell and pod.

=== 2. Upgrade from MongoDB 4.0 to 4.2
==== 2. Upgrade from MongoDB 4.0 to 4.2

. Change the tag to `4.2.21-debian-10-r8`:
+
```yaml
[source,yaml]
----
mongodb:
image:
tag: 4.2.21-debian-10-r8
```
----

. Run `helm upgrade` to update your installation.

. Once the `helm upgrade` has completed and MongoDB has rolled, you will need to `exec` into the pod (with the root password handy) to modify the compatibility version. (Be sure to replace `<password>` with your MongoDB root password.)
+
```bash
kubectl exec -it mongodb-0 -- mongo -u root -p <password>
[source,console]
----
$ kubectl exec -it mongodb-0 -- mongo -u root -p <password>
db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
```
----

. You should get `{ "ok" : 1 }` again. Exit out of the shell and pod.

=== 3. Upgrade from MongoDB 4.2 to 4.4
==== 3. Upgrade from MongoDB 4.2 to 4.4

. Change the tag one more time to `4.4.15-debian-10-r8`:
+
```yaml
[source,yaml]
----
mongodb:
image:
tag: 4.4.15-debian-10-r8
```
----

. Run `helm upgrade` to update your installation.

. Once the `helm upgrade` has completed and MongoDB has rolled, you will need to `exec` into the pod (with the root password handy) to modify the compatibility version. (Be sure to replace `<password>` with your MongoDB root password.)
+
```bash
kubectl exec -it mongodb-0 -- mongo -u root -p <password>
[source,console]
----
$ kubectl exec -it mongodb-0 -- mongo -u root -p <password>
db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
```
----

. Once you receive `{ "ok" : 1 }`, you have successfully upgraded your MongoDB to 4.4.15.

[#upgrade-mongodb-to-7.0]
== Upgrade MongoDB to 7.0

[#prerequisites-7.0]
=== Prerequisites

* You have completed the `4.4.15` upgrade above.
* Ensure backups have been taken. You need a backup of MongoDB to restore in case anything goes wrong during the upgrade progress.
* You are able to modify your `values.yaml` file.
* `helm upgrade` works from your system to upgrade the cluster.
* Your MongoDB root password is available.

[#script-upgrade-7.0]
=== Scripted upgrade
We have created a shell script that you can use to upgrade your cluster's MongoDB instance link:https://github.com/CircleCI-Public/server-scripts/tree/main/upgrade-mongo-to-7.0[here].

Alternatively, you can use the following instructions to manually upgrade your cluster's MongoDB:

[#manual-upgrade-7.0]
=== Manual upgrade

==== 1. Upgrade from MongoDB 4.4 to 5.0

. Your `values.yaml` should contain the following snippet:
+
[source,yaml]
----
mongodb:
image:
tag: 4.4.15-debian-10-r8
----
+
To begin the upgrade process, change the tag to `5.0.24-debian-11-r20` and update the probes to use `mongosh`:
+
[source,yaml]
----
mongodb:
image:
tag: 5.0.24-debian-11-r20
livenessProbe:
enabled: false
readinessProbe:
enabled: false
customLivenessProbe:
exec:
command:
- mongosh
- --eval
- "db.adminCommand('ping')"
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 6
customReadinessProbe:
exec:
command:
- bash
- -ec
- |
mongosh --eval 'db.hello().isWritablePrimary || db.hello().secondary' | grep -q 'true'
initialDelaySeconds: 5
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 6
----

. Run `helm upgrade` to update your installation.

. Once the `helm upgrade` has completed and MongoDB has rolled, you will need to `exec` into the pod (with the root password handy) to modify the compatibility version. Note that MongoDB 5.0+ uses `mongosh` instead of `mongo`. (Be sure to replace `<password>` with your MongoDB root password.)
+
[source,console]
----
$ kubectl exec -it mongodb-0 -- mongosh -u root -p <password>
db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
----

. You should get an `{ "ok" : 1 }` response from MongoDB. Exit out of the MongoDB shell and pod.

==== 2. Upgrade from MongoDB 5.0 to 6.0

. Change the tag to `6.0.13-debian-11-r21` while being sure to keep the new `customLivenessProbe` and `customReadinessProbe` parameters.:
+
[source,yaml]
----
mongodb:
image:
tag: 6.0.13-debian-11-r21
----

. Run `helm upgrade` to update your installation.

. Once the `helm upgrade` has completed and MongoDB has rolled, you will need to `exec` into the pod (with the root password handy) to modify the compatibility version. (Be sure to replace `<password>` with your MongoDB root password.)
+
[source,console]
----
$ kubectl exec -it mongodb-0 -- mongosh -u root -p <password>
db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
----

. You should get `{ "ok" : 1 }`` again. Exit out of the shell and pod.

==== 3. Upgrade from MongoDB 6.0 to 7.0

. Change the tag to `7.0.15-debian-12-r2`:
+
[source,yaml]
----
mongodb:
image:
tag: 7.0.15-debian-12-r2
----

. Run `helm upgrade` to update your installation.

. Once the `helm upgrade` has completed and MongoDB has rolled, you will need to `exec` into the pod (with the root password handy) to modify the compatibility version (be sure to replace `<password>` with your MongoDB root password.)
+
CAUTION: MongoDB 7.0+ upgrade is one-way and cannot be downgraded.
+
NOTE: MongoDB 7.0+ requires the `confirm: true` parameter.
+
[source,console]
----
$ kubectl exec -it mongodb-0 -- mongosh -u root -p <password>
db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } )
----

. Once you receive `{ "ok" : 1 }``, you have successfully upgraded your MongoDB to 7.0.15.