[discourse-gatekeeper] Migrate charm docs (#450)

* 'modified: docs/reference/r-releases-group/r-releases.md // new: docs/reference/r-releases-group/r-releases-rev232.md'

* 'modified: docs/reference/r-releases-group/r-releases-rev232.md,docs/reference/r-releases-group/r-releases.md // removed: docs/reference/r-releases-group/r-releases-rev203.md'

* 'modified: docs/reference/r-releases-group/r-releases.md // new: docs/reference/r-releases-group/r-releases-rev234.md'

* 'new: docs/how-to/h-async/h-async-clients.md,docs/how-to/h-async/h-async-deployment.md,docs/how-to/h-async/h-async-fence.md,docs/how-to/h-async/h-async-failover.md,docs/how-to/h-async/h-async-recovery.md,docs/how-to/h-async/h-async-removal.md'

* 'modified: docs/how-to/h-setup/h-deploy-maas.md'

---------

Co-authored-by: upload-charms-docs-bot <[email protected]>

Author: github-actions[bot]

docs/how-to/h-async/h-async-clients.md

@@ -0,0 +1,42 @@
+# Clients for Async replication
+> **WARNING**: it is an '8.0/candidate' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11867) if you are interested in the topic.
+
+## Pre-requisits
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
+
+## Offer and consume DB endpoints
+```shell
+juju switch rome
+juju offer db1:database db1-database
+
+juju switch lisbon
+juju offer db2:database db2-database
+
+juju add-model app ; juju switch app
+juju consume rome.db1-database
+juju consume lisbon.db2-database
+```
+
+## Internal Juju app/clients
+```shell
+juju switch app
+
+juju deploy mysql-test-app
+juju deploy mysql-router --channel dpe/edge
+
+juju relate mysql-test-app mysql-router
+juju relate mysql-router db1-database
+```
+
+## External Juju clients
+```shell
+juju switch app
+
+juju deploy data-integrator --config database-name=mydatabase
+juju deploy mysql-router mysql-router-external --channel dpe/edge
+
+juju relate data-integrator mysql-router-external
+juju relate mysql-router-external db1-database
+
+juju run data-integrator/leader get-credentials
+```

docs/how-to/h-async/h-async-deployment.md

