From 9d7acd1ec35873dff3791bf0d25d683f0c0befc0 Mon Sep 17 00:00:00 2001 From: andreia Date: Mon, 20 Oct 2025 16:51:16 +0200 Subject: [PATCH 1/4] Restructure refresh docs and add new multi-cluster guide --- docs/conf.py | 3 +- docs/explanation/juju.md | 2 +- docs/explanation/security/index.md | 2 +- docs/how-to/index.md | 4 +- docs/how-to/monitoring-cos/enable-tracing.md | 2 +- docs/how-to/refresh/index.md | 65 ++++++++++ docs/how-to/refresh/multi-cluster/index.md | 8 ++ .../multi-cluster/refresh-multi-cluster.md | 33 +++++ .../multi-cluster/roll-back-multi-cluster.md | 7 ++ docs/how-to/refresh/single-cluster/index.md | 8 ++ .../single-cluster/refresh-single-cluster.md} | 119 ++++++++++-------- .../roll-back-single-cluster.md} | 33 ++--- .../{upgrade => refresh}/upgrade-juju.md | 14 ++- docs/how-to/upgrade/index.md | 35 ------ docs/redirects.txt | 8 +- docs/reference/releases.md | 2 +- 16 files changed, 227 insertions(+), 118 deletions(-) create mode 100644 docs/how-to/refresh/index.md create mode 100644 docs/how-to/refresh/multi-cluster/index.md create mode 100644 docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md create mode 100644 docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md create mode 100644 docs/how-to/refresh/single-cluster/index.md rename docs/how-to/{upgrade/perform-a-minor-upgrade.md => refresh/single-cluster/refresh-single-cluster.md} (54%) rename docs/how-to/{upgrade/perform-a-minor-rollback.md => refresh/single-cluster/roll-back-single-cluster.md} (67%) rename docs/how-to/{upgrade => refresh}/upgrade-juju.md (96%) delete mode 100644 docs/how-to/upgrade/index.md diff --git a/docs/conf.py b/docs/conf.py index 182db94c7b..1565419100 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -232,7 +232,8 @@ "https://matrix.to/*", "https://portal.azure.com/*", "https://dev.mysql.com/*", - "https://www.mysql.com/*" + "https://www.mysql.com/*", + "https://www.terraform.io/*" ] # A regex list of URLs where anchors are ignored by 'make linkcheck' diff --git a/docs/explanation/juju.md b/docs/explanation/juju.md index ec81c45f93..72a7c17995 100644 --- a/docs/explanation/juju.md +++ b/docs/explanation/juju.md @@ -62,5 +62,5 @@ ERROR Charm feature requirements cannot be met: - charm requires feature "juju" (version >= 3.1.5) but model currently supports version 3.1.4 ``` -You must then [upgrade to the required Juju version](/how-to/upgrade/upgrade-juju) before proceeding with the charm upgrade. +You must then [upgrade to the required Juju version](/how-to/refresh/upgrade-juju) before proceeding with the charm upgrade. diff --git a/docs/explanation/security/index.md b/docs/explanation/security/index.md index 4fee714d20..bf83deef24 100644 --- a/docs/explanation/security/index.md +++ b/docs/explanation/security/index.md @@ -63,7 +63,7 @@ Charmed MySQL K8s and Charmed MySQL Router K8s run on top of the same rock (OCI- [Charmed MySQL K8s operator](https://github.com/canonical/mysql-k8s-operator) and [Charmed MySQL Router K8s operator](https://github.com/canonical/mysql-router-k8s-operator) install pinned versions of the rock to provide reproducible and secure environments. New versions (revisions) of charmed operators can be released to update the operator's code, workloads, or both. It is important to refresh the charm regularly to make sure the workload is as secure as possible. -For more information on upgrading Charmed MySQL K8s, see the [How to upgrade MySQL](/how-to/upgrade/index) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router-k8s/docs/h-upgrade) guides, as well as the [Releases](/reference/releases). +For more information on upgrading Charmed MySQL K8s, see the [How to upgrade MySQL](/how-to/refresh/index) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router-k8s/docs/h-upgrade) guides, as well as the [Releases](/reference/releases). ### Encryption diff --git a/docs/how-to/index.md b/docs/how-to/index.md index f2b43a4a51..88bf653920 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -47,13 +47,13 @@ Integrate with observability services like Grafana, Prometheus, and Tempo. Monitoring (COS) ``` -## Upgrades +## Refresh ( upgrade) ```{toctree} :titlesonly: :maxdepth: 2 -Upgrade +Refresh (upgrade) ``` ## Cross-regional (cluster-cluster) async replication diff --git a/docs/how-to/monitoring-cos/enable-tracing.md b/docs/how-to/monitoring-cos/enable-tracing.md index e0a566c226..68d6ed176f 100644 --- a/docs/how-to/monitoring-cos/enable-tracing.md +++ b/docs/how-to/monitoring-cos/enable-tracing.md @@ -9,7 +9,7 @@ This is feature is in development. It is **not recommended** for production envi ## Prerequisites * Charmed MySQL K8s revision 146 or higher - * See [](/how-to/upgrade/index) + * See [](/how-to/refresh/index) * `cos-lite` bundle deployed in a Kubernetes environment * See the [COS Microk8s tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) diff --git a/docs/how-to/refresh/index.md b/docs/how-to/refresh/index.md new file mode 100644 index 0000000000..c14e0ad93c --- /dev/null +++ b/docs/how-to/refresh/index.md @@ -0,0 +1,65 @@ +# Refresh (upgrade) + +This charm supports in-place upgrades to higher versions via Juju's [`refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details) command. + +## Supported refreshes + +```{eval-rst} ++------------+------------+----------+------------+ +| From | To | ++------------+------------+----------+------------+ +| Charm | MySQL | Charm | MySQL | +| revision | Version | revision | Version | ++============+============+==========+============+ +| XXX, XXX | ``8.0.41`` | | | ++------------+------------+----------+------------+ +| XXX, XXX | ``8.0.39`` | XXX, XXX | ``8.0.41`` | ++------------+------------+----------+------------+ +| XXX | ``8.0.36`` | XXX, XXX | ``8.0.41`` | +| | +----------+------------+ +| | | XXX, XXX | ``8.0.39`` | ++------------+------------+----------+------------+ +| XXX | ``8.0.34`` | None | | ++------------+------------+----------+------------+ +| XXX | ``8.0.32`` | XXX | ``8.0.36`` | +| | +----------+------------+ +| | | XXX | ``8.0.34`` | ++------------+------------+----------+------------+ +``` + +Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision xxx](https://github.com/canonical/mysql-operator/releases/tag/revxxx) **cannot** be upgraded using Juju's `refresh`. + +To upgrade from older versions to Revision xxx or higher, the data must be migrated manually. See: [](/how-to/development/migrate-data-via-backup-restore). + +### Juju version upgrade + +Before refreshing the charm, make sure to check the [](/reference/releases) page to see if there any requirements for the new revision, such as a Juju version upgrade. + +* [](/how-to/refresh/upgrade-juju) + +## Refresh guides + +To refresh a **single cluster**, see: + +* [](/how-to/refresh/single-cluster/refresh-single-cluster) +* [](/how-to/refresh/single-cluster/roll-back-single-cluster) + +To refresh a **multi-cluster** deployment, see + +* [](/how-to/refresh/multi-cluster/refresh-multi-cluster) +* [](/how-to/refresh/multi-cluster/roll-back-multi-cluster) + +```{toctree} +:titlesonly: +:maxdepth: 2 +:hidden: + +Single cluster +Multi-cluster +Upgrade Juju +``` + + + +[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303 +[check]: https://img.icons8.com/color/20/checkmark--v1.png \ No newline at end of file diff --git a/docs/how-to/refresh/multi-cluster/index.md b/docs/how-to/refresh/multi-cluster/index.md new file mode 100644 index 0000000000..d8b642acdc --- /dev/null +++ b/docs/how-to/refresh/multi-cluster/index.md @@ -0,0 +1,8 @@ +# Refresh a multi-cluster deployment + +```{toctree} +:titlesonly: + +Refresh +Roll back +``` \ No newline at end of file diff --git a/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md b/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md new file mode 100644 index 0000000000..bee3a8e9e0 --- /dev/null +++ b/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md @@ -0,0 +1,33 @@ +# How to refresh a multi-cluster deployment + +A MySQL multi-cluster deployment (also known as a cluster set) can be upgraded by performing a refresh of each cluster individually. + +This guide goes over the steps and important considerations before refreshing multiple MySQL clusters. + +## Determine cluster order + +To upgrade a multi-cluster deployment, each cluster must be refreshed one by one - starting with the standby clusters. + +**The primary cluster must be the last one to get refreshed.** + +This ensures that availability is not affected if there are any issues with the upgrade. Refreshing all the standbys first also minimizes the cost of the leader re-election process. + +To identify the primary cluster, run + +```shell +juju run mysql-k8s/ get-cluster-status cluster-set=true +``` + +## Refresh each cluster + +For each cluster, follow the instructions in [](/how-to/refresh/single-cluster/refresh-single-cluster). + +**Perform a health check before proceeding to the next cluster.** + +Use the [`get-cluster-status`](https://charmhub.io/mysql-k8s/actions#get-cluster-status) Juju action to check that everything is healthy after refreshing a cluster. + +## Roll back + +If something goes wrong, roll back the cluster. See: [](/how-to/refresh/single-cluster/roll-back-single-cluster) + + diff --git a/docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md b/docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md new file mode 100644 index 0000000000..525040342a --- /dev/null +++ b/docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md @@ -0,0 +1,7 @@ +# Roll back a multi-cluster deployment + +A multi-cluster rollback is the same as a single-cluster rollback, but repeated for each cluster that was fully or partially upgraded. + +```{include} ../single-cluster/roll-back-single-cluster.md + :start-after: "How to roll back a single cluster" +``` \ No newline at end of file diff --git a/docs/how-to/refresh/single-cluster/index.md b/docs/how-to/refresh/single-cluster/index.md new file mode 100644 index 0000000000..a33c11d90e --- /dev/null +++ b/docs/how-to/refresh/single-cluster/index.md @@ -0,0 +1,8 @@ +# Refresh a single cluster + +```{toctree} +:titlesonly: + +Refresh +Roll back +``` \ No newline at end of file diff --git a/docs/how-to/upgrade/perform-a-minor-upgrade.md b/docs/how-to/refresh/single-cluster/refresh-single-cluster.md similarity index 54% rename from docs/how-to/upgrade/perform-a-minor-upgrade.md rename to docs/how-to/refresh/single-cluster/refresh-single-cluster.md index 4d1f7a7198..b04e1aca31 100644 --- a/docs/how-to/upgrade/perform-a-minor-upgrade.md +++ b/docs/how-to/refresh/single-cluster/refresh-single-cluster.md @@ -1,42 +1,39 @@ -# Perform a minor upgrade +# How to refresh a single cluster -**Example**: MySQL 8.0.33 -> MySQL 8.0.34
-(including charm revision bump: e.g. Revision 193 -> Revision 196) +This guide covers refresh for single cluster MySQL deployments. To refresh a multi-cluster deployment, see [](/how-to/refresh/multi-cluster/refresh-multi-cluster) first. -This is part of the [Upgrade section](/how-to/upgrade/index). Refer to the landing page for more information and an overview of the content. +## Important information -We strongly recommend to **NOT** perform any other extraordinary operations on a Charmed MySQL K8s cluster, while upgrading. These may be (but not limited to) the following: +**Check if your current Juju version is compatible with the new charm version**. -1. Adding or removing units -2. Creating or destroying new relations -3. Changes in workload configuration -4. Upgrading other connected/related/integrated applications simultaneously +For information about charm versions, see [](/reference/releases). -The concurrency with other operations is not supported, and it can lead the cluster into inconsistent states. +To upgrade Juju, see [](/how-to/refresh/upgrade-juju). +**Create and test a backup of your data before running any type of refresh.** See [](/how-to/back-up-and-restore/create-a-backup). -**Note**: Make sure to have a backup of your data when running any type of upgrades! -See: [How to create a backup](/how-to/back-up-and-restore/create-a-backup) - -It is recommended to deploy your application in conjunction with [Charmed MySQL Router K8s](https://charmhub.io/mysql-router-k8s). This will ensure minimal service disruption, if any. +**It is recommended to integrate your application with [Charmed MySQL Router K8s](https://charmhub.io/mysql-router-k8s).** This will ensure minimal service disruption, if any. ## Summary of the upgrade steps -1. [**Collect**](#step-1-collect) all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do not skip this step! -2. [**Scale-up** (optional)](#step-2-scale-up-optional). The new unit will be the first one to be updated, and it will simplify the rollback procedure a lot in case of the upgrade failure. -3. [**Prepare**](#step-3-prepare) the Charmed MySQL K8s application for the in-place upgrade. -4. [**Upgrade**](#step-4-upgrade). Once started, only one unit in a cluster will be upgraded. In case of failure, the rollback is simple: remove newly added pod (via [step 2](#step-2-scale-up-optional)). -5. [**Resume** upgrade](#step-5-resume). If the new pod is OK after the refresh, the upgrade can be resumed for all other units in the cluster. All units in a cluster will be executed sequentially from the largest ordinal number to the lowest. -6. Consider a [**rollback**](#step-6-rollback-optional) 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. [Contact us](/reference/contacts)! -7. [**Scale-back** (optional)](#step-7-scale-back). Remove no longer necessary K8s pod created in step 2 (if any). -8. [Post-upgrade **check**](#step-8-check). Make sure all units are in a healthy state. +1. [**Collect**](step-1-collect) all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do not skip this step! +2. [**Scale-up** (optional)](step-2-scale-up-optional). The new unit will be the first one to be updated, and it will simplify the rollback procedure a lot in case of the upgrade failure. +3. [**Prepare**](step-3-prepare) the Charmed MySQL K8s application for the in-place upgrade. +4. [**Upgrade**](step-4-refresh). Once started, only one unit in a cluster will be upgraded. In case of failure, the rollback is simple: remove newly added pod (via [step 2](step-2-scale-up-optional)). +5. [**Resume** upgrade](step-5-resume). If the new pod is OK after the refresh, the upgrade can be resumed for all other units in the cluster. All units in a cluster will be executed sequentially from the largest ordinal number to the lowest. +6. Consider a [**rollback**](step-6-rollback-optional) 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. [Contact us](/reference/contacts)! +7. [**Scale-back** (optional)](step-7-scale-back). Remove no longer necessary K8s pod created in step 2 (if any). +8. [Post-upgrade **check**](step-8-check). Make sure all units are in a healthy state. -## Step 1: Collect +(step-1-collect)= +## Step 1: Collect -**Note**: This step is only valid when deploying from [charmhub](https://charmhub.io/). +```{note} +This step is only valid when deploying from [Charmhub](https://charmhub.io/mysql-k8s). If a [local charm](https://juju.is/docs/sdk/deploy-a-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 K8s revision in the command output, e.g: @@ -55,6 +52,7 @@ mysql-k8s/2 active idle 10.1.148.143 For this example, the current revision is `88`. Store it safely to use in case of rollback! +(step-2-scale-up-optional)= ## Step 2: Scale-up (optional) Optionally, it is recommended to scale the application up by one unit before starting the upgrade process. @@ -64,10 +62,12 @@ The new unit will be the first one to be updated, and it will assert that the up ```shell juju scale-application mysql-k8s ``` -> To scale up by 1 unit, `` would be the current number of units + 1 + +To scale up by 1 unit, `` would be the current number of units + 1 Wait for the new unit to be ready. +(step-3-prepare)= ## Step 3: Prepare After the application has settled, it’s necessary to run the `pre-upgrade-check` action against the leader unit: @@ -78,7 +78,7 @@ juju run mysql-k8s/leader pre-upgrade-check The output of the action should look like: -```shell +```yaml unit-mysql-k8s-0: UnitId: mysql-k8s/0 ... @@ -87,24 +87,46 @@ unit-mysql-k8s-0: ... ``` -The action will configure the charm to minimize the amount of primary switchover, among other preparations for the upgrade process. After successful execution, the charm is ready to be upgraded. +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: Upgrade +(step-4-refresh)= +## Step 4: Refresh + +If you are refreshing multiple clusters, make sure to refresh the standby clusters first. See [](/how-to/refresh/multi-cluster/refresh-multi-cluster) for more information. Use the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command to trigger the charm upgrade process. Example with channel selection + ```shell juju refresh mysql-k8s --channel 8.0/edge --trust ``` -Example with specific revision selection (do not forget the OCI resource) +Example with specific revision selection (do not forget the OCI resource): + ```shell juju refresh mysql-k8s --revision=89 --resource mysql-image=... --trust ``` The upgrade will execute only on the highest ordinal unit. +```{admonition} During an ongoing refresh +:class: warning + +**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. +``` + For the running example `mysql-k8s/2`, `juju status` would look similar to the output below: ```shell @@ -121,14 +143,13 @@ mysql-k8s/2 active idle 10.1.148.143 other units upgrading mysql-k8s/3 maintenance executing 10.1.148.145 upgrading unit ``` -**Do NOT trigger `rollback` procedure during the running `upgrade` procedure.** -It is expected to have some status changes during the process: `waiting`, `maintenance`, `active`. - -Make sure `upgrade` has failed/stopped and cannot be fixed/continued before triggering `rollback`! - **Please be patient during huge installations.** -Each unit should recover shortly after the upgrade, but time can vary depending on the amount of data written to the cluster while the unit was not part of it. +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-5-resume)= ## Step 5: Resume After the unit is upgraded, the charm will set the unit upgrade state as completed. @@ -155,39 +176,31 @@ mysql-k8s/2 active idle 10.1.148.143 mysql-k8s/3 active idle 10.1.148.145 ``` +(step-6-rollback-optional)= ## Step 6: Rollback (optional) -The step must be skipped if the upgrade went well! +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. -If there was an issue with the upgrade, even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to the previous revision. That way, the update can be attempted again after a further inspection of the failure. +The update can be attempted again after a further inspection of the failure. -> See: [How to perform a minor rollback](/how-to/upgrade/perform-a-minor-rollback) +See: [](/how-to/refresh/single-cluster/roll-back-single-cluster) +(step-7-scale-back)= ## 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: +If the application scale was changed for the upgrade procedure, it is now safe to scale it back to the desired unit count: ```shell juju scale-application mysql-k8s ``` -> To scale down by 1 unit, `` would be the current number of units - 1 + +To scale down by 1 unit, `` would be the current number of units - 1 Example: [![asciicast](https://asciinema.org/a/7ZMAsPWU3wv7ynZI1JvgRFG31.png)](https://asciinema.org/a/7ZMAsPWU3wv7ynZI1JvgRFG31) +(step-8-check)= ## Step 8: Check -Future improvements are [planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state of the pod/cluster on a low level. - -For now, use `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK. - - - +Use `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK. diff --git a/docs/how-to/upgrade/perform-a-minor-rollback.md b/docs/how-to/refresh/single-cluster/roll-back-single-cluster.md similarity index 67% rename from docs/how-to/upgrade/perform-a-minor-rollback.md rename to docs/how-to/refresh/single-cluster/roll-back-single-cluster.md index 1688b88bb8..c2443e86ab 100644 --- a/docs/how-to/upgrade/perform-a-minor-rollback.md +++ b/docs/how-to/refresh/single-cluster/roll-back-single-cluster.md @@ -1,17 +1,17 @@ -# Perform a minor rollback +# How to roll back a single cluster -**Example**: MySQL 8.0.34 -> MySQL 8.0.33
-(including charm revision bump: e.g Revision 43 -> Revision 42) +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 process will be halted and enter a failure state. -After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the process will be halted and enter a failure state. +Even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to a previous revision so that an update can be attempted after further inspection of the failure. -Even if the underlying MySQL cluster continue to work, it’s important to roll back the charm to a previous revision so that an update can be attempted after further inspection of the failure. - -```{caution} -**Warning:** Do NOT trigger `rollback` during the running `upgrade` action! It may cause an unpredictable MySQL cluster state! +```{warning} +Do NOT trigger `rollback` during a running `refresh` action! It may cause an unpredictable MySQL cluster state! ``` +This guide covers rollbacks for single cluster MySQL deployments. Before rolling back a **multi-cluster** refresh, see [](/how-to/refresh/multi-cluster/refresh-multi-cluster). + ## Summary of the rollback steps + 1. **Prepare** the Charmed MySQL K8s application for the in-place rollback. 2. **Rollback**. Perform the first charm rollback on the first unit only. The unit with the maximal ordinal will be chosen. 3. **Resume**. Continue rolling back the rest of the units if the first unit rolled back successfully. @@ -19,9 +19,10 @@ Even if the underlying MySQL cluster continue to work, it’s important to roll ## Step 1: Prepare -To execute a rollback, we use a similar procedure to the upgrade. The difference is the charm revision to upgrade to. In this guide's example, we will refresh the charm back to revision `88`. +To execute a rollback, we use a similar procedure to the refresh. The difference is the charm revision to refresh to. In this guide's example, we will refresh the charm back to revision `88`. + +It is necessary to re-run `pre-upgrade-check` action on the leader unit, to enter the refresh recovery state: -It is necessary to re-run `pre-upgrade-check` action on the leader unit, to enter the upgrade recovery state: ```shell juju run mysql-k8s/leader pre-upgrade-check ``` @@ -29,20 +30,25 @@ juju run mysql-k8s/leader pre-upgrade-check ## Step 2: Rollback When using charm from charmhub: + ```shell juju refresh mysql-k8s --revision=88 ``` When deploying from a local charm file, one must have the previous revision charm file and the `mysql-image` resource, then run: + ```shell juju refresh mysql-k8s --path= --resource mysql-image= ``` + For example: + ```shell juju refresh mysql-k8s --path=./mysql-k8s_ubuntu-22.04-amd64.charm \ --resource mysql-image=ghcr.io/canonical/charmed-mysql@sha256:753477ce39712221f008955b746fcf01a215785a215fe3de56f525380d14ad97 ``` -> where `mysql-k8s_ubuntu-22.04-amd64.charm` is the previous revision charm file. + +where `mysql-k8s_ubuntu-22.04-amd64.charm` is the previous revision charm file. The reference for the resource for a given revision can be found in the [`metadata.yaml`](https://github.com/canonical/mysql-k8s-operator/blob/e4beca6b34313a977eab5ab2c74fa43586f1154c/metadata.yaml) file in the charm's repository under the key `upstream-source`. @@ -51,6 +57,7 @@ The first unit will be rolled out and should rejoin the cluster after settling d ## Step 3: Resume To resume the upgrade on the remaining units use the `resume-upgrade` action: + ```shell juju run mysql-k8s/leader resume-upgrade ``` @@ -59,7 +66,5 @@ This will roll out the pods in the remaining units to the same charm revision. ## Step 4: Check -Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state on pods/clusters on a low level. - -For now, check `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK. +Check `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK. diff --git a/docs/how-to/upgrade/upgrade-juju.md b/docs/how-to/refresh/upgrade-juju.md similarity index 96% rename from docs/how-to/upgrade/upgrade-juju.md rename to docs/how-to/refresh/upgrade-juju.md index 1a3b562f9f..ff84127647 100644 --- a/docs/how-to/upgrade/upgrade-juju.md +++ b/docs/how-to/refresh/upgrade-juju.md @@ -1,3 +1,4 @@ +(upgrade-juju)= # Upgrade Juju for a new database revision This guide contains instructions to perform a patch or major/minor Juju upgrade to a controller and model containing a database charm. @@ -5,10 +6,10 @@ This guide contains instructions to perform a patch or major/minor Juju upgrade For more background about Juju upgrades in the context of database charms, check [Explanation > Juju > Juju upgrades](/explanation/juju). ## Patch version upgrade -A [PATCH](https://semver.org/#summary) Juju upgrade (e.g. Juju `3.1.5` → `3.1.8`) can be easily applied in-place. +A [PATCH](https://semver.org/#summary) Juju upgrade (e.g. Juju `3.1.5` → `3.1.8`) can be easily applied in-place. -```text +```shell sudo snap refresh juju juju upgrade-controller @@ -17,12 +18,14 @@ juju upgrade-controller juju upgrade-model # wait until complete ``` -Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade). +Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/refresh/single-cluster/refresh-single-cluster). ## Major/minor version upgrade + The easiest way to perform a [MAJOR/MINOR](https://semver.org/#summary) Juju version upgrade (e.g. Juju `3.1.8` → `3.5.1`), is to update the controller and model to the new version, then [migrate](https://juju.is/docs/juju/juju-migrate) the model. ### Commands summary + The following is a summary of commands that upgrade Juju to `3.5/stable`: ```text @@ -36,9 +39,10 @@ juju upgrade-model -m lxd_3.5.1:mydatabase # wait until complete ``` -Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade). +Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/refresh/single-cluster/refresh-single-cluster). ### Example + This section goes over the commands listed in the summary above with more details and sample outputs.
In this example scenario, we have mysql deployed in model mydatabase on the Juju controller lxd_3.1.8. @@ -169,7 +173,7 @@ mydatabase lxd_3.5.1 localhost/localhost 3.5.1 unsupported 22:59:01+02:0 At this stage, the application continues running under the supervision of the new controller version and is ready to be refreshed to the new charm revision. -You can now proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade). +You can now proceed with the [charm upgrade](/how-to/refresh/single-cluster/refresh-single-cluster). ## Resources Further documentation about Juju upgrades: diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md deleted file mode 100644 index fa82591a36..0000000000 --- a/docs/how-to/upgrade/index.md +++ /dev/null @@ -1,35 +0,0 @@ -# Upgrade - -This section contains documentation about performing upgrades (and rollbacks) on: -* [MySQL Server (workload)](#mysql-upgrades-workload) -* [Juju version](#juju-upgrades) - -## MySQL upgrades (workload) -There are two types of in-place workload upgrades: -* **Major upgrades** - E.g. MySQL `8.0` -> MySQL `9.0` - * *Not supported* -* **Minor upgrades** - E.g. MySQL `8.0.33` -> `8.0.34` (includes charm revision bump) - * See: [How to perform a minor upgrade](/how-to/upgrade/perform-a-minor-upgrade) - * See: [How to perform a minor rollback](/how-to/upgrade/perform-a-minor-rollback) - -```{caution} -This charm only supports in-place **minor** upgrades. - -To upgrade to a major MySQL version, one must install a new cluster separately and migrate the data from the old to the new installation. This documentation will be updated with the migration instructions when a new MySQL version becomes available. -``` - -## Juju upgrades - -New revisions of the charm may require that you do a major or minor Juju upgrade. - -See: [How to upgrade Juju](/how-to/upgrade/upgrade-juju) - -```{toctree} -:titlesonly: -:maxdepth: 2 -:hidden: - -Upgrade Juju -Perform a minor rollback -Perform a minor upgrade -``` diff --git a/docs/redirects.txt b/docs/redirects.txt index 95b1b1a820..93dddcf740 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -48,10 +48,10 @@ h-enable-monitoring/ how-to/monitoring-cos/enable-monitoring h-enable-alert-rules/ how-to/monitoring-cos/enable-alert-rules h-enable-tracing/ how-to/monitoring-cos/enable-tracing -h-upgrade/ how-to/upgrade/ -h-upgrade-juju/ how-to/upgrade/upgrade-juju -h-upgrade-minor/ how-to/upgrade/perform-a-minor-upgrade -h-rollback-minor/ how-to/upgrade/perform-a-minor-rollback +h-upgrade/ how-to/refresh/ +h-upgrade-juju/ how-to/refresh/upgrade-juju +h-upgrade-minor/ how-to/refresh/single-cluster/refresh-single-cluster +h-rollback-minor/ how-to/refresh/single-cluster/roll-back-single-cluster h-async/ how-to/cross-regional-async-replication/ h-async-deployment/ how-to/cross-regional-async-replication/deploy diff --git a/docs/reference/releases.md b/docs/reference/releases.md index 561ad728b6..112bf424ff 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -6,7 +6,7 @@ To learn more about the different release tracks and channels, see the [Juju doc To see all releases and commits, check the [Charmed MySQL K8s Releases page on GitHub](https://github.com/canonical/mysql-k8s-operator/releases). -| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/upgrade/perform-a-minor-upgrade) | [Cross-regional async replication](/how-to/cross-regional-async-replication/deploy) | [Point-in-time recovery](point-in-time-recovery) +| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/refresh/single-cluster/refresh-single-cluster) | [Cross-regional async replication](/how-to/cross-regional-async-replication/deploy) | [Point-in-time recovery](point-in-time-recovery) |:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | [254], [255] | 8.0.41 | `3.5.4+` | ![check] | ![check] | ![check] | ![check] | ![check] | | [240], [241] | 8.0.41 | `3.5.4+` | ![check] | ![check] | ![check] | ![check] | | From 2fee3c8e237cdfa604f80e55387bc4edf0c6918b Mon Sep 17 00:00:00 2001 From: andreia Date: Mon, 20 Oct 2025 16:59:22 +0200 Subject: [PATCH 2/4] rename cross-regional async replication to cluster-cluster --- .../clients.md | 4 +-- .../deploy.md | 17 +++-------- .../cluster-cluster-replication/index.md | 30 +++++++++++++++++++ .../recovery.md | 8 ++--- .../removal.md | 6 ++-- .../switchover-failover.md | 2 +- .../cross-regional-async-replication/index.md | 12 -------- docs/how-to/deploy/multi-az.md | 2 +- docs/how-to/index.md | 4 +-- docs/how-to/primary-switchover.md | 4 +-- docs/redirects.txt | 12 ++++---- docs/reference/releases.md | 2 +- 12 files changed, 56 insertions(+), 47 deletions(-) rename docs/how-to/{cross-regional-async-replication => cluster-cluster-replication}/clients.md (84%) rename docs/how-to/{cross-regional-async-replication => cluster-cluster-replication}/deploy.md (85%) create mode 100644 docs/how-to/cluster-cluster-replication/index.md rename docs/how-to/{cross-regional-async-replication => cluster-cluster-replication}/recovery.md (66%) rename docs/how-to/{cross-regional-async-replication => cluster-cluster-replication}/removal.md (79%) rename docs/how-to/{cross-regional-async-replication => cluster-cluster-replication}/switchover-failover.md (91%) delete mode 100644 docs/how-to/cross-regional-async-replication/index.md diff --git a/docs/how-to/cross-regional-async-replication/clients.md b/docs/how-to/cluster-cluster-replication/clients.md similarity index 84% rename from docs/how-to/cross-regional-async-replication/clients.md rename to docs/how-to/cluster-cluster-replication/clients.md index 8b147e62a8..4323704608 100644 --- a/docs/how-to/cross-regional-async-replication/clients.md +++ b/docs/how-to/cluster-cluster-replication/clients.md @@ -1,8 +1,8 @@ # Clients -## Pre-requisits +## Pre-requisites -Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)! +Make sure both `rome` and `lisbon` clusters are deployed according to [](/how-to/cluster-cluster-replication/deploy). ## Offer and consume database endpoints diff --git a/docs/how-to/cross-regional-async-replication/deploy.md b/docs/how-to/cluster-cluster-replication/deploy.md similarity index 85% rename from docs/how-to/cross-regional-async-replication/deploy.md rename to docs/how-to/cluster-cluster-replication/deploy.md index feb3cc1387..12fb003f41 100644 --- a/docs/how-to/cross-regional-async-replication/deploy.md +++ b/docs/how-to/cluster-cluster-replication/deploy.md @@ -1,16 +1,7 @@ -# Deploy async replication - -The following table shows the source and target controller/model combinations that are currently supported: - -| | AWS | GCP | Azure | -|---|---|:---:|:---:| -| AWS | ![ check ] | | | -| GCP | | ![ check ] | | -| Azure | | | ![ check ] | - -## Deploy +# Deploy Deploy two MySQL Clusters, named `Rome` and `Lisbon`: + ```shell juju add-model rome # 1st cluster location: Rome juju add-model lisbon # 2nd cluster location: Lisbon @@ -22,8 +13,8 @@ juju switch lisbon juju deploy mysql-k8s db2 --trust --channel=8.0/edge --config profile=testing --config cluster-name=lisbon --base ubuntu@22.04 ``` -```{note} -Remove profile configuration for production deployments. For more information, see our documentation about [Profiles](https://charmhub.io/mysql-k8s/docs/r-profiles). +```{caution} +Remove [profile](/reference/profiles) configuration for production deployments. ``` ## Offer diff --git a/docs/how-to/cluster-cluster-replication/index.md b/docs/how-to/cluster-cluster-replication/index.md new file mode 100644 index 0000000000..32e292be48 --- /dev/null +++ b/docs/how-to/cluster-cluster-replication/index.md @@ -0,0 +1,30 @@ +# Cluster-cluster replication + +Cluster-cluster asynchronous replication focuses on disaster recovery by distributing data across different servers. + +For increased safety, it is recommended to deploy each cluster in a different geographical region. + +## Substrate dependencies + +The following table shows the source and target controller/model combinations that are currently supported: + +| | AWS | GCP | Azure | +|-------|------------|:----------:|:----------:| +| AWS | ![ check ] | | | +| GCP | | ![ check ] | | +| Azure | | | ![ check ] | + +## Guides + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Deploy +Clients +Switchover/failover +Recovery +Removal +``` + +[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen \ No newline at end of file diff --git a/docs/how-to/cross-regional-async-replication/recovery.md b/docs/how-to/cluster-cluster-replication/recovery.md similarity index 66% rename from docs/how-to/cross-regional-async-replication/recovery.md rename to docs/how-to/cluster-cluster-replication/recovery.md index e1e168826f..9896ac6b47 100644 --- a/docs/how-to/cross-regional-async-replication/recovery.md +++ b/docs/how-to/cluster-cluster-replication/recovery.md @@ -2,19 +2,19 @@ ## Pre-requisites -Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cross-regional-async-replication/deploy). +Make sure both `Rome` and `Lisbon` clusters are deployed following the [cluster-cluster deployment guide](/how-to/cluster-cluster-replication/deploy). ## Recover detached cluster -If the relation between clusters was removed and one side went into detached/blocked state: simply relate async replication back to restore ClusterSet. +If the relation between clusters was removed and one side went into detached/blocked state: simply relate cluster-cluster replication back to restore ClusterSet. ## Recover lost cluster -If a cluster has been lost and the ClusterSet need new member: deploy new db application and init async replication. The data will be copied automatically and the new cluster will join ClusterSet. +If a cluster has been lost and the ClusterSet need new member: deploy new db application and init cluster-cluster replication. The data will be copied automatically and the new cluster will join ClusterSet. ## Recover invalidated cluster -A cluster in the cluster-set gets invalidated when async replication auto-recovery fails on a disconnection event or when a failover is run against another cluster-set member while this cluster is unreachable. +A cluster in the cluster-set gets invalidated when cluster-cluster replication auto-recovery fails on a disconnection event or when a failover is run against another cluster-set member while this cluster is unreachable. If the invalidated cluster connections is restored, it's status will be displayed in `juju status` as: diff --git a/docs/how-to/cross-regional-async-replication/removal.md b/docs/how-to/cluster-cluster-replication/removal.md similarity index 79% rename from docs/how-to/cross-regional-async-replication/removal.md rename to docs/how-to/cluster-cluster-replication/removal.md index fad0ae02e2..f118c94714 100644 --- a/docs/how-to/cross-regional-async-replication/removal.md +++ b/docs/how-to/cluster-cluster-replication/removal.md @@ -2,12 +2,12 @@ ## Pre-requisites -Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cross-regional-async-replication/deploy). +Make sure both `Rome` and `Lisbon` clusters are deployed following the [cluster-cluster deployment guide](/how-to/cluster-cluster-replication/deploy). ## Detach Cluster from ClusterSet ```{important} -It is important to [switchover](/how-to/cross-regional-async-replication/switchover-failover) the `Primary` cluster before detaching it from ClusterSet! +It is important to [switchover](/how-to/cluster-cluster-replication/switchover-failover) the `Primary` cluster before detaching it from ClusterSet! ``` Assuming the `Lisbon` is a current `Primary` and we want to detach `Rome` (for removal or reuse): @@ -24,7 +24,7 @@ From this points, there are three options, as described in the following section ## Rejoin detached cluster into previous ClusterSet -At this stage, the detached/blocked cluster `Rome` can re-join the previous ClusterSet by restoring async integration/relation: +At this stage, the detached/blocked cluster `Rome` can re-join the previous ClusterSet by restoring cluster-cluster integration/relation: ```shell juju switch rome diff --git a/docs/how-to/cross-regional-async-replication/switchover-failover.md b/docs/how-to/cluster-cluster-replication/switchover-failover.md similarity index 91% rename from docs/how-to/cross-regional-async-replication/switchover-failover.md rename to docs/how-to/cluster-cluster-replication/switchover-failover.md index ed65cd15cb..4e6ff3333e 100644 --- a/docs/how-to/cross-regional-async-replication/switchover-failover.md +++ b/docs/how-to/cluster-cluster-replication/switchover-failover.md @@ -2,7 +2,7 @@ ## Pre-requisites -Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)! +Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cluster-cluster-replication/deploy)! ## Switchover (safe) diff --git a/docs/how-to/cross-regional-async-replication/index.md b/docs/how-to/cross-regional-async-replication/index.md deleted file mode 100644 index 8048c4905f..0000000000 --- a/docs/how-to/cross-regional-async-replication/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Cross-regional asynchronous replication - -```{toctree} -:titlesonly: -:maxdepth: 2 - -Deploy -Clients -Switchover/failover -Recovery -Removal -``` diff --git a/docs/how-to/deploy/multi-az.md b/docs/how-to/deploy/multi-az.md index 67d36df103..2d24bd1e1e 100644 --- a/docs/how-to/deploy/multi-az.md +++ b/docs/how-to/deploy/multi-az.md @@ -256,7 +256,7 @@ mydatabase/2 active idle 10.80.1.6 At this point we can relax and enjoy the protection from Cloud Availability zones! -To survive acomplete cloud outage, we recommend setting up [cluster-cluster asynchronous replication](/how-to/cross-regional-async-replication/deploy). +To survive acomplete cloud outage, we recommend setting up [cluster-cluster asynchronous replication](/how-to/cluster-cluster-replication/deploy). ## Remove GKE setup diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 88bf653920..2cdaf34ea8 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -56,13 +56,13 @@ Monitoring (COS) Refresh (upgrade) ``` -## Cross-regional (cluster-cluster) async replication +## Cluster-cluster replication ```{toctree} :titlesonly: :maxdepth: 2 -Cross-regional async replication +Cluster-cluster replication ``` ## Development diff --git a/docs/how-to/primary-switchover.md b/docs/how-to/primary-switchover.md index 0d577c8a26..ae4aa47266 100644 --- a/docs/how-to/primary-switchover.md +++ b/docs/how-to/primary-switchover.md @@ -15,6 +15,6 @@ In this example, the unit `mysql/1` will become the new primary. The previous pr secondary. ```{caution} -The `promote-to-primary` action can be used in cluster scope, when using async replication. -Check [Switchover / Failover](cross-regional-async-replication/switchover-failover) for more information. +The `promote-to-primary` action can be used in cluster scope, when using cluster-cluster replication. +Check [Switchover / Failover](cluster-cluster-replication/switchover-failover) for more information. ``` \ No newline at end of file diff --git a/docs/redirects.txt b/docs/redirects.txt index 93dddcf740..5c1ce6f80a 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -53,12 +53,12 @@ h-upgrade-juju/ how-to/refresh/upgrade-juju h-upgrade-minor/ how-to/refresh/single-cluster/refresh-single-cluster h-rollback-minor/ how-to/refresh/single-cluster/roll-back-single-cluster -h-async/ how-to/cross-regional-async-replication/ -h-async-deployment/ how-to/cross-regional-async-replication/deploy -h-async-clients/ how-to/cross-regional-async-replication/clients -h-async-failover/ how-to/cross-regional-async-replication/switchover-failover -h-async-recovery/ how-to/cross-regional-async-replication/recovery -h-async-removal/ how-to/cross-regional-async-replication/removal +h-async/ how-to/cluster-cluster-replication/ +h-async-deployment/ how-to/cluster-cluster-replication/deploy +h-async-clients/ how-to/cluster-cluster-replication/clients +h-async-failover/ how-to/cluster-cluster-replication/switchover-failover +h-async-recovery/ how-to/cluster-cluster-replication/recovery +h-async-removal/ how-to/cluster-cluster-replication/removal h-development-integrate/ how-to/development/integrate-with-your-charm h-migrate-mysqldump/ how-to/development/migrate-data-via-mysqldump diff --git a/docs/reference/releases.md b/docs/reference/releases.md index 112bf424ff..6b3178a1a6 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -6,7 +6,7 @@ To learn more about the different release tracks and channels, see the [Juju doc To see all releases and commits, check the [Charmed MySQL K8s Releases page on GitHub](https://github.com/canonical/mysql-k8s-operator/releases). -| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/refresh/single-cluster/refresh-single-cluster) | [Cross-regional async replication](/how-to/cross-regional-async-replication/deploy) | [Point-in-time recovery](point-in-time-recovery) +| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/refresh/single-cluster/refresh-single-cluster) | [Cluster-cluster replication](/how-to/cluster-cluster-replication/deploy) | [Point-in-time recovery](point-in-time-recovery) |:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | [254], [255] | 8.0.41 | `3.5.4+` | ![check] | ![check] | ![check] | ![check] | ![check] | | [240], [241] | 8.0.41 | `3.5.4+` | ![check] | ![check] | ![check] | ![check] | | From b28deb0f2157f873cf894165164def7e9e07b51c Mon Sep 17 00:00:00 2001 From: andreia Date: Mon, 20 Oct 2025 17:18:50 +0200 Subject: [PATCH 3/4] fill in supported refresh revisions --- docs/how-to/refresh/index.md | 41 +++++++++++++++++++++++++------- docs/index.md | 2 +- docs/reference/charm-statuses.md | 2 +- 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/docs/how-to/refresh/index.md b/docs/how-to/refresh/index.md index c14e0ad93c..035eb061b8 100644 --- a/docs/how-to/refresh/index.md +++ b/docs/how-to/refresh/index.md @@ -11,25 +11,48 @@ This charm supports in-place upgrades to higher versions via Juju's [`refresh`]( | Charm | MySQL | Charm | MySQL | | revision | Version | revision | Version | +============+============+==========+============+ -| XXX, XXX | ``8.0.41`` | | | +| 254, 255 | ``8.0.41`` | | | +------------+------------+----------+------------+ -| XXX, XXX | ``8.0.39`` | XXX, XXX | ``8.0.41`` | +| 240, 241 | ``8.0.41`` | 254, 255 | ``8.0.41`` | +------------+------------+----------+------------+ -| XXX | ``8.0.36`` | XXX, XXX | ``8.0.41`` | +| 210, 211 | ``8.0.39`` | 254, 255 | ``8.0.41`` | | | +----------+------------+ -| | | XXX, XXX | ``8.0.39`` | +| | | 240, 241 | ``8.0.41`` | +------------+------------+----------+------------+ -| XXX | ``8.0.34`` | None | | +| 180, 181 | ``8.0.37`` | 254, 255 | ``8.0.41`` | +| | +----------+------------+ +| | | 240, 241 | ``8.0.41`` | +| | +----------+------------+ +| | | 210, 211 | ``8.0.39`` | ++------------+------------+----------+------------+ +| 153 | ``8.0.36`` | 254, 255 | ``8.0.41`` | +| | +----------+------------+ +| | | 240, 241 | ``8.0.41`` | +| | +----------+------------+ +| | | 210, 211 | ``8.0.39`` | +| | +----------+------------+ +| | | 180, 181 | ``8.0.37`` | +------------+------------+----------+------------+ -| XXX | ``8.0.32`` | XXX | ``8.0.36`` | +| 127 | ``8.0.35`` | None | | ++------------+------------+----------+------------+ +| 113 | ``8.0.34`` | 127 | ``8.0.35`` | ++------------+------------+----------+------------+ +| 99 | ``8.0.34`` | 127 | ``8.0.35`` | +| | +----------+------------+ +| | | 113 | ``8.0.35`` | ++------------+------------+----------+------------+ +| 75 | ``8.0.32`` | 127 | ``8.0.35`` | +| | +----------+------------+ +| | | 113 | ``8.0.35`` | | | +----------+------------+ -| | | XXX | ``8.0.34`` | +| | | 99 | ``8.0.34`` | +------------+------------+----------+------------+ + ``` -Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision xxx](https://github.com/canonical/mysql-operator/releases/tag/revxxx) **cannot** be upgraded using Juju's `refresh`. +Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision 153](https://github.com/canonical/mysql-operator/releases/tag/rev153) **cannot** be upgraded using Juju's `refresh`. -To upgrade from older versions to Revision xxx or higher, the data must be migrated manually. See: [](/how-to/development/migrate-data-via-backup-restore). +To upgrade from older versions to Revision 153 or higher, the data must be migrated manually. See: [](/how-to/development/migrate-data-via-backup-restore). ### Juju version upgrade diff --git a/docs/index.md b/docs/index.md index 4258c95356..99287d2d25 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ This operator is built with the [charm SDK](https://juju.is/docs/sdk) replaces [ Charmed MySQL K8s includes features such as cluster-to-cluster replication, TLS encryption, password rotation, backups, and easy integration with other applications both inside and outside of Juju. It meets the need of deploying MySQL in a structured and consistent manner while allowing the user flexibility in configuration, simplifying reliable management of MySQL in production environments. ```{note} -This is a **Kubernetes** operator. To deploy on IAAS/VM, see [Charmed MySQL VM](https://charmhub.io/mysql). +This is a **Kubernetes** operator. To deploy on IAAS/VM, see [Charmed MySQL VM](https://canonical-charmed-mysql.readthedocs-hosted.com/). ``` ## In this documentation diff --git a/docs/reference/charm-statuses.md b/docs/reference/charm-statuses.md index c9b1d2d093..29d20d7bf6 100644 --- a/docs/reference/charm-statuses.md +++ b/docs/reference/charm-statuses.md @@ -12,7 +12,7 @@ The charm follows [standard Juju applications statuses](https://documentation.ub | **waiting** | any | Charm is waiting for relations to be finished | No actions required | | **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration) | No actions required | | **blocked** | any | The manual user activity is required! | Follow the message hints (see below) | -| **blocked** | Failed to set up relation | The relation between two applications failed to be created. Most probably it is a regression of the recent changes in applications | Check Juju [debug-log](https://juju.is/docs/olm/juju-debug-log). Increase debug level and reproduce the issue. Report as an issue with debug logs attached (if reproducible). Consider to try previous revision for both applications | +| **blocked** | Failed to set up relation | The relation between two applications failed to be created. Most probably it is a regression of the recent changes in applications | Check Juju [debug-log](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/debug-log/). Increase debug level and reproduce the issue. Report as an issue with debug logs attached (if reproducible). Consider to try previous revision for both applications | | **blocked** | Failed to initialize mysql relation | The same as "Failed to set up relation" | See "Failed to set up relation" | | **blocked** | Failed to remove relation user | TODO: clean manually? How to unblock? | | | **blocked** | Failed to install and configure MySQL | TODO | | From 41bba00c3aba546eafff4610e92499f1fb7803d2 Mon Sep 17 00:00:00 2001 From: andreia Date: Tue, 21 Oct 2025 11:37:09 +0200 Subject: [PATCH 4/4] apply review suggestions --- docs/how-to/index.md | 2 +- docs/how-to/refresh/index.md | 2 +- docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md | 1 - 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 2cdaf34ea8..c0c9c8f793 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -47,7 +47,7 @@ Integrate with observability services like Grafana, Prometheus, and Tempo. Monitoring (COS) ``` -## Refresh ( upgrade) +## Refresh (upgrade) ```{toctree} :titlesonly: diff --git a/docs/how-to/refresh/index.md b/docs/how-to/refresh/index.md index 035eb061b8..cb29443aad 100644 --- a/docs/how-to/refresh/index.md +++ b/docs/how-to/refresh/index.md @@ -50,7 +50,7 @@ This charm supports in-place upgrades to higher versions via Juju's [`refresh`]( ``` -Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision 153](https://github.com/canonical/mysql-operator/releases/tag/rev153) **cannot** be upgraded using Juju's `refresh`. +Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision 127](https://github.com/canonical/mysql-k8s-operator/releases/tag/rev127) **cannot** be upgraded using Juju's `refresh`. To upgrade from older versions to Revision 153 or higher, the data must be migrated manually. See: [](/how-to/development/migrate-data-via-backup-restore). diff --git a/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md b/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md index bee3a8e9e0..276153bfd8 100644 --- a/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md +++ b/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md @@ -30,4 +30,3 @@ Use the [`get-cluster-status`](https://charmhub.io/mysql-k8s/actions#get-cluster If something goes wrong, roll back the cluster. See: [](/how-to/refresh/single-cluster/roll-back-single-cluster) -