How to perform a minor upgrade on a replica set

To upgrade to a major version, please perform a cluster migration via backup.

Minor upgrade steps

Here is a summary of the steps to perform a minor upgrade:

• Step 1. Determine your current revision
• Step 2. Determine new revision
• Step 3. Run a pre-refresh check
• Step 4. Begin upgrade
  • Case 1. Successful upgrade (same underlying snap)
  • Case 2: Successful upgrade (new underlying snap)
  • Case 3: Failure to upgrade
• Step 5. Continue upgrade
• Step 6.Verify success of upgrade

Step 1: Determine your current revision

Find determine your current revision:

juju status | grep <juju-app-name> | head -1 | awk '{print $5}'

This will not be used in the remainder of this How-To. But in the case that your upgrade is unsuccessful you will need this revision number to rollback your application.

Step 2: Determine new revision

Choose a revision to upgrade to from the list of available revisions to upgrade to

Step 3: Run a pre-upgrade check

Before refresh, the charm needs to perform some preparatory tasks to define the refresh plan. Run the pre-refresh-check action against the leader unit:

juju <juju-app-name>/leader pre-refresh-check 

Step 4: Begin upgrade

Using the revision from Step 2, upgrade your application

juju refresh <juju-app-name> --revision=<revision number>

It may take a minute before the charm receives the refresh command, when it does the units will begin to execute the command. Wait until juju status --watch 1s shows that all units in your deployment are idle.

Refreshing the charm upgrades the charm and services inside the charm. During which there are three possible outcomes:

1. Successful upgrade - where the new Charm uses the same underlying snap
2. Successful upgrade - where the new Charm uses a new underlying snap
3. Failure to upgrade

Case 1. Successful upgrade (same underlying snap)

In this case, the upgrade succeeded and all units finished upgrading automatically. If this is the case, your model will show that the charm successfully upgraded and juju status will show:

App      Version  Status  Scale  Charm    Channel  Rev  Exposed  Message
mongodb           active      3  mongodb             2  no

Unit        Workload  Agent  Machine  Public address  Ports      Message
mongodb/0*  active    idle   0        10.84.191.38    27017/tcp
mongodb/1   active    idle   1        10.84.191.252   27017/tcp
mongodb/2   active    idle   2        10.84.191.189   27017/tcp

Machine  State    Address        Inst id        Base          AZ  Message
0        started  10.84.191.38   juju-9ac398-0  ubuntu@22.04      Running
1        started  10.84.191.252  juju-9ac398-1  ubuntu@22.04      Running
2        started  10.84.191.189  juju-9ac398-2  ubuntu@22.04      Running

If this is the case, proceed directly to Step 6

Case 2: Successful upgrade (new underlying snap)

In this case, the charm only upgrades the first unit and waits for you to proceed with the upgrade

Your model will show that the first unit has successfully upgraded and you will see that:

1. juju status | grep mongo -m 1 contains Refreshing. Verify highest unit is healthy & run resume-refreshaction. To rollback,juju refresh to last revision
2. juju status | grep mongo | awk 'END{print $2 " " $3}' outputs active idle

If this is the case proceed to Step 5

Case 3: Failure to upgrade

If your upgrade failed, then juju status will show that the unit is blocked with the message Unhealthy after refresh. If the upgrade of the first unit failed, you can :

1. Recommended: Wait for 5-10 minutes to see if the cluster can heal itself
2. Recommended: Rollback. To rollback complete Steps 3-6 using the revision number from Step 1.
3. Not Recommended: Force an upgrade by running juju run mongodb/leader force-refresh-start. Please note this can break your database and is not recommended?

Step 5: Continue upgrade

Before continuing the upgrade, verify that your deployment is healthy. The charm performs a simple health check after upgrading the unit, but it is suggested that the user verifies that the database is indeed healthy.

Once you have done this, you may continue the upgrade process. To proceed with the upgrade run the resume-refresh action on the leader of the deployment:

juju mongodb/leader resume-refresh

Step 6: Verify success of the upgrade

Wait until juju status --watch 1s shows all units in the active status. If all nodes in your Charm MongoDB deployment are active your upgrade was successful.

If your upgrade failed, you should see the charm go into the blocked state with the message Unhealthy after refresh. . If the upgrade failed, you can :

• Recommended: Wait for 5-10 minutes to see if the cluster can heal itself
• Recommended: Rollback. To rollback complete Steps 3-6 using the revision number from Step 1.