'new: docs/how-to/h-async/h-async-failover.md,docs/how-to/h-upgrade/h…

…-upgrade-minor.md,docs/how-to/h-async/h-async-clients.md,docs/reference/r-releases-group/r-releases-rev99.md,docs/reference/r-releases-group/r-releases.md,docs/reference/r-releases-group/r-releases-rev127.md,docs/how-to/h-setup/h-deploy-aks.md,docs/how-to/h-setup/h-manage-units.md,docs/reference/r-testing.md,docs/how-to/h-to-manage-backups/h-configure-s3-aws.md,docs/explanation/e-juju.md,docs/tutorial/t-enable-security.md,docs/reference/r-releases-group/r-releases-rev113.md,docs/how-to/h-async/h-async-removal.md,docs/reference/r-requirements.md,docs/how-to/h-contribute.md,docs/how-to/h-async/h-async-recovery.md,docs/index.md,docs/how-to/h-upgrade/h-juju-upgrade.md,docs/reference/r-releases-group/r-releases-rev153.md,docs/how-to/h-monitoring/h-enable-monitoring.md,docs/how-to/h-async/h-async-deployment.md,docs/how-to/h-setup/h-enable-encryption.md,docs/how-to/h-monitoring/h-enable-tracing.md' (#456)

Co-authored-by: discourse-gatekeeper-docs-bot <[email protected]>

docs/explanation/e-juju.md