@@ -0,0 +1,86 @@
+# Deploy Async replication
+> **WARNING**: it is an '8.0/candidate' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11867) if you are interested in the topic.
+
+## 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
+
+juju switch rome
+juju deploy mysql-k8s db1 --channel=8.0/candidate --config profile=testing --config cluster-name=rome --base [email protected]
+
+juju switch lisbon
+juju deploy mysql-k8s db2 --channel=8.0/candidate --config profile=testing --config cluster-name=lisbon --base [email protected]
+```
+
+[note type="caution"]
+**Note**: remove profile configuration for production deployments. Check [Profiles](/t/11973) for documentation.
+[/note]
+
+## Offer
+
+Offer asynchronous replication on the Primary cluster (Rome):
+```shell
+juju switch rome
+juju offer db1:async-primary async-primary
+```
+
+(Optional) Offer asynchronous replication on StandBy cluster (Lisbon), for the future:
+```shell
+juju switch lisbon
+juju offer db2:async-primary async-primary
+``` 
+
+## Consume
+
+Consume asynchronous replication on planned `StandBy` cluster (Lisbon):
+```shell
+juju switch lisbon
+juju consume rome.async-primary
+juju integrate async-primary db2:async-replica
+``` 
+
+(Optional) Consume asynchronous replication on the current `Primary` (Rome), for the future:
+```shell
+juju switch rome
+juju consume lisbon.async-primary
+``` 
+
+## Status
+
+Run the `get-cluster-status` action with the `cluster-set=True`flag: 
+```shell
+juju run -m rome db1/0 get-cluster-status cluster-set=True
+```
+Results:
+```shell
+status:
+  clusters:
+    lisbon:
+      clusterrole: replica
+      clustersetreplicationstatus: ok
+      globalstatus: ok
+    rome:
+      clusterrole: primary
+      globalstatus: ok
+      primary: 10.82.12.22:3306
+  domainname: cluster-set-bcba09a4d4feb2327fd6f8b0f4ac7a2c
+  globalprimaryinstance: 10.82.12.22:3306
+  primarycluster: rome
+  status: healthy
+  statustext: all clusters available.
+success: "True"
+```
+
+## Scaling
+The two clusters works independently, this means that it's possible to independently scaling in/out each cluster without much hassle, e.g.:
+```shell
+juju add-unit db1 -n 2 -m rome
+
+juju add-unit db2 -n 2 -m lisbon
+```
+[note type="caution"]
+**Note**: The scaling is possible before and after the asynchronous replication established/created.
+[/note]

docs/how-to/h-async/h-async-failover.md

@@ -0,0 +1,35 @@
+# Switchover / Failover of Async replication
+> **WARNING**: it is an '8.0/candidate' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11867) if you are interested in the topic.
+
+## Pre-requisits
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
+
+## Switchover (safe)
+Assuming `Rome` is currently `Primary` and you want to promote `Lisbon` to be new primary<br/>(`Rome` will be converted to `StandBy` member):
+```shell
+juju run -m lisbon db2/leader promote-standby-cluster cluster-set-name=<cluster-set-119185404c15ba547eb5f0750a5c34b5>
+```
+where `cluster-set-name` is a mandatory option to avoid human mistakes.
+
+The cluster-set-name [can be set on deployment](https://charmhub.io/mysql/configure) and retrieved using:
+```
+juju run -m rome db1/0 get-cluster-status cluster-set=true
+
+   ...
+   domainname: cluster-set-bcba09a4d4feb2327fd6f8b0f4ac7a2c
+   ...
+```
+
+## Failover (forced)
+
+[note type="caution"]
+**Warning**: this is a **dangerous** operation which can cause the split-brain situation. It should be executed if Primary cluster is no longer exist (lost) ONLY! Otherwise please use safe switchover procedure above! Also consider [to fence the write traffic](/t/14173) BEFORE forcing emergency failover.
+[/note]
+
+Assuming `Rome` was a `Primary` (before we lost the cluster `Rome`) and you want to promote `Lisbon` to be the new primary:
+```shell
+juju run -m lisbon db2/leader promote-standby-cluster cluster-set-name=<cluster-set-bcba09a4d4feb2327fd6f8b0f4ac7a2c> force=True
+```
+It's required to provide the `cluster-set-name` option as a foolproof method.
+
+> **Warning**: The `force` will cause the old primary to be invalidated, make sure you have [fenced writes](/t/14173) there (fencing will reject all writes to the ClusterSet during the emergency failover)!

docs/how-to/h-async/h-async-fence.md

@@ -0,0 +1,36 @@
+# Fencing Async replication
+> **WARNING**: it is an '8.0/candidate' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11867) if you are interested in the topic.
+
+## Pre-requisits
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
+
+## Fencing
+
+In case of [emergency failover](/t/14171), and there is a risk of the transaction sets differing between parts of the ClusterSet.  To avoid a split brain scenario, where more than one cluster is set as `primary`, it's important to fence all write traffic from the failed primary cluster. For doing so there's an action `fence-writes`:
+```
+juju run -m rome db1/leader fence-writes cluster-set-name=<my-cluster-set>
+```
+where `cluster-set-name` is a mandatory option to avoid human mistakes (see below).
+
+> **Note**: The action `fence-writes` can be run against any of the Primary Cluster units.
+
+## Unfencing
+
+Case the old primary is reestablished and/or have all transactions reconciled, one can resume write traffic to it, by using the `unfence-writes` action, e.g.: 
+```
+juju run -m rome db1/leader unfence-writes cluster-set-name=<my-cluster-set>
+```
+where `cluster-set-name` is a mandatory option to avoid human mistakes (see below).
+
+## ClusterSet name:
+The `cluster-set-name` [can be set on deployment](https://charmhub.io/mysql/configure) and retrieved using:
+```
+juju run db1/0 get-cluster-status cluster-set=true
+
+   ...
+   domainname: cluster-set-bcba09a4d4feb2327fd6f8b0f4ac7a2c
+   ...
+```
+
+## Extra
+You can find more details about fencing in official [MySQL ClusterSet documentation](https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-cluster-fencing.html).

docs/how-to/h-async/h-async-recovery.md

@@ -0,0 +1,36 @@
+# Recovery of Async replication
+> **WARNING**: it is an '8.0/candidate' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11867) if you are interested in the topic.
+
+## Pre-requisits
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
+
+## Recovery detached cluster
+
+If relation between clusters was removed and one side went into detached/blocked state: simply relate async replication back to restore ClusterSet.
+
+## Recovery 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.
+
+## Recovery 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. If the invalidated cluster connections is restored, it's status will be displayed in juju status as:
+
+```
+App  Version                  Status  Scale  Charm  Channel   Rev  Address         Exposed  Message
+db2  8.0.36-0ubuntu0.22.04.1  active      3  mysql  8.0/edge  234  10.152.183.241  no
+
+Unit    Workload  Agent  Address       Ports  Message
+db2/0   active    idle   10.1.124.208      
+db2/1*  active    idle   10.1.124.203         Primary (standby, invalidated)
+db2/2   active    idle   10.1.124.200      
+```
+
+Which indicates that connectivity is possible, but replication channel is stopped.
+To restore replication operation, run:
+
+```shell
+juju run db2/leader rejoin-cluster cluster-name=rome
+```
+
+Being `rome` the name of the invalidated cluster.

docs/how-to/h-async/h-async-removal.md

@@ -0,0 +1,56 @@
+# Removal of Async replication
+> **WARNING**: it is an '8.0/candidate' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11867) if you are interested in the topic.
+
+## Pre-requisits
+
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
+
+## Detach Cluster from ClusterSet
+
+> **Note**: It is important to [switchover](/t/14171) 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):
+
+```shell
+
+juju remove-relation async-primary db2:async-replica
+
+```
+
+The command above will move cluster `Rome` into the detached state `blocked` keeping all the data in place.
+
+All units in `Rome` will be in a standalone (non-clusterized) read-only state.
+
+From this points, there are three options, as described in the following sections.
+
+## 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:
+
+```shell
+
+juju switch rome
+
+juju integrate async-primary db1:async-replica
+
+```
+
+## Removing detached cluster
+
+Remove no-longer necessary Cluster `Rome` (and destroy storage if Rome data is no longer necessary):
+
+```shell
+
+juju remove-application db1 # --destroy-storage
+
+```
+
+## New ClusterSet from detached Cluster
+
+Convert `Rome` to the new Cluster/ClusterSet keeping the current data in use:
+
+```shell
+
+juju run -m rome db1/leader recreate-cluster
+
+```

docs/how-to/h-setup/h-deploy-maas.md

@@ -120,15 +120,23 @@ juju bootstrap --constraints tags=juju maas-cloud maas-controller
 
 # Deploy Charmed MySQL on MAAS
 ```shell
-juju add-model mysql
-juju deploy mysql --channel 8.0/stable
+juju add-model mysql maas-cloud
+juju deploy mysql --channel 8.0/candidate # MAAS supported since charm revision 234+
 ```
-<!--
 Sample `juju status` output:
 ```shell
-TODO
+Model  Controller       Cloud/Region        Version  SLA          Timestamp
+mysql  maas-controller  maas-cloud/default  3.1.8    unsupported  12:57:06+02:00
+
+App    Version          Status  Scale  Charm  Channel        Rev  Exposed  Message
+mysql  8.0.36-0ubun...  active      1  mysql  8.0/candidate  234  no       
+
+Unit      Workload  Agent  Machine  Public address  Ports           Message
+mysql/1*  active    idle   1        10.10.10.7      3306,33060/tcp  Primary
+
+Machine  State    Address     Inst id       Base          AZ       Message
+1        started  10.10.10.7  pumped-racer  [email protected]  default  Deployed
 ```
--->
 
 # Test your Charmed MySQL deployment