Sync docs from Discourse (#523)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

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-deploy-canonical-k8s.md

@@ -0,0 +1,74 @@
+# How to deploy on Canonical Kubernetes
+
+[Canonical Kubernetes](https://ubuntu.com/kubernetes) is a Kubernetes service built on Ubuntu and optimized for most major public clouds. 
+
+This guide shows you how to deploy Charmed MySQL K8s to Canonical Kubernetes.
+
+## Summary
+This guide assumes you have a spare hardware/VMs running Ubuntu 22.04 LTS (or newer). 
+
+* [Install Canonical Kubernetes](#install-canonical-kubernetes)
+* [Install Juju](#install-juju)
+* [Deploy Charmed MySQL K8s](#deploy-charmed-mysql-k8s)
+
+---
+
+## Install Canonical Kubernetes
+
+>The following instructions are a complete but summarized version of the steps for installing Canonical K8s. For more thorough instructions and details, see the official Canonical Kubernetes documentation: [Install Canonical Kubernetes from a snap](https://documentation.ubuntu.com/canonical-kubernetes/latest/src/snap/howto/install/snap/).
+
+Install, bootstrap, and check the status of Canonical K8s with the following commands:
+```shell
+sudo snap install k8s --edge --classic
+sudo k8s bootstrap
+sudo k8s status --wait-ready
+```
+
+Once Canonical K8s is up and running, [enable the local storage](https://documentation.ubuntu.com/canonical-kubernetes/latest/snap/tutorial/getting-started/#enable-local-storage) (or any another persistent volumes provider, to be used by [Juju Storage](https://juju.is/docs/juju/storage) later):
+```shell
+sudo k8s enable local-storage
+sudo k8s status --wait-ready
+```
+
+(Optional) Install kubectl tool and dump the K8s config:
+```shell
+sudo snap install kubectl --classic
+mkdir ~/.kube
+sudo k8s config > ~/.kube/config
+kubectl get namespaces # to test the credentials
+```
+
+## Install Juju
+
+Install Juju and bootstrap the first Juju controller in K8s:
+```shell
+sudo snap install juju --channel 3.6/candidate
+juju add-k8s ck8s --client --context-name="k8s"
+juju bootstrap ck8s
+```
+
+## Deploy Charmed MySQL K8s
+
+```shell
+juju add-model mysql
+juju deploy mysql-k8s --trust
+```
+
+follow the deployment progress using:
+```shell
+juju status --watch 1s
+```
+
+Example output:
+```shell
+Model   Controller  Cloud/Region  Version  SLA          Timestamp
+mysql   ck8s        ck8s          3.6-rc1  unsupported  18:32:38+01:00
+
+App         Version                  Status  Scale  Charm           Channel     Rev  Address         Exposed  Message
+mysql-k8s   8.0.37-0ubuntu0.22.04.3  active      1  mysql-k8s       8.0/stable  180  10.152.183.146  no       
+
+Unit           Workload  Agent  Address    Ports  Message
+mysql-k8s/0*   active    idle   10.1.0.11         Primary
+```
+
+>**Next steps:** Learn [how to scale your application](/t/9675), [relate with other applications](/t/9671) and [more](/t/9677)!

docs/how-to/h-development-integrate.md

@@ -1,17 +1,45 @@
-# How to integrate DB with my charm
+# How to integrate a database with your charm
 
-Please check [the supported interfaces](/t/10249) of the current charm first. You have options to use modern (preferred) or legacy interfaces. Make sure you are familiar with [Juju integration concepts](https://juju.is/docs/juju/integration).
+Charmed MySQL K8s can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with MySQL.
 
-The most existing charms currently use [ops-lib-mysql](https://github.com/canonical/ops-lib-mysql) interface (legacy). Canonical recommends for new charms to use [data-platform-libs](https://github.com/canonical/data-platform-libs) instead. You can take a look at [mysql-test-app](https://github.com/canonical/mysql-test-app) for more practical examples. Consider to [read the great manual about the charm development](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql). The legacy charm details are well described [here](/t/11236).
+## Summary
+* Check supported interfaces 
+* Integrate your charm with MySQL
+* Troubleshooting & testing
+* FAQ
 
+---
 
-FAQ:
-* Q: Does the requirer need to set anything in relation data?<br/>A: it depends on the interface. Check the `mysql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/mysql_client/v0/README.md).
-* Q: Is there a charm library available, or does my charm need to compile the mysql relation data on its own?<br/>A: Yes, the library is available: [data-platform-libs](https://github.com/canonical/data-platform-libs).
-* Q: How do I obtain the database url/uri?<br/>A: [it is planned](https://warthogs.atlassian.net/browse/DPE-2278), but currently missing. Meanwhile use [PostgreSQL as an example](https://charmhub.io/postgresql-k8s/docs/h-develop-mycharm).
+## Check supported interfaces
 
-Troubleshooting:
-* Please start with [Juju troubleshooting guide](https://juju.is/docs/sdk/debug-a-charm).
-* Check Charmed MySQL K8s [troubleshooting hints](/t/11886).
+First, we recommend that you check [the supported interfaces](/t/10249) of the current charm. You have the option to use modern (preferred) or legacy interfaces. 
+
+Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ops-lib-pgsql) interface (legacy). 
+> See also: [MySQL K8s legacy charm explanation](/t/11236)
+
+ For new charms, **Canonical recommends using [data-platform-libs](https://github.com/canonical/data-platform-libs).**
+
+## Integrate your charm with MySQL
+
+> See also: 
+> * [Juju documentation | Integration](https://juju.is/docs/juju/integration)
+> * [Juju documentation | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql)
+
+Refer to [mysql-test-app](https://github.com/canonical/mysql-test-app) as a practical example of implementing data-platform-libs interfaces to integrate a charm with Charmed MySQL K8s.
+
+## Troubleshooting and testing
+* To learn the basics of charm debugging, start with [Juju | How to debug a charm](https://juju.is/docs/sdk/debug-a-charm)
+* To troubleshoot Charmed MySQL, see the [Troubleshooting](/t/11886) page.
+* To test the charm, check the [Testing](/t/11772) reference
+
+## FAQ
+**Does the requirer need to set anything in relation data?**
+> It depends on the interface. Check the `mysql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/mysql_client/v0/README.md).
+
+**Is there a charm library available, or does my charm need to compile the mysql relation data on its own?**
+> Yes, a library is available: [data-platform-libs](https://github.com/canonical/data-platform-libs).
+
+**How do I obtain the database url/uri?**
+>This feature is [planned](https://warthogs.atlassian.net/browse/DPE-2278) but currently missing.
 
 [Contact us](/t/11868) if you have any questions, issues and/or ideas!

docs/how-to/h-development.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