Skip to content

Commit 4c575b4

Browse files
github-actions[bot]discourse-gatekeeper-docs-bot
github-actions[bot]
and
discourse-gatekeeper-docs-bot
authored
Initial sync of Discourse=>GitHub documentation
Co-authored-by: discourse-gatekeeper-docs-bot <[email protected]>
1 parent a4e98ce commit 4c575b4

36 files changed

+2273
-0
lines changed

‎docs/explanation/e-architecture.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Architecture
2+
3+
[MySQL](https://www.mysql.com/) is the world’s most popular open source database. The “[Charmed MySQL K8s](https://charmhub.io/mysql-k8s)” 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).
4+
5+
## Juju K8s Concept
6+
7+
The charm design leverages the [sidecar](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/#example-1-sidecar-containers) pattern to allow multiple containers in each pod with [Pebble](https://juju.is/docs/sdk/pebble) running as the workload container’s entrypoint.
8+
9+
Pebble is a lightweight, API-driven process supervisor that is responsible for configuring processes to run in a container and controlling those processes throughout the workload lifecycle.
10+
11+
Pebble `services` are configured through [layers](https://github.com/canonical/pebble#layer-specification), and the following containers represent each one a layer forming the effective Pebble configuration, or `pebble plan`:
12+
13+
1. a [charm]() container runs Juju operator code: `juju ssh mysql-k8s/0 bash`
14+
1. a [mysql](https://www.mysql.com/) (workload) container runs the MySQL application along with other services (like monitoring metrics exporters, etc): `juju ssh --container mysql mysql-k8s/0 bash`
15+
16+
As a result, if you run a `kubectl get pods` on a namespace named for the Juju model you’ve deployed the "Charmed MySQL K8s" charm into, you’ll see something like the following:
17+
18+
```shell
19+
NAME READY STATUS RESTARTS AGE
20+
mysql-k8s-0 2/2 Running 0 65m
21+
```
22+
23+
This shows there are 2 containers in the pod: `charm` and `workload` mentioned above.
24+
25+
And if you run `kubectl describe pod mysql-k8s-0`, all the containers will have as Command `/charm/bin/pebble`. That’s because Pebble is responsible for the processes startup as explained above.
26+
27+
<a name="hld"></a>
28+
## HLD (High Level Design)
29+
30+
The "Charmed MySQL K8s" (`workload` container) based on `mysql-image` resource defined in the [charm metadata.yaml](https://github.com/canonical/mysql-k8s-operator/blob/main/metadata.yaml). It is an official Canonical "[charmed-mysql](https://github.com/canonical/charmed-mysql-rock)" [OCI/ROCK](https://ubuntu.com/server/docs/rock-images/introduction) image, which is recursively based on Canonical SNAP “[charmed-mysql](https://snapcraft.io/charmed-mysql)” (read more about the SNAP details [here](/t/11756)).
31+
32+
[Charmcraft](https://juju.is/docs/sdk/install-charmcraft) uploads an image as a [charm resource](https://charmhub.io/mysql-k8s/resources/mysql-image) to [Charmhub](https://charmhub.io/mysql-k8s) during the [publishing](https://github.com/canonical/mysql-k8s-operator/blob/main/.github/workflows/release.yaml#L40-L53), as described in the [Juju SDK How-to guides](https://juju.is/docs/sdk/publishing).
33+
34+
The charm supports Juju deploymed to all Kubernetes environments: [MicroK8s](https://microk8s.io/), [Charmed Kubernetes](https://ubuntu.com/kubernetes/charmed-k8s), [GKE](https://charmhub.io/mysql-k8s/docs/h-deploy-gke), [Amazon EKS](https://aws.amazon.com/eks/), ...
35+
36+
The OCI/ROCK ships the following components:
37+
38+
* MySQL Community Edition (based on SNAP "[charmed-mysql](/t/11756)")
39+
* MySQL Router (based on SNAP "[charmed-mysql](/t/11756)")
40+
* MySQL Shell (based on SNAP "[charmed-mysql](/t/11756)")
41+
* Percona XtraBackup (based on SNAP "[charmed-mysql](/t/11756)")
42+
* Prometheus MySQLd Exporter (based on SNAP "[charmed-mysql](/t/11756)")
43+
* Prometheus MySQL Router Exporter (based on SNAP "[charmed-mysql](/t/11756)")
44+
* Prometheus Grafana dashboards and Loki alert rules are part of the charm revision and missing in SNAP.
45+
46+
SNAP-based ROCK images guaranties the same components versions and functionality between VM and K8s charm flavors.
47+
48+
Pebble runs layers of all the currently enabled services, e.g. monitoring, backups, etc:
49+
```shell
50+
> juju ssh --container mysql mysql-k8s/0 /charm/bin/pebble plan
51+
services:
52+
mysqld_exporter:
53+
summary: mysqld exporter
54+
startup: disabled <= COS Monitoring disabled
55+
override: replace
56+
command: /start-mysqld-exporter.sh
57+
environment:
58+
DATA_SOURCE_NAME: user:password@unix(/var/run/mysqld/mysqld.sock)/
59+
user: mysql
60+
group: mysql
61+
mysqld_safe:
62+
summary: mysqld safe
63+
startup: enabled <= MySQL is up and running
64+
override: replace
65+
command: mysqld_safe
66+
user: mysql
67+
group: mysql
68+
kill-delay: 24h0m0s
69+
```
70+
71+
The `mysqld_safe` is a main MySQL wrapper which is normally up and running right after the charm deployment.
72+
73+
The `mysql-router` used in [Charmed MySQL Router K8s](https://charmhub.io/mysql-router-k8s?channel=8.0/edge) only and should be stopped on [Charmed MySQL K8s](https://charmhub.io/mysql-k8s) deployments.
74+
75+
All `exporter` services are activated after the relation with [COS Monitoring](/t/9981) only.
76+
77+
> **:information_source: Note:** it is possible to star/stop/restart pebble services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
78+
79+
> **:warning: Important:** all pebble resources must be executed under the proper user (defined in user:group options of pebble layer)!
80+
81+
The ROCK "charmed-mysql" also ships list of tools used by charm:
82+
* `mysql` - mysql client to connect `mysqld`.
83+
* `mysqlsh` - new [mysql-shell](https://dev.mysql.com/doc/mysql-shell/8.0/en/) client to configure MySQL cluster.
84+
* `xbcloud` - a tool to download and upload full or part of xbstream archive from/to the cloud.
85+
* `xbstream` - a tool to support simultaneous compression and streaming.
86+
* `xtrabackup` - a tool to backup/restore MySQL DB.
87+
88+
The `mysql` and `mysqlsh` are well known and popular tools to manage MySQL.
89+
The `xtrabackup (xbcloud+xbstream)` used for [MySQL Backups](/t/9653) only to store backups on S3 compatible storage.
90+
91+
<a name="integrations"></a>
92+
## Integrations
93+
94+
### MySQL Router
95+
96+
[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 K8s](https://charmhub.io/mysql-router-k8s)" is an independent charm "Charmed MySQL K8s" can be related with.
97+
98+
### TLS Certificates Operator
99+
100+
[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.
101+
102+
### S3 Integrator
103+
104+
[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.
105+
106+
### Data Integrator
107+
108+
[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.
109+
110+
### MySQL Test App
111+
112+
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.
113+
114+
### Grafana
115+
116+
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/9981) setup.
117+
118+
### Loki
119+
120+
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/9981) setup.
121+
122+
### Prometheus
123+
124+
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/9981) setup.
125+
126+
<a name="lld"></a>
127+
## LLD (Low Level Design)
128+
129+
Please check the charm state machines displayed on [workflow diagrams](/t/10031). The low-level logic is mostly common for both VM and K8s charm flavors.
130+
131+
<!--- TODO: Describe all possible installations? Cross-model/controller? --->
132+
133+
### Juju Events
134+
135+
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”.
136+
137+
For this charm, the following events are observed:
138+
139+
1. [mysql_pebble_ready](https://juju.is/docs/sdk/container-name-pebble-ready-event): informs charm about the availability of the ROCK "charmed-mysql"-based `workload` K8s container. Also performs basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster).
140+
2. [leader-elected](https://juju.is/docs/sdk/leader-elected-event): generate all the secrets to bootstrap the cluster.
141+
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).
142+
6. [update-status](https://juju.is/docs/sdk/update-status-event): Takes care of workload health checks.
143+
<!--- 7. database_storage_detaching: TODO: ops? event?
144+
8. TODO: any other events? relation_joined/changed/created/broken
145+
--->
146+
147+
### Charm Code Overview
148+
149+
The "[src/charm.py](https://github.com/canonical/mysql-k8s-operator/blob/main/src/charm.py)" is the default entry point for a charm and has the [MySQLCharmBase](https://github.com/canonical/mysql-k8s-operator/blob/main/lib/charms/mysql/v0/mysql.py) Python class which inherits from CharmBase.
150+
151+
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).
152+
153+
The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
154+
155+
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/) (of VM flavor of the charm!):
156+
```
157+
charmcraft list-lib mysql
158+
Library name API Patch
159+
backups 0 7
160+
mysql 0 45
161+
s3_helpers 0 4
162+
tls 0 2
163+
```

‎docs/explanation/e-flowcharts.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Charm lifecycle flowcharts
2+
3+
[Click to navigate the mermaid diagram on GitHub](https://github.com/canonical/mysql-k8s-operator/blob/main/docs/explanation/e-flowcharts.md).
4+
5+
```mermaid
6+
flowchart TD
7+
id101([leader_elected]) --> id102[generate\npassword/configs]
8+
id102 --> id103[store peer databag]
9+
id103 --> id104((return))
10+
11+
id201([pebble_ready]) --> id202{if not `configured` \nnor peer relation}
12+
id202 --> id203>defer]
13+
id202 -- else --> id204[add pebble layer]
14+
id204 --> id205[configure mysql\nusers]
15+
id205 --> id206[configure instance\nfor GR]
16+
id206 --> id207{is leader?}
17+
id207 -- no --> id208((return))
18+
id207 -- yes --> id209[create GR cluster]
19+
id209 --> id208
20+
21+
id301([peer_relation_changed\nor\nupdate_status]) --> id302{is waiting\nto join}
22+
id302 -- yes --> id303{is already\nin cluster?}
23+
id303 --> id304[get primary\nfrom any online peer]
24+
id304 --> id305[get current\ncluster node count]
25+
id305 --> id306{is cluster\nat max size}
26+
id306 -- no --> id307{is cluster\ntopology\nchanging}
27+
id307 --> id309[acquire topology\nchange token]
28+
id309 --> id310[join the cluster\nfrom primary]
29+
id310 --> id311[release token]
30+
id306 -- yes --> id308[Set blocked\nand standby]
31+
id302 -- no --> id399((return))
32+
id303 -- yes --> id399
33+
id307 --> id399
34+
id308 --> id399
35+
id311 --> id399
36+
```

‎docs/explanation/e-interfaces.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Interfaces/endpoints
2+
3+
Charmed MySQL K8s supports modern `mysql_client` and legacy `mysql` interfaces (in a backward compatible mode).
4+
5+
**Note:** do NOT relate both modern and legacy interfaces simultaneously!
6+
7+
## Modern interfaces
8+
9+
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/).
10+
11+
### Modern `mysql_client` interface (`database` endpoint):
12+
13+
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:
14+
15+
```shell
16+
# Deploy Charmed MySQL cluster with 3 nodes
17+
juju deploy mysql-k8s -n 3 --trust --channel 8.0
18+
19+
# Deploy the relevant charms, e.g. mysql-test-app
20+
juju deploy mysql-test-app
21+
22+
# Relate MySQL with your application
23+
juju relate mysql-k8s:database mysql-test-app:database
24+
25+
# Check established relation (using mysql_client interface):
26+
juju status --relations
27+
28+
# Example of the properly established relation:
29+
# > Relation provider Requirer Interface Type
30+
# > mysql-k8s:database mysql-test-app:database mysql_client regular
31+
```
32+
Find all details about default and extra DB user roles in “[Charm Users explanations](/t/10791)”.
33+
34+
**Note:** In order to relate with this charm, every table created by the related 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.
35+
36+
## Legacy interfaces
37+
38+
**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/11236)" document.
39+
40+
### Legacy `mysql` interface (`mysql` and `mysql-root` endpoints):
41+
42+
This charm supports legacy interface `mysql` (endpoint `mysql` and `mysql-root`). 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):
43+
44+
```shell
45+
juju deploy mysql-k8s --trust --channel 8.0
46+
juju config mysql-k8s mysql-interface-database=wordpress mysql-interface-user=wordpress
47+
juju deploy wordpress-k8s
48+
juju relate mysql-k8s:mysql wordpress-k8s:db
49+
```
50+
51+
**Note:** The endpoint `mysql-root` provides the same legacy interface `mysql` with MySQL root-level privileges. It is NOT recommended to use it from security point of view.

0 commit comments

Comments
 (0)