Sync docs from Discourse

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

@@ -1,5 +1,13 @@
 # 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 two MySQL Clusters, named `Rome` and `Lisbon`:
@@ -92,4 +100,6 @@ The two clusters works independently, this means that it's possible to independe
 juju scale-application db1 3 -m rome
 
 juju scale-application db2 3 -m lisbon
-```
+```
+
+[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen

docs/how-to/h-configure-s3-aws.md

@@ -1,4 +1,10 @@
-> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju run ...` with `juju run-action --wait ...` and `juju integrate` with `juju relate` for Juju 2.9.
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Configure S3 for AWS
 
 Charmed MySQL K8s backup can be stored on any S3 compatible storage. The S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). Deploy and configure the s3-integrator charm for **[AWS S3](https://aws.amazon.com/s3/)** (click [here](/t/charmed-mysql-how-to-configure-s3-for-radosgw/10319) to backup on Ceph via RadosGW):
 ```shell

docs/how-to/h-configure-s3-radosgw.md

@@ -1,11 +1,29 @@
-Charmed MySQL K8s backup can be stored on any S3 compatible storage, e.g. on [Ceph](https://ceph.com/en/) via [RadosGW](https://docs.ceph.com/en/latest/man/8/radosgw/). The S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). Deploy and configure the s3-integrator charm for **RadosGW** (click [here](/t/charmed-mysql-k8s-how-to-configure-s3-for-aws/9651) to backup on AWS S3):
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Configure S3 for RadosGW
+
+A MySQL K8s backup can be stored on any S3-compatible storage. S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator).
+
+This guide will teach you how to deploy and configure the s3-integrator charm on Ceph via [RadosGW](https://docs.ceph.com/en/quincy/man/8/radosgw/), send the configuration to a Charmed MySQL K8s application, and update it. 
+> For AWS, see the guide [How to configure S3 for AWS](/t/9651)
+
+## Configure s3-integrator
+First, install the MinIO client and create a bucket:
 ```shell
-# Install MinIO client and create a bucket:
 mc config host add dest https://radosgw.mycompany.fqdn <access-key> <secret-key> --api S3v4 --lookup path
 mc mb dest/backups-bucket
-
+```
+Then, deploy and run the charm:
+```shell
 juju deploy s3-integrator
-juju run-action s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key> --wait
+juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key>
+```
+Lastly, use `juju config` to add your configuration parameters. For example:
+```shell
 juju config s3-integrator \
     endpoint="https://radosgw.mycompany.fqdn" \
     bucket="backups-bucket" \
@@ -15,24 +33,27 @@ juju config s3-integrator \
     s3-uri-style="path"
 ```
 
-To pass these configurations to Charmed MySQL K8s, relate the two applications:
+## Integrate with Charmed MySQL K8s
+
+To pass these configurations to Charmed MySQL K8s, integrate the two applications:
 ```shell
-juju relate s3-integrator mysql-k8s
+juju integrate s3-integrator mysql-k8s
 ```
 
-You can create/list/restore backups now:
-
+You can create, list, and restore backups now:
 ```shell
-juju run-action mysql-k8s/leader list-backups --wait
-juju run-action mysql-k8s/leader create-backup --wait
-juju run-action mysql-k8s/leader list-backups --wait
-juju run-action mysql-k8s/leader restore backup-id=<backup-id-here> --wait
+juju run mysql-k8s/leader list-backups
+juju run mysql-k8s/leader create-backup
+juju run mysql-k8s/leader list-backups
+juju run mysql-k8s/leader restore backup-id=<backup-id-here>
 ```
 
-You can also update your S3 configuration options after relating, using:
+You can also update your S3 configuration options after integrating, using:
 ```shell
 juju config s3-integrator <option>=<value>
 ```
 The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage.
 
-> :tipping_hand_man: **[MicroCeph TIP](https://github.com/canonical/microceph)**: make sure the `region` for `s3-integrator` matches `"sudo microceph.radosgw-admin zonegroup list"` output (use `region="default"` by default).
+[note]
+[MicroCeph](https://github.com/canonical/microceph)** tip: make sure the `region` for `s3-integrator` matches the `"sudo microceph.radosgw-admin zonegroup list"` output (use `region="default"` by default).
+[/note]

docs/how-to/h-create-backup.md

@@ -1,22 +1,34 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
 # How to create and list backups
 
-Creating and listing backups requires that you:
-* [Have a Charmed MySQL K8s deployed](/t/charmed-mysql-k8s-how-to-manage-units/9659)
+This guide contains recommended steps and useful commands for creating and managing backups to ensure smooth restores.
+
+## Prerequisites
+* A [deployed](/t/9659) MySQL K8s cluster
 * Access to S3 storage
-* [Have configured settings for S3 storage](/t/charmed-mysql-k8s-how-to-configure-s3/9651)
+* [Configured settings for S3 storage](/t/9651)
 
-Once Charmed MySQL K8s is `active` and `idle` (check `juju status`), you can create your first backup with the `create-backup` command:
+---
+
+## Create a backup
+
+Once `juju status` shows Charmed MySQL K8s as `active` and `idle` you can create your first backup with the `create-backup` command:
 ```shell
-juju run-action mysql-k8s/leader create-backup --wait
+juju run mysql-k8s/leader create-backup
 ```
 
-[note]
 If you have a cluster of one unit, you can run the `create-backup` action on `mysql-k8s/leader` (which will also be the primary unit). 
 
 Otherwise, you must run the `create-backup` action on a non-primary unit (see `juju status` or run `juju run-action mysql-k8s/leader get-cluster-status` to find the primary unit).
-[/note]
+
+## List backups
 
 You can list your available, failed, and in progress backups by running the `list-backups` command:
 ```shell
-juju run-action mysql-k8s/leader list-backups --wait
+juju run mysql-k8s/leader list-backups
 ```

docs/how-to/h-enable-alert-rules.md

@@ -2,7 +2,7 @@
 
 This guide will show how to set up [Pushover](https://pushover.net/) to receive alert notifications from the COS Alert Manager with [Awesome Alert Rules](https://samber.github.io/awesome-prometheus-alerts/).
 
-Charmed MySQL K8s ships a pre-configured and pre-enabled [list of Awesome Alert Rules].
+Charmed MySQL K8s ships a pre-configured and pre-enabled [list of Awesome Alert Rules]. 
 
 <details><summary>Screenshot of alert rules in the Grafana web interface</summary>
 
@@ -74,4 +74,4 @@ Do you have questions? [Contact us]!
 [Contact us]: /t/11868
 [Charmed MySQL K8s operator]: /t/11869
 [COS Monitoring]: /t/9981
-[list of Awesome Alert Rules]: https://github.com/canonical/mysql-k8s-operator/tree/main/src/prometheus_alert_rules
+[list of Awesome Alert Rules]: /t/15838

docs/how-to/h-enable-monitoring.md

@@ -1,26 +1,39 @@
-# Enable monitoring
-> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju run ...` with `juju run-action --wait ...` and `juju integrate` with `juju relate` for Juju 2.9.
+# How to enable monitoring (COS)
 
-Enable monitoring requires that you:
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+## Prerequisites
 * [Have a Charmed MySQL K8s deployed](/t/9677)
 * [Deploy `cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
 
-Switch to COS K8s environment and offer COS interfaces to be cross-model related with Charmed MySQL K8s model:
+## Offer interfaces via the COS controller
+Switch to COS K8s environment and offer COS interfaces to be cross-model related with Charmed MySQL K8s model.
+
+To switch to the Kubernetes controller, for the cos model, run
 ```shell
-# Switch to Kubernetes controller, for the cos model.
 juju switch <k8s_cos_controller>:<cos_model_name>
-
+```
+To offer the COS interfaces, run
+```shell
 juju offer grafana:grafana-dashboard
 juju offer loki:logging
 juju offer prometheus:receive-remote-write
 ```
 
-Switch to Charmed MySQL K8s model, find offers and consume them:
+## Consume offers via the MySQL model
+Next, we will switch to Charmed MySQL K8s model, find offers and consume them.
+
+We are on the Kubernetes controller for the COS model. To switch to the MySQL model, run
 ```shell
-# We are on the Kubernetes controller, for the cos model. Switch to mysql model
 juju switch <k8s_db_controller>:<mysql_model_name>
-
-juju find-offers <k8s_cos_controller>: # Do not miss ':' here!
+```
+To find offers, run the following command (make sure not to miss the ":" at the end!):
+```shell
+juju find-offers <k8s_cos_controller>:
 ```
 
 A similar output should appear, if `k8s` is the k8s controller name and `cos` the model where `cos-lite` has been deployed:
@@ -39,21 +52,28 @@ juju consume k8s:admin/cos.loki
 juju consume k8s:admin/cos.prometheus
 ```
 
-Now, deploy '[grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s)' and integrate (relate) it with Charmed MySQL K8s, later integrate (relate) `grafana-agent-k8s` with consumed COS offers:
+## Deploy and integrate Grafana
+First, deploy [grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s):
 ```shell
 juju deploy grafana-agent-k8s --trust
-
+```
+Then, integrate (relate) it with Charmed MySQL K8s:
+```shell
 juju relate grafana-agent-k8s grafana
 juju relate grafana-agent-k8s loki
 juju relate grafana-agent-k8s prometheus
+```
 
+Finally, integrate (relate) `grafana-agent-k8s` with consumed COS offers:
+```shell
 juju relate grafana-agent-k8s mysql-k8s:grafana-dashboard
 juju relate grafana-agent-k8s mysql-k8s:logging
 juju relate grafana-agent-k8s mysql-k8s:metrics-endpoint
 ```
 
 After this is complete, Grafana will show the new dashboards: `MySQL Exporter` and allows access for Charmed MySQL logs on Loki.
 
+### Sample outputs
 The example of `juju status` on Charmed MySQL K8s model:
 ```shell
 Model  Controller   Cloud/Region        Version  SLA          Timestamp
@@ -98,7 +118,8 @@ loki        loki         loki-k8s        60   1/1        logging               l
 prometheus  prometheus   prometheus-k8s  103  1/1        receive-remote-write  prometheus_scrape        requirer
 ```
 
-To connect Grafana WEB interface, follow the COS section "[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)":
+### Connect Grafana web interface
+To connect Grafana web interface, follow the COS section "[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)":
 ```shell
 juju run grafana/leader get-admin-password --model <k8s_controller>:<cos_model_name>
 ```

docs/how-to/h-migrate-cluster.md

@@ -1,24 +1,37 @@
-# How to restore foreign backup
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
 
-This is a How-To for restoring a backup that was made from the a *different* cluster, (i.e. cluster migration via restore). To perform a basic restore please reference the [Restore How-To](/t/charmed-mysql-k8s-how-to-restore-backup/9663)
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
 
+# How to migrate a cluster
+
+This is a guide on how to restore a backup that was made from a different cluster, (i.e. cluster migration via restore).
+
+To perform a basic restore please reference the [Restore How-To](/t/charmed-mysql-k8s-how-to-restore-backup/9663).
+
+## Prerequisites
 Restoring a backup from a previous cluster to a current cluster requires that you:
 - Have a single unit Charmed MySQL deployed and running
 - Access to S3 storage
 - [Have configured settings for S3 storage](/t/charmed-mysql-k8s-how-to-configure-s3/9651)
 - Have the backups from the previous cluster in your S3-storage
 - Have the passwords from your previous cluster
 
+---
+
+<a href="#heading--manage-cluster-passwords"><h2 id="heading--manage-cluster-passwords">Manage cluster passwords</h2></a>
 When you restore a backup from an old cluster, it will restore the password from the previous cluster to your current cluster. Set the password of your current cluster to the previous cluster’s password:
 ```shell
-juju run-action mysql-k8s/leader set-password username=root password=<previous cluster password> --wait
-juju run-action mysql-k8s/leader set-password username=clusteradmin password=<previous cluster password> --wait
-juju run-action mysql-k8s/leader set-password username=serverconfig password=<previous cluster password> --wait
+juju run mysql-k8s/leader set-password username=root password=<previous cluster password>
+juju run mysql-k8s/leader set-password username=clusteradmin password=<previous cluster password>
+juju run mysql-k8s/leader set-password username=serverconfig password=<previous cluster password>
 ```
 
+## List backups
 To view the available backups to restore you can enter the command `list-backups`:
 ```shell
-juju run-action mysql-k8s/leader list-backups --wait
+juju run mysql-k8s/leader list-backups
 ```
 
 This shows a list of the available backups (it is up to you to identify which `backup-id` corresponds to the previous-cluster):
@@ -29,9 +42,10 @@ This shows a list of the available backups (it is up to you to identify which `b
       YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
 ```
 
+## Restore backup
 To restore your current cluster to the state of the previous cluster, run the `restore` command and pass the correct `backup-id` to the command:
  ```shell
-juju run-action mysql-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ --wait
+juju run mysql-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
 ```
 
 Your restore will then be in progress, once it is complete your cluster will represent the state of the previous cluster.