Architecture¶

MySQL is the world’s most popular open source database. Charmed MySQL is a Juju-based operator to deploy and support MySQL from day 0 to day 2. It is based on the MySQL Community Edition using the built-in cluster functionality: MySQL InnoDB ClusterSet.

High-level design¶

Charmed MySQL is developed for deployment on machine clouds or Kubernetes. Although both versions are extremely similar in functionality, there are some key differences in their architecture.

Machine charm¶

Charmed MySQL VM leverages the charmed-mysql snap 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).

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”)
MySQL Router (based on Ubuntu APT package “mysql-router”)
MySQL Shell (based on Canonical backport)
Percona XtraBackup (based on Canonical backport)
Prometheus MySQLd Exporter (based on Canonical backport)
Prometheus MySQL Router Exporter (based on Canonical backport)
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 only and should be stopped on Charmed MySQL deployments.

All exporter services are activated only after relating with COS.

Caution

It is possible to start, stop, and restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
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 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 only to store backups on S3 compatible storage.

Kubernetes charm¶

Charmed MySQL K8s leverages the sidecar pattern to allow multiple containers in each pod with Pebble running as the workload container’s entrypoint.

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.

Pebble services are configured through layers, and the following containers represent each one a layer forming the effective Pebble configuration, or pebble plan:

a charm container runs Juju operator code: juju ssh mysql-k8s/0 bash
a mysql (workload) container runs the MySQL application along with other services (like monitoring metrics exporters, etc): juju ssh --container mysql mysql-k8s/0 bash

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:

NAME           READY   STATUS    RESTARTS   AGE
mysql-k8s-0    2/2     Running   0          65m

This shows there are 2 containers in the pod: charm and workload mentioned above.

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.

The Charmed MySQL K8s (workload container) based on the mysql-image resource defined in the charm metadata.yaml. It is an official Canonical “charmed-mysql” OCI/ROCK image, which is recursively based on Canonical SNAP “charmed-mysql” (read more about the snap details in Machine charm).

Charmcraft uploads an image as a charm resource to Charmhub during the publishing, as described in the Juju SDK How-to guides.

The charm supports Juju deployment to all Kubernetes environments: MicroK8s, Charmed Kubernetes, GKE, Amazon EKS, …

The OCI/ROCK ships the following components based on the charmed-mysql snap:

MySQL Community Edition
MySQL Router
MySQL Shell
Percona XtraBackup
Prometheus MySQLd Exporter
Prometheus MySQL Router Exporter

Prometheus Grafana dashboards and Loki alert rules are part of the charm revision, but missing in the snap.

SNAP-based ROCK images guaranties the same components versions and functionality between VM and K8s charm flavors.

Pebble runs layers of all the currently enabled services, e.g. monitoring, backups, etc:

> juju ssh --container mysql mysql-k8s/0 /charm/bin/pebble plan
services:
    mysqld_exporter:
        summary: mysqld exporter
        startup: disabled                   <= COS Monitoring disabled
        override: replace
        command: /start-mysqld-exporter.sh
        environment:
            DATA_SOURCE_NAME: user:password@unix(/var/run/mysqld/mysqld.sock)/
        user: mysql
        group: mysql
    mysqld_safe:
        summary: mysqld safe
        startup: enabled                    <= MySQL is up and running
        override: replace
        command: mysqld_safe
        user: mysql
        group: mysql
        kill-delay: 24h0m0s

The mysqld_safe is a main MySQL wrapper which is normally up and running right after the charm deployment.

The mysql-router used in Charmed MySQL Router K8s only and should be stopped on Charmed MySQL K8s deployments.

All exporter services are activated only after relating with COS.

Caution

It is possible to start, stop, and restart pebble services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
All pebble resources must be executed under the proper user (defined in user:group options of pebble layer)!

The ROCK “charmed-mysql” also ships list of tools used by charm:

mysql - mysql client to connect mysqld.
mysqlsh - new mysql-shell client to configure MySQL cluster.
xbcloud - a tool to download and upload full or part of xbstream archive from/to the cloud.
xbstream - a tool to support simultaneous compression and streaming.
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) is used only to store backups on S3 compatible storage.

Integrations¶

MySQL Router¶

MySQL Router is part of MySQL InnoDB Cluster, and is lightweight middle-ware that provides transparent routing between your application and back-end MySQL Servers. The MySQL Router charm (VM | K8s) is an independent charm that can be related with MySQL.

TLS Certificates Operator¶

The TLS Certificates charm is responsible for distributing certificates through relationship. Certificates are provided by the operator through Juju configs. For playground deployments, the self-signed operator is available as well.

S3 Integrator¶

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¶

The 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 through config options. 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 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 data sources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the Grafana Operator to simplify observability. See: How to enable monitoring (COS).

Loki¶

Loki is an open-source fully-featured logging system. This charms is shipped with support for the Loki Operator to collect the generated logs. See: How to enable monitoring (COS).

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 to automatically scrape the targets. See: How to enable monitoring (COS).

Low-level design¶

See the charm state machines displayed in Charm lifecycle flowcharts. The low-level logic is mostly common for both VM and K8s charms.

Juju events¶

Accordingly to the Juju SDK: “an event is a data structure that encapsulates part of the execution context of a charm”.

For this charm, the following events are observed:

on_install: install the snap “charmed-mysql” and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster).
leader-elected: generate all the secrets to bootstrap the cluster.
leader-settings-changed: Handle the leader settings changed event.
start: Init/setting up the cluster node.
config_changed: 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).
update-status: Takes care of workload health checks.

Charm code overview¶

The code for both VM and K8s charms is located in the same repository, mysql-operators under the machines and kubernetes directories respectively.

For each substrate, src/charm.py is the default entry point for a charm and has the MySQLCharmBase Python class which inherits from CharmBase.

CharmBase is the base class from which all Charms are formed, defined by Ops (Python framework for developing charms). See more information in the Ops documentation for CharmBase.

The __init__ method guarantees that the charm observes all events relevant to its operation and handles them.