From 7f190d2e498a29e1e0ee6eccc4ce21faa282bea1 Mon Sep 17 00:00:00 2001 From: imlogang <37604784+imlogang@users.noreply.github.com> Date: Wed, 19 Nov 2025 11:32:19 -0600 Subject: [PATCH 1/3] Add docs on how to go from 4.4 to 7.0 --- .../modules/operator/pages/upgrade-mongo.adoc | 131 +++++++++++++++++- 1 file changed, 126 insertions(+), 5 deletions(-) diff --git a/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc b/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc index 254e09efde..16ee7526b4 100644 --- a/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc +++ b/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc @@ -1,13 +1,16 @@ = 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] +[#upgrade-mongodb-to-4.4] +== Upgrade MongoDB to 4.4 + +[#prerequisites-4.4] == Prerequisites * Ensure backups have been taken. You will need a backup of MongoDB to restore to in case anything goes wrong during the upgrade progress @@ -15,12 +18,12 @@ MongoDB `3.6.22` is shipped with CircleCI server 4.9. * `helm upgrade` will work from your system to upgrade the cluster * MongoDB root password is available -[#script-upgrade] +[#script-upgrade-4.4] == 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 -[#manual-upgrade] +[#manual-upgrade-4.4] == Manual upgrade === 1. Upgrade from MongoDB 3.6 to 4.0 @@ -93,3 +96,121 @@ 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 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 + +[#script-upgrade-7.0] +== 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-7.0[here]. +If you wish, you may 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: ++ +```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`: ++ +```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 `` with your MongoDB root password.) ++ +```bash +kubectl exec -it mongodb-0 -- mongosh -u root -p +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.: ++ +```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 `` with your MongoDB root password.) ++ +```bash +kubectl exec -it mongodb-0 -- mongosh -u root -p +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`: ++ +```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. **Important: MongoDB 7.0+ upgrade is one-way and cannot be downgraded.** Note that MongoDB 7.0+ requires the `confirm: true` parameter. (Be sure to replace `` with your MongoDB root password.) ++ +```bash +kubectl exec -it mongodb-0 -- mongosh -u root -p +db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } ) +``` + +. Once you receive `ok: 1`, you have successfully upgraded your MongoDB to 7.0.15. From 7cb51144d7b9453996cb682a5bcad3eebc7b1a18 Mon Sep 17 00:00:00 2001 From: rosie yohannan Date: Thu, 20 Nov 2025 11:09:08 +0000 Subject: [PATCH 2/3] style and formatting --- .../modules/operator/pages/upgrade-mongo.adoc | 138 ++++++++++-------- 1 file changed, 79 insertions(+), 59 deletions(-) diff --git a/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc b/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc index 16ee7526b4..1062cb29c8 100644 --- a/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc +++ b/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc @@ -11,89 +11,97 @@ MongoDB `3.6.22` is shipped with CircleCI server 4.9. == Upgrade MongoDB to 4.4 [#prerequisites-4.4] -== Prerequisites +=== Prerequisites -* 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 +* 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-4.4] -== 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 +=== 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]. + +Alternatively, you can use the following instructions to manually upgrade your cluster's MongoDB: [#manual-upgrade-4.4] -== Manual upgrade +=== Manual upgrade -=== 1. Upgrade from MongoDB 3.6 to 4.0 +==== 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 `` with your MongoDB root password.) + -```bash -kubectl exec -it mongodb-0 -- mongo -u root -p +[source,console] +---- +$ kubectl exec -it mongodb-0 -- mongo -u root -p 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 `` with your MongoDB root password.) + -```bash -kubectl exec -it mongodb-0 -- mongo -u root -p +[source,console] +---- +$ kubectl exec -it mongodb-0 -- mongo -u root -p 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 `` with your MongoDB root password.) + -```bash -kubectl exec -it mongodb-0 -- mongo -u root -p +[source,console] +---- +$ kubectl exec -it mongodb-0 -- mongo -u root -p db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } ) -``` +---- . Once you receive `{ "ok" : 1 }`, you have successfully upgraded your MongoDB to 4.4.15. @@ -101,35 +109,38 @@ db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } ) == Upgrade MongoDB to 7.0 [#prerequisites-7.0] -== Prerequisites +=== Prerequisites * You have completed the `4.4.15` upgrade above. -* 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 +* 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 which may be used to upgrade your cluster's MongoDB instance link:https://github.com/CircleCI-Public/server-scripts/tree/main/upgrade-mongo-to-7.0[here]. -If you wish, you may use the following instructions to manually upgrade your cluster's MongoDB +=== 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 +=== Manual upgrade -=== 1. Upgrade from MongoDB 4.4 to 5.0 +==== 1. Upgrade from MongoDB 4.4 to 5.0 . Your `values.yaml` should contain the following snippet: + -```yaml +[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`: + -```yaml +[source,yaml] +---- mongodb: image: tag: 5.0.24-debian-11-r20 @@ -160,57 +171,66 @@ mongodb: 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 `` with your MongoDB root password.) + -```bash -kubectl exec -it mongodb-0 -- mongosh -u root -p +[source,console] +---- +$ kubectl exec -it mongodb-0 -- mongosh -u root -p 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 +==== 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.: + -```yaml +[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 `` with your MongoDB root password.) + -```bash -kubectl exec -it mongodb-0 -- mongosh -u root -p +[source,console] +---- +$ kubectl exec -it mongodb-0 -- mongosh -u root -p 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 +==== 3. Upgrade from MongoDB 6.0 to 7.0 . Change the tag to `7.0.15-debian-12-r2`: + -```yaml +[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. **Important: MongoDB 7.0+ upgrade is one-way and cannot be downgraded.** Note that MongoDB 7.0+ requires the `confirm: true` parameter. (Be sure to replace `` with your MongoDB root password.) +. 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 `` 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. + -```bash -kubectl exec -it mongodb-0 -- mongosh -u root -p +[source,console] +---- +$ kubectl exec -it mongodb-0 -- mongosh -u root -p db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } ) -``` +---- . Once you receive `ok: 1`, you have successfully upgraded your MongoDB to 7.0.15. From 92838117db432f28f3a3c1ca19a2a2aea3373527 Mon Sep 17 00:00:00 2001 From: imlogang <37604784+imlogang@users.noreply.github.com> Date: Thu, 20 Nov 2025 09:19:38 -0600 Subject: [PATCH 3/3] Add curly brackets around manual response --- .../modules/operator/pages/upgrade-mongo.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc b/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc index 1062cb29c8..314030cb27 100644 --- a/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc +++ b/docs/server-admin-4.9/modules/operator/pages/upgrade-mongo.adoc @@ -183,7 +183,7 @@ $ kubectl exec -it mongodb-0 -- mongosh -u root -p db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } ) ---- -. You should get an `ok: 1` response from MongoDB. Exit out of the MongoDB shell and pod. +. 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 @@ -206,7 +206,7 @@ $ kubectl exec -it mongodb-0 -- mongosh -u root -p db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } ) ---- -. You should get `ok: 1` again. Exit out of the shell and pod. +. You should get `{ "ok" : 1 }`` again. Exit out of the shell and pod. ==== 3. Upgrade from MongoDB 6.0 to 7.0 @@ -233,4 +233,4 @@ $ kubectl exec -it mongodb-0 -- mongosh -u root -p db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } ) ---- -. Once you receive `ok: 1`, you have successfully upgraded your MongoDB to 7.0.15. +. Once you receive `{ "ok" : 1 }``, you have successfully upgraded your MongoDB to 7.0.15.