How to perform a minor upgrade on a replica set
To upgrade to a major version, please perform a cluster migration via backup
Note: This feature is only available on specific revisions in Charmed MongoDB K8s 6/stable
, listed here.
If you wish to upgrade to/from a different revision, then 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
- 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}'
If your current revision is not in the list of available revisions to upgrade to, then you must perform a cluster migration via backup
In the case that your upgrade is not successful, you will need this revision number to roll back 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
Do not proceed if this action is not successful
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:
- Successful upgrade - where the new Charm uses the same underlying snap
- Successful upgrade - where the new Charm uses a new underlying snap
- 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-k8s active 3 mongodb-k8s no
Unit Workload Agent Machine Public address Ports Message
mongodb-k8s/0* active idle 0 10.84.191.38 27017/tcp
mongodb-k8s/1 active idle 1 10.84.191.252 27017/tcp
mongodb-k8s/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 [email protected] Running
1 started 10.84.191.252 juju-9ac398-1 [email protected] Running
2 started 10.84.191.189 juju-9ac398-2 [email protected] 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:
juju status | grep mongo -m 1
containsRefreshing. Verify highest unit is healthy & run
resume-refreshaction. To rollback,
juju refreshto last revision
juju status | grep mongo | awk 'END{print $2 " " $3}'
outputsactive 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 :
- Recommended: Wait for 5-10 minutes to see if the cluster can heal itself
- Recommended: Rollback. To roll back complete Steps 3-6 using the revision number from Step 1.
- 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-k8s/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 K8s 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.
It is not recommended to force an upgrade using force-refresh-start
. Please note that this can break your database.