'new: docs/how-to/h-contribute.md,docs/how-to/h-upgrade/h-rollback-major.md,docs/how-to/h-develop/h-develop-mycharm.md,docs/reference/r-releases-group/r-releases-rev240.md,docs/how-to/h-upgrade/h-juju-upgrade.md,docs/how-to/h-upgrade/h-rollback-minor.md,docs/explanation/e-logs.md,docs/tutorial/t-setup-environment.md,docs/how-to/h-develop/h-develop-migratedataby/h-develop-backuprestore.md,docs/how-to/h-async/h-async-removal.md,docs/how-to/h-develop/h-legacy-charm.md,docs/how-to/h-async/h-async-recovery.md,docs/how-to/h-setup/h-manage-app.md,docs/how-to/h-to-manage-backups/h-configure-s3-radosgw.md,docs/how-to/h-upgrade/h-upgrade-minor.md,docs/how-to/h-upgrade/h-upgrade-major.md,docs/index.md,docs/explanation/e-juju.md,docs/how-to/h-monitoring/h-enable-tracing.md,docs/reference/r-testing.md,docs/how-to/h-to-manage-backups/h-create-and-list-backups.md,docs/tutorial/t-manage-passwords.md,docs/explanation/e-legacy-charm.md,docs/how-to/h-async/h-async-deployment.md,docs/tutorial/t-managing-units.md,docs/how-to/h-to-manage-backups/h-restore-backup.md,docs/tutorial/t-cleanup-environment.md,docs/how-to/h-develop/h-troubleshooting.md,docs/how-to/h-upgrade/h-upgrade-intro.md,docs/explanation/e-users.md,docs/how-to/h-setup/h-enable-encryption.md,docs/how-to/h-async/h-async-failover.md,docs/how-to/h-develop/h-develop-migratedataby/h-develop-mysqldump.md,docs/how-to/h-monitoring/h-enable-monitoring.md,docs/reference/r-contacts.md,docs/how-to/h-setup/h-deploy-maas.md,docs/reference/r-releases-group/r-releases-rev151.md,docs/tutorial/t-overview.md,docs/how-to/h-develop/h-develop-intro.md,docs/how-to/h-to-manage-backups/h-migrate-cluster-via-restore.md,docs/how-to/h-setup/h-deploy-lxd.md,docs/how-to/h-async/h-async-clients.md,docs/reference/r-releases-group/r-releases.md,docs/tutorial/t-enable-security.md,docs/reference/r-requirements.md,docs/explanation/e-architecture.md,docs/reference/r-profiles.md,docs/how-to/h-setup/h-manage-units.md,docs/how-to/h-develop/h-develop-migratedataby/h-develop-mydumper.md,docs/tutorial/t-integrations.md,docs/reference/r-releases-group/r-releases-rev196.md,docs/explanation/e-statuses.md,docs/tutorial/t-deploy-charm.md,docs/explanation/e-interfaces.md,docs/how-to/h-to-manage-backups/h-configure-s3-aws.md' (#481)

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

Author: github-actions[bot]

docs/explanation/e-architecture.md

@@ -0,0 +1,133 @@
+# Architecture
+
+[MySQL](https://www.mysql.com/) is the world’s most popular open source database. The "[Charmed MySQL](https://charmhub.io/mysql)" is a Juju-based operator to deploy and support MySQL from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/), it is based on the [MySQL Community Edition](https://www.mysql.com/products/community/) using the built-in cluster functionality: [MySQL InnoDB ClusterSet](https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-clusterset.html).
+
+<a name="hld"></a>
+## HLD (High Level Design)
+
+The charm design leverages on the SNAP “[charmed-mysql](https://snapcraft.io/charmed-mysql)” which is deployed by Juju on the specified VM/MAAS/bare-metal machine based on Ubuntu Jammy/22.04. SNAP allows to run MySQL service(s) in a secure and isolated environment ([strict confinement](https://ubuntu.com/blog/demystifying-snap-confinement)). The installed SNAP:
+```
+> juju ssh mysql/0
+> snap list charmed-mysql
+Name           Version  Rev  Tracking       Publisher        Notes
+charmed-mysql  8.0.34   69   latest/stable  dataplatformbot  held
+```
+
+The SNAP ships the following components:
+
+* MySQL Community Edition (based on Ubuntu APT package "[mysql-server-8.0](https://packages.ubuntu.com/jammy/mysql-server-8.0)") 
+* MySQL Router (based on Ubuntu APT package "[mysql-router](https://packages.ubuntu.com/jammy/mysql-router)")
+* MySQL Shell (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/mysql-shell))
+* Percona XtraBackup (based on Canonical  [backport](https://launchpad.net/~data-platform/+archive/ubuntu/xtrabackup))
+* Prometheus MySQLd Exporter (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/mysqld-exporter))
+* Prometheus MySQL Router Exporter (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/mysqlrouter-exporter))
+* Prometheus Grafana dashboards and Loki alert rules are part of the charm revision and missing in SNAP.
+
+Versions of all the components above are carefully chosen to fit functionality of each other.
+
+The Charmed MySQL unit consisting of a several services which are enabled/activated accordingly to the setup: 
+
+```
+> snap services charmed-mysql
+Service                              Startup   Current   Notes
+charmed-mysql.mysqld                 enabled   active    -
+charmed-mysql.mysqld-exporter        disabled  inactive  -
+charmed-mysql.mysqlrouter-service    disabled  inactive  -
+charmed-mysql.mysqlrouterd-exporter  disabled  inactive  -
+```
+
+The `mysqld` snap service is a main MySQL instance which is normally up and running right after the charm deployment.
+
+The `mysql-router` snap service used in [Charmed MySQL Router](https://charmhub.io/mysql-router?channel=dpe/edge) only and should be stopped on [Charmed MySQL](https://charmhub.io/mysql) deployments.
+
+All `exporter` services are activated after the relation with [COS Monitoring](/t/9900) only.
+
+> **:information_source: Note:** it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
+
+> **:warning: Important:** all snap resources must be executed under the special user `snapd_daemon` only!
+
+The snap "charmed-mysql" also ships list of tools used by charm:
+* `charmed-mysql.mysql` (alias `mysql`) - mysql client to connect `mysqld`.
+* `charmed-mysql.mysqlsh` - new [mysql-shell](https://dev.mysql.com/doc/mysql-shell/8.0/en/) client to configure MySQL cluster.
+* `charmed-mysql.xbcloud` - a tool to download and upload full or part of xbstream archive from/to the cloud.
+* `charmed-mysql.xbstream` - a tool to support simultaneous compression and streaming.
+* `charmed-mysql.xtrabackup` - a tool to backup/restore MySQL DB.
+
+The `mysql` and `mysqlsh` are well known and popular tools to manage MySQL.
+The `xtrabackup (xbcloud+xbstream)` used for [MySQL Backups](/t/9896) only to store backups on S3 compatible storage.
+
+<a name="integrations"></a>
+## Integrations
+
+### MySQL Router
+
+[MySQL Router](https://dev.mysql.com/doc/mysql-router/8.0/en/) is part of MySQL InnoDB Cluster, and is lightweight middle-ware that provides transparent routing between your application and back-end MySQL Servers. The "[Charmed MySQL Router](https://charmhub.io/mysql-router)" is an independent charm "Charmed MySQL" can be related with.
+
+### TLS Certificates Operator
+
+[TLS Certificates](https://charmhub.io/tls-certificates-operator) charm responsible for distributing certificates through relationship. Certificates are provided by the operator through Juju configs. For the playground deployments, the [self-signed operator](https://charmhub.io/self-signed-certificates) is available as well.
+
+### S3 Integrator
+
+[S3 Integrator](https://charmhub.io/s3-integrator) is an integrator charm for providing S3 credentials to Charmed MySQL which seek to access shared S3 data. Store the credentials centrally in the integrator charm and relate consumer charms as needed.
+
+### Data Integrator
+
+[Data Integrator](https://charmhub.io/data-integrator) charm is a solution to request DB credentials for non-native Juju applications. Not all applications implement a data_interfaces relation but allow setting credentials via config. Also, some of the applications are run outside of juju. This integrator charm allows receiving credentials which can be passed into application config directly without implementing juju-native relation.
+
+### MySQL Test App
+
+The charm "[MySQL Test App](https://charmhub.io/mysql-test-app)" is a Canonical test application to validate the charm installation / functionality and perform the basic performance tests.
+
+### Grafana
+
+Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/t/9900) setup.
+
+### Loki
+
+Loki is an open-source fully-featured logging system. This charms is shipped with support for the [Loki Operator](https://charmhub.io/loki-k8s) to collect the generated logs. Please follow [COS Monitoring](/t/9900) setup.
+
+### Prometheus
+
+Prometheus is an open-source systems monitoring and alerting toolkit with a dimensional data model, flexible query language, efficient time series database and modern alerting approach. This charm is shipped with a Prometheus exporters, alerts and support for integrating with the [Prometheus Operator](https://charmhub.io/prometheus-k8s) to automatically scrape the targets. Please follow [COS Monitoring](/t/9900) setup.
+
+<a name="lld"></a>
+## LLD (Low Level Design)
+
+Please check the charm state machines displayed on [workflow diagrams](/t/10031). The low-level logic is mostly common for both VM and K8s charms.
+
+<!--- TODO: Describe all possible installations? Cross-model/controller? --->
+
+### Juju Events
+
+Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): “an event is a data structure that encapsulates part of the execution context of a charm”.
+
+For this charm, the following events are observed:
+
+1. [on_install](https://juju.is/docs/sdk/install-event): install the snap "charmed-mysql" and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
+2. [leader-elected](https://juju.is/docs/sdk/leader-elected-event): generate all the secrets to bootstrap the cluster.
+3. [leader-settings-changed](https://juju.is/docs/sdk/leader-settings-changed-event): Handle the leader settings changed event.
+4. [start](https://juju.is/docs/sdk/start-event): Init/setting up the cluster node.
+5. [config_changed](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
+6. [update-status](https://juju.is/docs/sdk/update-status-event): Takes care of workload health checks.
+<!--- 7. database_storage_detaching: TODO: ops? event?
+8. TODO: any other events?
+--->
+
+### Charm Code Overview
+
+The "[src/charm.py](https://github.com/canonical/mysql-operator/blob/main/src/charm.py)" is the default entry point for a charm and has the [MySQLCharmBase](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py) Python class which inherits from CharmBase.
+
+CharmBase is the base class from which all Charms are formed, defined by [Ops](https://juju.is/docs/sdk/ops) (Python framework for developing charms). See more information in [Charm](https://juju.is/docs/sdk/constructs#heading--charm).
+
+The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
+
+The VM and K8s charm flavors shares the codebase via [charm libraries](https://juju.is/docs/sdk/libraries) in '[lib/charms/mysql/v0/](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/)':
+```
+charmcraft list-lib mysql
+Library name    API    Patch                                                                                                                                                                                                                          
+backups         0      7                                                                                                                                                                                                                              
+mysql           0      45                                                                                                                                                                                                                             
+s3_helpers      0      4                                                                                                                                                                                                                              
+tls             0      2                                     
+```

docs/explanation/e-interfaces.md

@@ -0,0 +1,77 @@
+# Interfaces/endpoints
+> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju integrate` with `juju relate` for Juju 2.9.
+
+Charmed MySQL VM supports modern `mysql_client` and legacy `mysql`, `mysql-shared`, `mysql-router` interfaces (in a backward compatible mode).
+
+**Note:** do NOT integrate (relate) both modern and legacy interfaces simultaneously.
+
+## Modern relations
+
+This charm provides 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 integrate` via endpoint `database`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example:
+
+```shell
+# Deploy Charmed MySQL cluster with 3 nodes
+juju deploy mysql -n 3 --channel 8.0
+
+# Deploy the relevant charms, e.g. mysql-test-app
+juju deploy mysql-test-app
+
+# Integrate (relate) MySQL with your application
+juju integrate mysql:database mysql-test-app:database
+
+# Check established relation (using mysql_client interface):
+juju status --relations
+
+# Example of the properly established relation:
+# > Relation provider   Requirer                 Interface     Type
+# > mysql:database      mysql-test-app:database  mysql_client  regular
+```
+
+Find all details about default and extra DB user roles in “[Charm Users explanations](/t/10789)”.
+
+**Note:** In order to integrate with this charm, every table created by the integrated 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.
+
+## Legacy relations
+
+**Note:** Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided. Check the legacy interface implementation limitations in the "[Legacy charm](/t/10788)" document.
+
+This charm supports several legacy interfaces, e.g. `mysql`, `mysql-shared`, `mysql-router`. They were used in some legacy charms in [cross-model relations](https://juju.is/docs/olm/cross-model-integration).
+
+### `mysql` interface (`mysql` endpoint)
+
+It was a popular interface used by some legacy charms (e.g. "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)"), often in [cross-model relations](https://juju.is/docs/olm/cross-model-integration):
+
+```shell
+juju deploy mysql --channel 8.0
+juju config mysql mysql-interface-database=mediawiki mysql-interface-user=mediawiki
+juju deploy mediawiki
+juju integrate mysql:mysql mediawiki:db
+```
+
+### `mysql-router` interface (`db-router` endpoint)
+
+It is a relation that one uses with the [mysql router](https://charmhub.io/mysql-router) charm. The following commands can be executed to deploy and integrate to the keystone charm:
+
+```shell
+juju deploy mysql --channel 8.0
+juju deploy mysql-router --series focal
+juju deploy keystone --series focal
+juju integrate mysql-router keystone
+juju integrate mysql:db-router mysql-router:db-router
+```
+
+**Note:** pay attention to deploy identical [series](https://juju.is/docs/olm/deploy-an-application-with-a-specific-series) for `keystone` and `mysql-router` applications (due to the [subordinate](https://juju.is/docs/sdk/charm-types#heading--subordinate-charms) charm nature of `mysql-router`).
+
+### `mysql-shared` interface (`shared-db` endpoint)
+
+It is a relation that one uses when the application needs to connect directly to the database cluster. It is supported by various legacy charms, e.g. [mysql-innodb-cluster](https://charmhub.io/mysql-innodb-cluster). The following commands can be executed to deploy and integrate to the keystone charm:
+
+```shell
+juju deploy mysql --channel 8.0
+juju deploy keystone --series focal
+juju integrate keystone:shared-db mysql:shared-db
+```

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) 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:database mysql-test-app
+
+juju run mysql/leader get-password 
+```
+### Juju 2.9.x:
+```shell
+juju relate mysql:database mysql-test-app
+
+juju run-action --wait mysql/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/11421). 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/14325) before proceeding with the charm upgrade.