How to perform a minor upgrade¶
Example: MySQL Router 8.0.33 -> MySQL Router 8.0.34 (including simple charm revision bump: from revision 99 to revision 102)
Charmed MySQL Router should be should be upgraded before Charmed MySQL.
Make sure to have a Charmed MySQL backup of your data when running any type of upgrades.
We strongly recommend to NOT perform any other extraordinary operations on Charmed MySQL cluster and/or MySQL Router, while upgrading.
As examples, these may be (but not limited to) the following:
Adding or removing units
Creating or destroying new relations
Changes in workload configuration
Upgrading other connected/related/integrated applications simultaneously
Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
Minor upgrade steps (K8s only)¶
Note
Upgrade instructions for the VM charm are a work in progress.
In the meantime, contact us via our public Matrix channel for help.
To summarize:
Collect all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do NOT skip this step.
(optional) Scale up: The new
sacrificialunit will be the first one to be updated, and it will simplify the rollback procedure in case of the upgrade failure.Prepare “Charmed MySQL K8s” Juju application for the in-place upgrade. See the step description below for all technical details executed by charm here.
Upgrade: Once started, only one unit of the app will be upgraded. In case of failure, roll back with
juju refresh.Resume upgrade: If the new unit is OK after the refresh, the upgrade can be resumed. All units in an app will be executed sequentially from highest to lowest unit number.
(optional) Consider rolling back in case of disaster. Please inform and include us in your case scenario troubleshooting to trace the source of the issue and prevent it in the future.
(optional) Scale back: Remove no longer necessary K8s units created in step 2 (if any).
Post-upgrade check: Make sure all units are in the proper state and the cluster is healthy.
Step 1: Collect¶
Note
This step is only valid when deploying from charmhub. If the deployment is of a local charm (revision is small, e.g. 0-10), make sure you save a copy of the current .charm file BEFORE going further. You might need it for rollback.
The first step is to record the revision of the running application, as a safety measure for a rollback action. Run the juju status command and look for the deployed Charmed MySQL and MySQL Router revisions in the command output, e.g.:
Model Controller Cloud/Region Version SLA Timestamp
upgrade microk8s microk8s/localhost 3.1.6 unsupported 15:32:04+02:00
App Version Status Scale Charm Channel Rev Address Exposed Message
mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-k8s 8.0/stable 99 10.152.183.238 no
mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-router-k8s 8.0/stable 69 10.152.183.184 no
mysql-test-app 0.0.2 active 1 mysql-test-app stable 26 10.152.183.36 no
Unit Workload Agent Address Ports Message
mysql-k8s/0* active idle 10.1.12.24 Primary
mysql-k8s/1 active idle 10.1.12.36
mysql-k8s/2 active idle 10.1.12.22
mysql-router-k8s/0 active idle 10.1.12.28
mysql-router-k8s/1 active idle 10.1.12.10
mysql-router-k8s/2* active idle 10.1.12.5
mysql-test-app/0* active idle 10.1.12.57
For this example, the current revision is 99 for MySQL K8s and 69 for Router. Store it safely to use in case of rollback!
Step 2: Scale-up (optional)¶
Optionally, it is recommended to scale the application up by one unit before starting the upgrade process.
The new unit will be the first one to be updated, and it will assert that the upgrade is possible. In case of failure, having the extra unit will ease the rollback procedure, without disrupting service.
juju scale-application mysql-k8s <current_units_count+1>
juju scale-application mysql-router-k8s <current_units_count+1>
Wait for the new unit up and ready.
Step 3: Prepare¶
After the application has settled, it’s necessary to run the pre-refresh-check action against the leader unit (for the MySQL Server only):
juju run mysql-k8s/leader pre-refresh-check
The action will configure the charm to minimize the amount of primary switchover, among other preparations for the upgrade process. After successful execution, charms are ready to be upgraded.
Step 4: Upgrade¶
Use the juju refresh command to trigger the charm upgrade process. If using juju version 3 or higher, it is necessary to add the --trust option.
# example with channel selection and juju 2.9.x
juju refresh mysql-router-k8s --channel 8.0/stable
# example with channel selection and juju 3.x
juju refresh mysql-router-k8s --channel 8.0/stable --trust
# example with specific revision selection (do NOT miss OCI resource!)
juju refresh mysql-router-k8s --revision=89 --resource mysql-router-image=...
After the Router upgrade is completed, upgrade the Server:
# example with channel selection and juju 2.9.x
juju refresh mysql-k8s --channel 8.0/stable
# example with channel selection and juju 3.x
juju refresh mysql-k8s --channel 8.0/stable --trust
# example with specific revision selection
juju refresh mysql-k8s --revision=89
The MySQL Server upgrade will execute only on the highest ordinal unit.
The unit should recover shortly after, but the time can vary depending on the amount of data written to the cluster while the unit was not part of the cluster. Please be patient on huge installations.
Step 5: Resume¶
After the unit is upgraded, the charm will set the unit upgrade state as completed. If deemed necessary, the user can further assert the success of the upgrade. If the unit is healthy within the cluster, the next step is to resume the upgrade process by running:
juju run mysql-k8s/leader resume-upgrade
Juju 2.9 users
Remember to use juju run-action <action name> --wait instead of juju run <action name>.
See also: Breaking changes between Juju 2.9 and 3
The resume-upgrade will roll out the Server upgrade for the following unit, always from highest from lowest. For each successfully upgraded unit beyond the first, the process will roll out the next one automatically.
Model Controller Cloud/Region Version SLA Timestamp
upgrade microk8s microk8s/localhost 3.1.6 unsupported 15:56:25+02:00
App Version Status Scale Charm Channel Rev Address Exposed Message
mysql-k8s 8.0.34-0ubuntu0.22.04.1 waiting 3/4 mysql-k8s 8.0/edge 109 10.152.183.238 no installing agent
mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 4 mysql-router-k8s 8.0/edge 69 10.152.183.184 no
mysql-test-app 0.0.2 active 1 mysql-test-app stable 26 10.152.183.36 no
Unit Workload Agent Address Ports Message
mysql-k8s/0* waiting idle 10.1.12.24 other units upgrading first...
mysql-k8s/1 unknown lost 10.1.12.36 agent lost, see 'juju show-status-log mysql-k8s/1'
mysql-k8s/2 maintenance idle 10.1.12.14 upgrade completed
mysql-k8s/3 maintenance idle 10.1.12.32 upgrade completed
mysql-router-k8s/0 active idle 10.1.12.28
mysql-router-k8s/1 active idle 10.1.12.10
mysql-router-k8s/2* active idle 10.1.12.5
mysql-router-k8s/3 active idle 10.1.12.9
mysql-test-app/0* active idle 10.1.12.57
Step 6: Rollback (optional)¶
If the upgrade was incompatible, it’s important to roll back the charm to a previous revision so that an update can be later attempted after a further inspection of the failure. See How to perform a minor rollback.
Step 7: Scale-back¶
Case the application scale was changed for the upgrade procedure, it is now safe to scale it back to the desired unit count:
juju scale-application mysql-k8s <unit_count>
juju scale-application mysql-router-k8s <unit_count>
Use juju status to check the cluster state.