How to refresh a single cluster¶
This guide covers refresh for single cluster MySQL deployments. To refresh a multi-cluster deployment, see How to refresh a multi-cluster deployment first.
Important information¶
Check if your current Juju version is compatible with the new charm version.
For information about charm versions, see Release notes.
To upgrade Juju, see How to upgrade Juju for a new database revision
Create and test a backup of your data before running any type of refresh. See How to create a backup.
It is recommended to integrate your application with Charmed MySQL Router . This will ensure minimal service disruption, if any.
Step 1: Record revision information¶
Note
This step is only valid when deploying from Charmhub .
If a local charm is deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the .charm file is available BEFORE going further. You might need it for a rollback.
The first step is to record the revision of the running application as a safety measure for a rollback action. To accomplish this, run the juju status command and look for the deployed Charmed MySQL revision in the command output.
Example output for Charmed MySQL on a machine controller:
Model Controller Cloud/Region Version SLA Timestamp
example lxd localhost/localhost 3.6.14 unsupported 17:58:37Z
App Version Status Scale Charm Channel Rev Exposed Message
mysql 8.4.7 active 3 mysql XXX no
Unit Workload Agent Machine Public address Ports Message
mysql/9 active idle 13 10.169.158.70 3306/tcp,33060/tcp
mysql/10* active idle 11 10.169.158.14 3306/tcp,33060/tcp Primary
mysql/11 active idle 12 10.169.158.217 3306/tcp,33060/tcp
Machine State Address Inst id Series AZ Message
11 started 10.169.158.14 juju-b72e25-11 ubuntu@26.04 Running
12 started 10.169.158.217 juju-b72e25-12 ubuntu@26.04 Running
13 started 10.169.158.70 juju-b72e25-13 ubuntu@26.04 Running
For this example, the current revision is XXX. Store it safely to use in case of rollback!
Step 2: Scale up¶
It is mandatory to have at least 3 units of MySQL before refreshing. This ensures that the MySQL cluster can refresh regardless of whether a MySQL Router application is connected, as the quorum criteria within the cluster varies based on this condition.
In case of failure, having extra units will ease a future rollback procedure without disrupting service. To scale up the application:
juju add-unit mysql --num-units <amount of units to add>
juju scale-application mysql-k8s <total number of units>
Wait for the new units to be ready.
Tip
It is recommended to use an odd number to prevent a split-brain scenario.
Step 3: Pre-upgrade check¶
Before refreshing, it is necessary to run the pre-refresh-check action against the leader unit:
juju run mysql/leader pre-refresh-check
The output of the action should look like:
unit-mysql-10:
...
results: {}
status: completed
...
juju run mysql-k8s/leader pre-refresh-check
The output of the action should look like:
unit-mysql-k8s-0:
UnitId: mysql-k8s/0
...
results: {}
status: completed
...
The action will configure the charm to minimize the amount of primary switchover, among other preparations for a safe refresh process. After successful execution, the charm is ready to be refreshed.
Step 4: Configure pause-after-unit-refresh¶
After each unit is refreshed, the charm will perform automatic health checks. We recommend supplementing the automatic checks with manual checks.
Examples of manual checks:
Database clients are healthy and can connect to the refreshed units
Transactions per second and resource consumption (CPU, memory, disk) are similar on refreshed and non-refreshed units
Leaving the application in a partially-refreshed state (only some units refreshed) for several weeks and monitoring that the new version is stable in your environment
To facilitate your manual checks, the application can be configured to pause the refresh and wait for your confirmation.
Set the pause-after-unit-refresh config option to:
allto wait for your confirmation after each unit refreshesfirst(default) to wait for your confirmation once, after the first unit refreshesnoneto never wait for your confirmation
For example:
juju config mysql pause-after-unit-refresh=all
juju config mysql-k8s pause-after-unit-refresh=all
Note
If the charm’s automatic health checks fail, the refresh will be paused (until those health checks succeed) regardless of the value of the pause-after-unit-refresh config option.
Step 5: Refresh¶
If you are refreshing multiple clusters, make sure to refresh the standby clusters first. See {ref}`refresh-multi-cluster for more information.
Use the juju refresh command to trigger the charm refresh process.
Example with channel selection:
juju refresh mysql --channel 8.4/edge
Example with specific revision selection:
juju refresh mysql --revision=YYY
Example with a local charm file:
juju refresh mysql --path ./mysql_ubuntu-26.04-amd64.charm
Example with channel selection:
juju refresh mysql-k8s --channel 8.4/edge --trust
Example with specific revision selection( do not forget the OCI resource):
juju refresh mysql-k8s --revision=YYY --resource mysql-image=... --trust
During an ongoing refresh
Do NOT perform any other extraordinary operations on the cluster, such as:
Adding or removing units
Creating or destroying new relations
Changes in workload configuration
Refreshing other connected/related/integrated applications simultaneously
Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
Do NOT trigger a rollback. Status changes during the process are expected (e.g. waiting, maintenance, active)
Make sure the refresh has failed/stopped and cannot be continued before triggering a rollback.
Once the refresh command is executed, all units will receive new charm content. The refresh will run on one unit at a time.
Example juju status during an refresh:
Model Controller Cloud/Region Version SLA Timestamp
example lxd localhost/localhost 3.6.14 unsupported 18:11:21Z
App Version Status Scale Charm Channel Rev Exposed Message
mysql 8.4.7 active 3 mysql no
Unit Workload Agent Machine Public address Ports Message
mysql/9 maintenance executing 13 10.169.158.70 3306/tcp,33060/tcp other units upgrading first...
mysql/10* waiting idle 11 10.169.158.14 3306/tcp,33060/tcp other units upgrading first...
mysql/11 maintenance idle 12 10.169.158.217 3306/tcp,33060/tcp upgrading unit
Machine State Address Inst id Series AZ Message
11 started 10.169.158.14 juju-b72e25-11 jammy Running
12 started 10.169.158.217 juju-b72e25-12 jammy Running
13 started 10.169.158.70 juju-b72e25-13 jammy Running
Example juju status during an refresh:
Model Controller Cloud/Region Version SLA Timestamp
example k8s microk8s/localhost 3.6.14 unsupported 01:20:47Z
App Version Status Scale Charm Channel Rev Address Exposed Message
mysql-k8s 8.4.7 waiting 3 mysql-k8s 8.4/edge 10.152.183.102 no waiting for units to settle down
Unit Workload Agent Address Ports Message
mysql-k8s/0* active idle 10.1.148.184 other units upgrading first...
mysql-k8s/1 maintenance executing 10.1.148.138 other units upgrading first...
mysql-k8s/2 active idle 10.1.148.143 other units upgrading first...
mysql-k8s/3 active idle 10.1.148.145 upgrading unit
Please be patient during huge installations. Each unit should recover shortly after the refresh, but time can vary depending on the amount of data written to the cluster while the unit was not part of it.
Incompatible charm revisions or dependencies will halt the process.
After a juju refresh, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the refresh process, the refresh will be halted and enter a failure state.
Step 6: Resume¶
If the pause-after-unit-refresh config option is set to all or first (default), your confirmation will be needed during the refresh.
After every unit, or just the first unit is refreshed, the charm will require to manually resume the process by running the resume-refresh action:
Target the next unit:
juju run mysql/X resume-refresh
Target the leader unit:
juju run mysql-k8s/leader resume-refresh
resume-refresh will roll out the refresh for the following unit, always from the highest ordinal number to the lowest. For each successful refreshed unit, the process will roll out the next automatically.
Step 7: Roll back¶
If there was an issue with the refresh, even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to the previous revision.
The update can be attempted again after a further inspection of the failure.
Step 8: Check cluster health¶
Use juju status to make sure the cluster state is OK.