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

This pull request was autogenerated by discourse-gatekeeper to migrate
existing documentation from server to the git repository.

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

Author: github-actions[bot]

docs/explanation/e-interfaces.md

@@ -0,0 +1,33 @@
+# Interfaces/endpoints
+
+MySQL Router K8s supports modern ['mysql_client'](https://github.com/canonical/charm-relation-interfaces) interface. Applications can easily connect MySQL using ['data_interfaces'](https://charmhub.io/data-platform-libs/libraries/data_interfaces) library from ['data-platform-libs'](https://github.com/canonical/data-platform-libs/).
+
+### Modern `mysql_client` interface (`database` endpoint):
+
+Adding a relation is accomplished with `juju relate` (or `juju integrate` for Juju 3.x) via endpoint `database`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example:
+
+```shell
+# Deploy Charmed MySQL K8s and MySQL Router K8s clusters with 3 nodes each
+juju deploy mysql-k8s -n 3 --trust
+juju deploy mysql-router-k8s -n 3 --trust --channel 8.0
+
+# Deploy the relevant charms, e.g. mysql-test-app
+juju deploy mysql-test-app
+
+# Relate all applications
+juju integrate mysql-k8s mysql-router-k8s
+juju integrate mysql-router-k8s:database mysql-test-app
+
+# Check established relation (using mysql_client interface):
+juju status --relations
+
+# Example of the properly established relation:
+# > Integration provider                 Requirer                             Interface           Type     Message
+# > mysql-k8s:database                   mysql-router-k8s:backend-database    mysql_client        regular
+# > mysql-router-k8s:database            mysql-test-app:database              mysql_client        regular         
+# > ...
+```
+
+**Note:** In order to relate with Charmed MySQL K8s, every table created by the client application must have a primary key. This is required by the [group replication plugin](https://dev.mysql.com/doc/refman/8.0/en/group-replication-requirements.html) enabled in this charm.
+
+See all the charm interfaces [here](https://charmhub.io/mysql-router-k8s/integrations).

docs/explanation/e-juju-details.md

@@ -0,0 +1,43 @@
+# Juju tech details
+
+[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-router-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)
+
+## Breaking changes between Juju 2.9.x and 3.x
+
+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-router-k8s:database mysql-test-app
+
+juju run mysql-k8s/leader get-password 
+```
+### Juju 2.9.x:
+```shell
+juju relate mysql-router-k8s:database mysql-test-app
+
+juju run-action --wait mysql-k8s/leader get-password
+```
+> :tipping_hand_man: [The document based on OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x)

docs/explanation/e-statuses.md

@@ -0,0 +1,20 @@
+# Charm Statuses
+
+> :warning: **WARNING** : it is an work-in-progress article. Do NOT use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic.
+
+The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses:
+
+| Juju Status | Message | Expectations | Actions |
+|-------|-------|-------|-------|
+| **active** | any | Normal charm operations | No actions required |
+| **waiting** | any | Charm is waiting for relations to be finished | No actions required |
+| **maintenance** | any | Charm is performing the internal maintenance (e.g. re-configuration) | No actions required |
+| **blocked** | any | The manual user activity is required! | Follow the message hints (see below) |
+| **blocked** | Missing relation: ...  | Normal behavior, charm needs all relations to work. | Follow the hint to establish a proper relation. |
+| **blocked** | Router was manually removed from MySQL ClusterSet. Remove & re-deploy unit | Scale-down temporary message OR split-brain for the unknown reason. | Wait to finish scale-down or remove and re-deploy unit if the message is persistent.|
+| **blocked** | ... app requested unsupported extra user role on database endpoint | Unsupported [role](https://charmhub.io/data-integrator/configure#extra-user-roles) requested. | Use supported extra-user-role. |
+| **blocked** | Upgrade incompatible. Rollback to previous revision with `juju refresh` | Incompatible charm channel/revision chosen. | [Rollback](/t/12239) the charm. |
+| **blocked** | Upgrading. Verify highest unit is healthy & run `resume-upgrade ` action. To rollback, `juju refresh` to last revision | Normal behavior, application is being upgraded and waiting for user confirmation to continue or rollback | [Continue upgrade](/t/12238) or [rollback](/t/12239). |
+| **error** | any | An unhanded internal error happened | Read the message hint and check the debug log to see the exception. Execute `juju resolve <error_unit/0>` after addressing the root of the error state |
+| **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible |
+| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent |

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

@@ -0,0 +1,35 @@
+# Deploy MySQL Router K8s
+
+Please follow the [MySQL Router K8s Tutorial](/t/12176) for technical details and explanations.
+
+Short story for your Ubuntu 22.04 LTS (`Wordpress` used as an client example for `MySQL Router`:
+```shell
+sudo snap install multipass
+multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs
+multipass shell my-vm
+
+juju add-model wordpress-demo
+juju deploy mysql-k8s --channel 8.0/stable --trust # --config profile=testing
+juju deploy mysql-router-k8s --channel 8.0/stable --trust
+
+juju integrate mysql-k8s mysql-router-k8s
+
+juju status --watch 1s
+```
+
+The expected result:
+```shell 
+Model           Controller  Cloud/Region        Version  SLA          Timestamp
+wordpress-demo  microk8s    microk8s/localhost  3.1.6    unsupported  14:39:27+02:00
+
+App               Version                  Status   Scale  Charm             Channel     Rev  Address         Exposed  Message
+mysql-k8s         8.0.34-0ubuntu0.22.04.1  active       1  mysql-k8s         8.0/stable   99  10.152.183.189  no       
+mysql-router-k8s  8.0.34-0ubuntu0.22.04.1  blocked      1  mysql-router-k8s  8.0/stable   69  10.152.183.81   no       Missing relation: database
+
+Unit                 Workload  Agent  Address     Ports  Message
+mysql-k8s/0*         active    idle   10.1.12.61         Primary
+mysql-router-k8s/0*  active    idle   10.1.12.16         
+```
+The charm MySQL Router K8s is now waiting for relations with a client application, e.g. [mysql-test-app](https://charmhub.io/mysql-test-app), [wordpress](https://charmhub.io/wordpress-k8s), ...
+
+Check the [Testing](/t/12234) reference to test your deployment.

docs/how-to/h-setup/h-enable-encryption.md

@@ -0,0 +1,64 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.1`
+
+If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to enable TLS encryption
+
+<!---[Update and add to explanation]
+MySQL Router will enable encrypted connections by default with self generated certificates. Though also by default, connecting clients can disable encryption by setting the connection ssl-mode as disabled.
+When related with the `tls-certificates-operator` the charmed operator for MySQL Router will require that every client connection (new and running connections) use encryption, rendering an error when attempting to establish an unencrypted connection.-->
+
+This guide will show how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example.
+
+[note type="caution"]
+**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
+
+Check [this guide](/t/11664) for an overview of the TLS certificates charms available. 
+[/note]
+
+---
+
+## Enable TLS
+
+First, deploy the TLS charm:
+```shell
+juju deploy self-signed-certificates
+```
+To enable TLS, integrate the two applications:
+```shell
+juju integrate self-signed-certificates mysql-router-k8s
+```
+
+## Manage keys
+
+Updates to private keys for certificate signing requests (CSR) can be made via the `set-tls-private-key` action. Note that passing keys to external/internal keys should *only be done with* `base64 -w0`, *not* `cat`.
+
+With three replicas, this schema should be followed:
+
+Generate a shared internal (private) key:
+```shell
+openssl genrsa -out internal-key.pem 3072
+```
+
+Apply the newly generated internal key on each `juju` unit:
+```shell
+juju run mysql-router-k8s/0 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
+juju run mysql-router-k8s/1 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
+juju run mysql-router-k8s/2 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
+```
+
+Updates can also be done with auto-generated keys with:
+
+```shell
+juju run mysql-router-k8s/0 set-tls-private-key
+juju run mysql-router-k8s/1 set-tls-private-key
+juju run mysql-router-k8s/2 set-tls-private-key
+```
+
+## Disable TLS
+Disable TLS by removing the integration:
+```shell
+juju remove-relation self-signed-certificates mysql-router-k8s
+```

docs/how-to/h-setup/h-manage-app.md

@@ -0,0 +1,34 @@
+# How to manage related applications
+
+## Modern `mysql_client` interface:
+
+Relations to new applications are supported via the "[mysql_client](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/mysql_client/v0/README.md)" interface. To create a relation:
+
+```shell
+juju relate mysql-router-k8s application
+```
+
+To remove a relation:
+
+```shell
+juju remove-relation mysql-router-k8s application
+```
+
+All listed on CharmHub applications are available [here](https://charmhub.io/mysql-router-k8s/integrations), e.g.:
+ * [mysql-test-app](https://charmhub.io/mysql-test-app)
+ * [wordpress-k8s](https://charmhub.io/wordpress-k8s)
+ * [slurmdbd](https://charmhub.io/slurmdbd)
+
+## Legacy `mysql` interface:
+
+This charm does NOT support legacy `mysql` interface.
+
+## Internal operator user
+
+To rotate the internal router passwords, the relation with backend-database should be removed and related again. That process will generate a new user and password for the application, while retaining the requested database and data.
+
+```shell
+juju remove-relation mysql-k8s mysql-router-k8s
+
+juju integrate mysql-k8s mysql-router-k8s
+```

docs/how-to/h-setup/h-manage-units.md

@@ -0,0 +1,20 @@
+# How to deploy and manage units
+
+## Basic Usage
+
+To deploy a single unit of MySQL Router using its default configuration
+```shell
+juju deploy mysql-router-k8s --channel 8.0 --trust
+```
+
+To deploy MySQL Router in high-availability mode, specify the number of desired units with the `-n` option.
+```shell
+juju deploy mysql-router-k8s --channel 8.0 --trust -n <number_of_replicas>
+```
+
+## Scaling
+
+Both scaling-up and scaling-down operations are performed using `juju scale-application`:
+```shell
+juju scale-application mysql-router-k8s <desired_num_of_units>
+```

docs/how-to/h-upgrade/h-rollback-major.md

@@ -0,0 +1,5 @@
+# Major Rollback
+
+> :information_source: **Example**: MySQL Router 9.0 -> MySQL Router 8.0
+
+Currently, the charm supports MySQL Router 8.0 only; therefore, minor rollbacks are only possible. Canonical is NOT planning to support in-place rollbacks for the major MySQL Router version change as the old MySQL cluster installation with old MySQL Router will stay nearby and can be reused for the rollback.

docs/how-to/h-upgrade/h-rollback-minor.md

@@ -0,0 +1,44 @@
+# Minor Rollback
+
+> :information_source: **Example**: MySQL Router 8.0.34 -> MySQL Router 8.0.33<br/>
+(including simple charm revision bump: from revision 43 to revision 42)
+
+> **:warning: WARNING**: do NOT trigger `rollback` during the **running** `upgrade` action! It may cause unpredictable MySQL Cluster and/or MySQL Router state!
+
+## Minor rollback steps
+1. **Rollback**. Perform the charm rollback using `juju refresh`. The unit with the maximal ordinal will be rolled back first, and the rollback will continue for the entire application.
+2. **Check**. Make sure the charm and cluster are in healthy state again.
+
+## Manual Rollback
+
+After a `juju refresh`, case there any version incompatibilities in charm revisions or it dependencies, or any other unexpected failure in the upgrade process, the upgrade process will be halted an enter a failure state.
+
+Although the underlying MySQL Cluster and MySQL Router continue to work, it’s important to rollback the charm to previous revision so an update can be later attempted after a further inspection of the failure.
+
+To execute a rollback we take the same procedure as the upgrade, the difference being the charm revision to upgrade to. In case of this tutorial example, one would refresh the charm back to revision `88`, the steps being:
+
+## Step 1: Rollback
+
+When using the charm from charmhub:
+
+```shell
+juju refresh mysql-router-k8s --revision=88 --trust
+```
+
+When deploying from a local charm file, you need to have the previous revision's `.charm` file and the `mysql-image` resource. Then, run:
+
+```shell
+juju refresh mysql-router-k8s --trust --path=<path_to_charm_file> \
+       --resource mysql-router-image=<image>
+```
+The resource reference can be found under the `upstream-source` key in the charm's `metadata.yaml` file. You can access this file by:
+* Simply unpacking the `.charm` file
+* Finding the corresponding [release](https://github.com/canonical/mysql-router-k8s-operator/releases) in the charm's GitHub repository and navigating to `metadata.yaml`.
+
+After the refresh command, the `juju` controller revision for the application will be back in sync with the running MySQL Router K8s revision.
+
+## Step 2: Check
+
+Future [improvement are planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state on pod/cluster on a low level.
+
+For now, use `juju status` to check the cluster [state](/t/11866).

docs/how-to/h-upgrade/h-upgrade-intro.md

@@ -0,0 +1,17 @@
+# MySQL Router K8s Upgrade
+
+Please choose the appropriate upgrade/rollback tutorial.
+
+Migration:
+
+* [Major upgrade](/t/12236), e.g. MySQL Router 8.0 -> MySQL Router 9.0.
+
+* [Major rollback](/t/12237), e.g. MySQL Router 9.0 -> MySQL Router 8.0.
+
+In-place minor upgrade:
+
+* [Minor upgrade](/t/12238), e.g. MySQL Router 8.0.33 -> MySQL Router 8.0.34<br/>
+(including charm revision bump 99 -> 102).
+
+* [Minor rollback](/t/12239), e.g. MySQL Router 8.0.34 -> MySQL Router 8.0.33<br/>
+(including charm revision return 102 -> 99).