[DPE-7242] Add multi-cluster refresh docs (#690)

* update naming scheme for upgrade docs

* minor edits to Juju upgrades

* add empty multi-cluster upgrade doc and update references

* update content in single and multi-cluster upgrade docs

* update 'upgrade' terminology to 'refresh'

* update cross-regional async replication terminology

* add table of supported refreshes

* small edits

* update sample refresh commands to match juju status

* minor edits

* Apply suggestion from @sinclert-canonical

Co-authored-by: Sinclert Pérez <[email protected]>

* Apply review suggestions

* Update docs/how-to/refresh/index.md

Co-authored-by: Sinclert Pérez <[email protected]>

* split single and multi-cluster instructions into folders

* remove terraform domain from linkcheck

* fix broken references

* fix broken juju link

* fix 24.04 mention

* fix broken reference

---------

Co-authored-by: Sinclert Pérez <[email protected]>

Author: a-velasco

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/*"
     ]
 
 

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 renamed to 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 renamed to 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 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 <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 renamed to 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 renamed to 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 renamed to 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/cross-regional-async-replication/index.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).