[DPE-7242] Add multi-cluster refresh docs

docs/explanation/juju.md

@@ -31,12 +31,14 @@ See the [Juju 3.0 release notes](https://documentation.ubuntu.com/juju/3.6/refer
 The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example:
 
 ### Juju 3.x:
+
 ```shell
 juju integrate mysql:database mysql-test-app
 
 juju run mysql/leader get-password 
 ```
 ### Juju 2.9.x:
+
 ```shell
 juju relate mysql:database mysql-test-app
 
@@ -46,7 +48,9 @@ juju run-action --wait mysql/leader get-password
 This section is based on the [OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x)
 ```
 
+(explanation-juju-upgrades)=
 ## Juju  upgrades
+
 Newly released charm revisions might require a new Juju version. This is usually because the new revision requires new Juju features, e.g. [Juju secrets](https://juju.is/docs/juju/secret).
 
 Information about Juju requirements will be clearly indicated in the charm's [release notes](/reference/releases) and in the repository's [metadata.yaml](https://github.com/canonical/mysql-operator/blob/14c06ff88c4e564cd6d098aa213bd03e78e84b52/metadata.yaml#L72-L80) file.
@@ -62,5 +66,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.
 

docs/how-to/cross-regional-async-replication/clients.md → docs/how-to/cluster-cluster-replication/clients.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 according to [](/how-to/cluster-cluster-replication/deploy).
 
 ## Offer and consume database endpoints
 

docs/how-to/cross-regional-async-replication/deploy.md → docs/how-to/cluster-cluster-replication/deploy.md

@@ -1,14 +1,4 @@
-# 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`:
 
@@ -24,7 +14,7 @@ juju deploy mysql db2 --channel=8.0/edge --config profile=testing --config clust
 ```
 
 ```{caution}
-Remove profile configuration for production deployments. Check [Profiles](/reference/profiles) for documentation.
+Remove [profile](/reference/profiles) configuration for production deployments. 
 ```
 
 ## Offer
@@ -107,8 +97,5 @@ juju add-unit db2 -n 2 -m lisbon
 ```
 
 ```{caution}
-**Note**: The scaling is possible before and after the asynchronous replication established/created.
+The scaling is possible before and after the asynchronous replication is established/created.
 ```
-
-[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen
-

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 distribute data across different geographical regions as well.
+
+## 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 <deploy>
+Clients <clients>
+Switchover/failover <switchover-failover>
+Recovery <recovery>
+Removal <removal>
+```
+
+[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen

docs/how-to/cross-regional-async-replication/recovery.md → docs/how-to/cluster-cluster-replication/recovery.md

@@ -2,7 +2,7 @@
 
 ## 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 [async deployment guide](/how-to/cluster-cluster-replication/deploy).
 
 ## Recover detached cluster
 

docs/how-to/cross-regional-async-replication/removal.md → 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 [async 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):

docs/how-to/cross-regional-async-replication/switchover-failover.md → 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)
 

docs/how-to/development/migrate-data-via-backup-restore.md

@@ -1,4 +1,4 @@
-# Migrate data via backup/restore
+# How to migrate data via backup/restore
 
 Charmed MySQL is able to restore [its own backups](/how-to/back-up-and-restore/restore-a-backup) stored on [S3-compatible storage](/how-to/back-up-and-restore/configure-s3-aws). 
 

docs/how-to/index.md

@@ -47,22 +47,22 @@ Integrate with observability services like Grafana, Prometheus, and Tempo.
 Monitoring (COS) <monitoring-cos/index>
 ```
 
-## Upgrades
+## Refresh (upgrade)
 
 ```{toctree}
 :titlesonly:
 :maxdepth: 2
 
-Upgrade <upgrade/index>
+Refresh (upgrade) <refresh/index>
 ```
 
-## Cross-regional (cluster-cluster) async replication
+## Cluster-cluster replication
 
 ```{toctree}
 :titlesonly:
 :maxdepth: 2
 
-Cross-regional async replication <cross-regional-async-replication/index>
+Cluster-cluster replication <cluster-cluster-replication/index>
 ```
 
 ## Development

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 revision 237 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)
 

docs/how-to/primary-switchover.md

@@ -16,5 +16,6 @@ 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.
+
+See [](/how-to/cluster-cluster-replication/switchover-failover) for more information.
 ```

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    |
++============+============+==========+============+
+| 366, 367   | ``8.0.41`` |          |            |
++------------+------------+----------+------------+
+| 312, 313   | ``8.0.39`` | 366, 367 | ``8.0.41`` |
++------------+------------+----------+------------+
+| 240        | ``8.0.36`` | 366, 367 | ``8.0.41`` |
+|            |            +----------+------------+
+|            |            | 312, 313 | ``8.0.39`` |
++------------+------------+----------+------------+
+| 196        | ``8.0.34`` | None     |            |
++------------+------------+----------+------------+
+| 151        | ``8.0.32`` | 240      | ``8.0.36`` |
+|            |            +----------+------------+
+|            |            | 196      | ``8.0.34`` |
++------------+------------+----------+------------+
+```
+
+Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision 240](https://github.com/canonical/mysql-operator/releases/tag/rev240) **cannot** be refreshed beyond [Revision 196](https://github.com/canonical/mysql-operator/releases/tag/rev196).
+
+To upgrade from older versions to Revision 240 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/refresh-single-cluster)
+* [](/how-to/refresh/roll-back-single-cluster)
+
+To refresh a **multi-cluster** deployment, see
+
+* [](/how-to/refresh/refresh-multi-cluster)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+Refresh a cluster <refresh-single-cluster>
+Roll back a cluster <roll-back-single-cluster>
+Refresh a multi-cluster deployment <refresh-multi-cluster>
+Upgrade Juju <upgrade-juju>
+```
+
+<!--Links-->
+
+[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303
+[check]: https://img.icons8.com/color/20/checkmark--v1.png

docs/how-to/refresh/refresh-multi-cluster.md

@@ -0,0 +1,38 @@
+# How to refresh a multi-cluster deployment
+
+A MySQL multi-cluster deployment (also known as a multi-node cluster or 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.**
+
+When a primary cluster gets refreshed, it triggers a potentially costly re-election process. To minimise this cost, all standby clusters should be refreshed before the primary.
+
+<!--TODO: Mention how to identify primary cluster-->
+
+## Refresh each cluster
+
+For each cluster, follow the instructions in [](/how-to/refresh/refresh-single-cluster).
+
+**Perform a health check before proceeding to the next cluster.**
+
+Use the [`get-cluster-status`](https://charmhub.io/mysql/actions#get-cluster-status) Juju action to check that everything is healthy after refreshing a cluster.
+
+<!---TODO: example of running get-cluster-status (and making sure the cluster-set param is True?)
+```shell
+juju run <?> get-cluster-status
+```
+-->
+
+## Roll back
+
+If something goes wrong, roll back the cluster. See: [](/how-to/refresh/roll-back-single-cluster)
+
+<!--TODO: clarify what to do if you've already refreshed one or more clusters, another one fails, and you need to roll back everything - including the clusters that are fully upgraded -->
+
+
+