Skip to content

Commit

Permalink
[discourse-gatekeeper] Migrate charm docs (#353)
Browse files Browse the repository at this point in the history 
* 'modified: docs/tutorial/t-manage-passwords.md,docs/tutorial/t-integrations.md,docs/how-to/h-manage-app.md,docs/how-to/h-restore-backup.md,docs/how-to/h-enable-monitoring.md,docs/index.md,docs/tutorial/t-overview.md,docs/how-to/h-configure-s3-radosgw.md,docs/how-to/h-migrate-cluster-via-restore.md,docs/how-to/h-configure-s3-aws.md,docs/tutorial/t-enable-security.md,docs/how-to/h-manage-units.md,docs/tutorial/t-managing-units.md,docs/tutorial/t-deploy-mysql.md,docs/tutorial/t-setup-environment.md // new: docs/explanation/e-legacy-charm.md,docs/reference/r-contacts.md,docs/reference/r-requirements.md,docs/how-to/h-develop/h-develop-migratedataby/h-develop-backuprestore.md,docs/how-to/h-upgrade/h-rollback-minor.md,docs/explanation/e-logs.md,docs/how-to/h-develop/h-develop-mycharm.md,docs/reference/r-releases-group/r-releases.md,docs/explanation/e-users.md,docs/how-to/h-setup/h-async-replication.md,docs/explanation/e-juju-details.md,docs/reference/r-releases-group/r-releases-rev196.md,docs/how-to/h-upgrade/h-upgrade-major.md,docs/how-to/h-develop/h-develop-migratedataby/h-develop-mydumper.md,docs/explanation/e-architecture.md,docs/explanation/e-statuses.md,docs/how-to/h-develop/h-develop-migratedataby/h-develop-mysqldump.md,docs/reference/r-testing.md,docs/how-to/h-setup/h-enable-encryption.md,docs/how-to/h-upgrade/h-upgrade-minor.md,docs/reference/r-releases-group/r-releases-rev151.md,docs/explanation/e-interfaces.md,docs/how-to/h-upgrade/h-upgrade-intro.md,docs/how-to/h-upgrade/h-rollback-major.md,docs/how-to/h-develop/h-develop-intro.md,docs/how-to/h-setup/h-deploy-lxd.md,docs/how-to/h-develop/h-troubleshooting.md,docs/how-to/h-to-manage-backups/h-create-and-list-backups.md,docs/how-to/h-develop/h-legacy-charm.md,docs/reference/r-profiles.md // removed: docs/reference/.gitkeep,docs/how-to/h-enable-encryption.md,docs/explanation/.gitkeep,docs/how-to/h-create-and-list-backups.md'

* 'modified: docs/index.md'

---------

Co-authored-by: upload-charms-docs-bot <[email protected]>
  • Loading branch information
@github-actions
github-actions[bot] and upload-charms-docs-bot authored Nov 29, 2023
1 parent f8f49dd commit dfcf8e7
Show file tree
Hide file tree
Showing 49 changed files with 2,266 additions and 320 deletions.
Empty file removed docs/explanation/.gitkeep
View file
Empty file.
133 changes: 133 additions & 0 deletions docs/explanation/e-architecture.md
View file
Original file line number Diff line number Diff line change
@@ -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
```
75 changes: 75 additions & 0 deletions docs/explanation/e-interfaces.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# 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
```

**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.

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
```
43 changes: 43 additions & 0 deletions docs/explanation/e-juju-details.md
View file
Original file line number Diff line number Diff line change
@@ -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) 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: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
```
> :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)
Loading

0 comments on commit dfcf8e7

Please sign in to comment.