@@ -0,0 +1,70 @@
+# Juju 
+
+[Juju](https://juju.is/) is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms.
+
+This [charm](https://charmhub.io/mysql-k8s) is an operator - business logic encapsulated in reusable software packages that automate every aspect of an application's life. Charms are shared via [CharmHub](https://charmhub.io/).
+
+See also:
+
+* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju)
+* [Charm SDK](https://juju.is/docs/sdk)
+
+This page aims to provide some context on some of the inner workings of Juju that affect this charm.
+
+## Summary
+* [Breaking changes between Juju 2.8.x and 3.x](#heading--breaking-changes)
+* [Juju upgrades](#heading--upgrades)
+
+---
+
+<a href="#heading--breaking-changes"><h2 id="heading--breaking-changes"> Breaking changes between Juju 2.9.x and 3.x </h2></a>
+As this charm documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes.
+
+Breaking changes have been introduced in the Juju client between versions 2.9.x and 3.x. These are caused by the renaming and re-purposing of several commands - functionality and command options remain unchanged.
+
+In the context of this guide, the pertinent changes are shown here:
+
+|2.9.x|3.x|
+| --- | --- |
+|`add-relation`|`integrate`|
+|`relate`|`integrate`|
+|`run`|`exec`|
+|`run-action --wait`|`run`|
+
+See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for the comprehensive list of changes.
+
+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-k8s:database mysql-test-app
+
+juju run mysql-k8s/leader get-password 
+```
+### Juju 2.9.x:
+```shell
+juju relate mysql-k8s:database mysql-test-app
+
+juju run-action --wait mysql-k8s/leader get-password
+```
+[note]
+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)
+[/note]
+
+<a href="#heading--upgrades"><h2 id="heading--upgrades"> Juju  upgrades </h2></a>
+Newly released charm revisions might require a new [Juju version](/t/11742). 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](/t/11878) and in the repository's [metadata.yaml](https://github.com/canonical/mysql-operator/blob/14c06ff88c4e564cd6d098aa213bd03e78e84b52/metadata.yaml#L72-L80) file.
+
+When upgrading your database charm with <code>juju refresh</code>, Juju checks that its version is compatible with the target revision. If not, it stops the upgrade and prevents further changes to keep the installation safe. 
+
+```shell
+~$ juju refresh mysql
+
+Added charm-hub charm "mysql", revision 42 in channel 8.0/stable, to the model
+ERROR Charm feature requirements cannot be met:
+    - charm requires all of the following:
+      - 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](/t/14333) before proceeding with the charm upgrade.

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/11868) if you are interested in the topic.
+
+## Pre-requisits
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/13458)!
+
+## 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-k8s --trust --channel 8.0/edge
+
+juju relate mysql-test-app mysql-router-k8s
+juju relate mysql-router-k8s db1-database
+```
+
+## External Juju clients
+```shell
+juju switch app
+
+juju deploy data-integrator --config database-name=mydatabase
+juju deploy mysql-router-k8s mysql-router-external --trust --channel 8.0/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,100 @@
+# Deploy Async replication
+[note type="caution"]
+**Warning**: This feature is for charm revision `8.0/edge`. Do NOT use it in production!
+
+Contact the [Canonical Data Platform team](/t/11868) if you are interested in this topic.
+[/note]
+
+## 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 --trust --channel=8.0/edge --config profile=testing --config cluster-name=rome --base [email protected]
+
+juju switch lisbon
+juju deploy mysql-k8s db2 --trust --channel=8.0/edge --config profile=testing --config cluster-name=lisbon --base [email protected]
+```
+
+[note]
+**Note**: Remove profile configuration for production deployments. For more information, see our documentation about [Profiles](https://charmhub.io/mysql-k8s/docs/r-profiles).
+[/note]
+
+## Offer
+
+
+Offer asynchronous replication on the Primary cluster (Rome):
+```shell
+juju switch rome
+juju offer db1:replication-offer replication-offer
+```
+
+(Optional) Offer asynchronous replication on StandBy cluster (Lisbon), for the future:
+```shell
+juju switch lisbon
+juju offer db2:replication-offer replication-offer
+``` 
+
+## Consume
+[note type="caution"]
+**Warning**: [Juju unit scaling](/t/9675) is not expected to work during the asynchronous replication setup (between `integrate replication-offer` and `create-replication` calls).
+[/note]
+
+Consume asynchronous replication on planned `StandBy` cluster (Lisbon):
+```shell
+juju switch lisbon
+juju consume rome.replication-offer
+juju integrate replication-offer db2:replication
+```
+
+Once relations are established, cluster Rome will get into Blocked state, waiting for the replication to be created.
+
+To do so, run the action create-replication on rome’s leader unit.
+
+```shell
+juju switch rome
+juju run db1/leader create-replication
+```
+
+(Optional) Consume asynchronous replication on the current `Primary` (Rome), for the future:
+```shell
+juju switch rome
+juju consume lisbon.replication-offer
+``` 
+
+## 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: db1-0.db1-endpoints.rome.svc.cluster.local:3306
+  domainname: cluster-set-bcba09a4d4feb2327fd6f8b0f4ac7a2c
+  globalprimaryinstance: db1-0.db1-endpoints.rome.svc.cluster.local: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 scale-application db1 3 -m rome
+
+juju scale-application db2 3 -m lisbon
+```

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

@@ -0,0 +1,31 @@
+# Switchover / Failover of Async replication
+
+> **WARNING**: it is an '8.0/edge' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11868) if you are interested in the topic.
+
+## Pre-requisits
+
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/13458)!
+
+## 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-to-primary 
+```
+
+## Failover (forced)
+
+[note type="caution"]
+
+**Warning**: this is a **dangerous** operation which can cause the split-brain situation.<br/>It should be executed if Primary cluster is NOT recoverable any longer!<br/>Otherwise please use safe 'switchover' procedure above!
+
+[/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-to-primary force=True
+```
+
+> **Warning**: The `force` will cause the old primary to be invalidated.

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/11868) if you are interested in the topic.
+
+## Pre-requisits
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/13458)!
+
+## 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-k8s  8.0/edge  137  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,61 @@
+# Removal of Async replication
+
+> **WARNING**: it is an '8.0/edge' article. Do NOT use it in production!<br/>Contact [Canonical Data Platform team](/t/11868) if you are interested in the topic.
+
+## Pre-requisits
+
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/13458)!
+
+## Detach Cluster from ClusterSet
+
+> **Note**: It is important to [switchover](/t/13460) 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 replication-offer db2:replication
+
+```
+
+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 replication-offer db1:replication
+
+juju switch lisbon
+
+juju run db2/leader create-replication
+
+```
+
+## 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-contribute.md

@@ -0,0 +1,33 @@
+[note type="caution"]
+:construction: This page is under construction! More details for each section coming soon.
+[/note]
+
+# How to contribute
+
+Charmed MySQL K8s is an open-source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.
+
+This page explains the processes and practices recommended for contributing to this charm's code and documentation.
+
+## Submit a bug or issue 
+* Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-k8s-operator/issues)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+
+## Contribute to the code
+
+Before developing new features or fixes to this charm, you consider [opening an issue on GitHub](https://github.com/canonical/mysql-k8s-operator/issues) explaining your use case.
+
+If you would like to chat with us about your use-cases or proposed implementation, you can reach us at our [Data Platform Matrix channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com).
+
+### Tips for a good contribution
+
+* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
+* All contributions require review before being merged. Code review typically examines
+  * Code quality
+  * Test coverage
+  * User experience for Juju operators of this charm
+
+## Contribute to the documentation
+
+There are several ways to contribute to the documentation:
+* Writing a comment on Discourse
+* Submitting an [issue](https://github.com/canonical/mysql-k8s-operator/issues) on GitHub with the `documentation` label