You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page contains explanations regarding the legacy version of this charm. This includes clarification about Charmhub tracks, supported endpoints and interfaces, config options, and other important information.
3
+
4
+
## Summary
5
+
*[Charm types: "legacy" vs. "modern"](#heading--charm-types)
6
+
*[Default track `latest/` vs. track `1/`](#heading--default-track)
7
+
*[How to migrate to the modern charm](#heading--how-to-migrate)
8
+
*[How to deploy the legacy charm](#heading--how-to-deploy-legacy)
9
+
*[Features supported by the modern charm](#heading--features-supported-by-modern)
10
+
*[Config options](#heading--config-options)
11
+
*[Extensions](#heading--extensions)
12
+
*[Roles](#heading--roles)
13
+
*[MySQL versions](#heading--postgresql-versions)
14
+
*[Architectures](#heading--architectures)
15
+
*[Contact us](#heading--contact-us)
16
+
17
+
---
18
+
19
+
<ahref="#heading--charm-types"><h2id="heading--charm-types"> Charm types: "legacy" vs. "modern" </h2></a>
20
+
21
+
There are [two types of charms](https://juju.is/docs/sdk/charm-taxonomy#heading--charm-types-by-generation) stored under the same charm name `mysql-router`:
22
+
23
+
1.[Reactive](https://juju.is/docs/sdk/charm-taxonomy#heading--reactive) charm in the channel `latest/stable`, `8.0/stable`, `8.0.19/stable` (called `legacy`)
24
+
2.[Ops-based](https://juju.is/docs/sdk/ops) charm in the channel `dpe/candidate`, `8.4/edge` (called `modern`)
25
+
26
+
Both legacy and modern charms are [**subordinated**](https://juju.is/docs/sdk/charm-taxonomy#heading--subordinate-charms).
27
+
28
+
The legacy charm provided SQL endpoints `shared-db` (for the interface `mysql-shared`). The modern charm provides those old endpoint and a new endpoint `database` (for the interface `mysql_client`). Read more details about the available endpoints and interfaces [here](https://charmhub.io/mysql-router/docs/e-interfaces?channel=dpe/candidate).
29
+
30
+
**Note**: Please choose one endpoint to use. No need to relate all of them simultaneously!
31
+
32
+
<ahref="#heading--default-track"><h2id="heading--default-track"> Default track `latest/` vs. track `8.4/` </h2></a>
33
+
34
+
The [default track](https://docs.openstack.org/charm-guide/yoga/project/charm-delivery.html) will be switched from the `latest` to `8.4` soon. This is to ensure all new deployments use a modern codebase. We strongly advise against using the latest track, since a future charm upgrade may result in a MySQL Router version incompatible with an integrated application. Track `8.4/` guarantees a major router version 8.4 deployment only. The track `latest/` will be closed after all applications migrated from reactive to the ops-based charm.
35
+
36
+
37
+
<ahref="#heading--how-to-migrate"><h2id="heading--how-to-migrate"> How to migrate to the modern charm </h2></a>
38
+
39
+
The modern charm provides temporary support for the legacy interfaces:
40
+
41
+
**Quick try**: relate the current application with new charm using endpoint `shared-db` (set the channel to `dpe/candidate`). No extra changes necessary:
42
+
43
+
```
44
+
mysql-router:
45
+
charm: mysql-router
46
+
channel: dpe/candidate
47
+
```
48
+
49
+
**Proper migration**: migrate the application to the new interface [`mysql_client`](https://github.com/canonical/charm-relation-interfaces). The application will connect MySQl Router using the [data_interfaces](https://charmhub.io/data-platform-libs/libraries/data_interfaces) library from [data-platform-libs](https://github.com/canonical/data-platform-libs/) via the endpoint `database`.
50
+
51
+
**Warning**: In-place upgrades are NOT possible! The reactive charm cannot be upgraded to the operator-framework-based one. The second/modern charm application must be launched nearby and relations should be switched from the legacy application to the modern one.
52
+
53
+
54
+
<ahref="#heading--how-to-deploy-legacy"><h2id="heading--how-to-deploy-legacy"> How to deploy the legacy charm </h2></a>
55
+
56
+
Deploy the charm using the channel `latest/stable`:
57
+
58
+
```
59
+
mysql-router:
60
+
charm: mysql-router
61
+
channel: 8.0/stable
62
+
```
63
+
64
+
**Note**: remove Charm store prefix `cs:` from the bundle. Otherwise the modern charm will be chosen by Juju (due to the default track will be pointing to `8.4/stable` and not `latest/stable`). The common error message is: `cannot deploy application "mysql-router": unknown option "..."`.
65
+
66
+
<ahref="#heading--features-supported-by-modern"><h2id="heading--features-supported-by-modern"> Features supported by the modern charm </h2></a>
67
+
This section goes over the key differences in feature support and functionality between the legacy and modern charm.
The legacy charm config options were not moved to the modern charm, since the modern charm applies the best possible configuration automatically. Feel free to [contact us](/t/12323?channel=dpe/candidate) about the MySQl Router config options.
The "legacy charm" (from `latest/stable`) is stored on [Launchpad](TODO). Report legacy charm issues [here](TODO).
89
+
90
+
The "modern charm" (from `dpe/candidate`) is stored on [GitHub](https://github.com/canonical/mysql-router-operator). Report modern charm issues [here](https://github.com/canonical/mysql-router-operator/issues/new/choose).
91
+
92
+
Do you have questions? [Reach out](/t/12323?channel=dpe/candidate) to us!
Consume offers to be reachable in the current model:
60
+
To consume offers to be reachable in the current model, run
39
61
40
62
```shell
41
63
juju consume k8s:admin/cos.grafana
42
64
juju consume k8s:admin/cos.loki
43
65
juju consume k8s:admin/cos.prometheus
44
66
```
45
67
46
-
Now deploy ‘[grafana_agent](https://charmhub.io/grafana-agent)’ (subordinate charm) alongside the Charmed MySQL Router application (also subordinate) and integrate (relate) it with Charmed MySQLRouter, then later integrate (relate) `grafana-agent `with the consumed COS offers:
68
+
## Deploy and integrate Grafana
47
69
70
+
First, deploy [grafana-agent](https://charmhub.io/grafana-agent) and integrate it with the principal application for the subordinate MySQL Router app `<client_application>`: <!--TODO: Why not just use MySQL as example of principal? -->
48
71
```shell
49
-
# Assume <client_application> is the principal application for the subordinate mysql router application
50
72
juju deploy grafana-agent
51
73
juju integrate <client_application> grafana-agent
74
+
```
75
+
76
+
Integrate (previously known as "[relate](https://juju.is/docs/juju/integration)") `grafana-agent` with the COS interfaces:
After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allows access for Charmed MySQLRouter logs on Loki.
84
+
After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allows access for Charmed MySQL Router logs on Loki.
59
85
60
-
An example of `juju status` on the Charmed MySQLRouter VM model:
86
+
Example of `juju status` on the Charmed MySQL Router VM model:
61
87
62
88
```shell
63
89
ubuntu@localhost:~$ juju status
@@ -100,8 +126,9 @@ grafana 9.5.3 active 1 grafana-k8s stable 106 10.152.183.238 no
100
126
loki 2.9.4 active 1 loki-k8s stable 124 10.152.183.84 no
101
127
prometheus 2.49.1 active 1 prometheus-k8s stable 171 10.152.183.182 no
102
128
```
129
+
## Connect to Grafana web interface
103
130
104
-
To connect to the Grafana WEB interface, follow the COS section “[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s#heading--browse-dashboards)”:
131
+
To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s?_ga=2.201254254.1948444620.1704703837-757109492.1701777558#heading--browse-dashboards) section of the MicroK8s "Getting started" guide.
105
132
106
133
```shell
107
134
juju run grafana/leader get-admin-password --model <k8s_controller>:<cos_model_name>
For optimal performance, it is recommended that [MySQL Router](https://dev.mysql.com/doc/mysql-router/8.0/en/) is run alongside your application and that your application uses a Unix domain socket to connect to and execute queries against MySQL Router. The usage of a Unix domain socket here results in increased network performance due to the reduced network hops and in increased security due to the lack of exposed ports.
4
+
5
+
When your application implements the modern (preferred) interface in [MySQL Router's supported interfaces](https://discourse.charmhub.io/t/mysql-router-how-to-manage-app/12339) , the MySQL Router charm is deployed as a subordinate of your application charm and your application will be presented with a Unix domain socket, over the interface, to connect to MySQL Router.
6
+
7
+
## Accessing MySQL Router outside of Juju
8
+
9
+
A known limitation of relating with MySQL Router (a subordinate charm) is that your application would need to be deployed as a Juju application. However, if your application exists outside of the Juju ecosystem, you can access MySQL Router externally with the [Data Integrator](https://charmhub.io/data-integrator) charm.
10
+
11
+
### Example setup
12
+
The steps below show you how to deploy and set up MySQL, MySQL Router, and Data Integrator for access outside of Juju.
You can then connect to MySQL Router with the provided `endpoints` from your application that resides outside of Juju.
53
+
54
+
## Using a Virtual IP to connect to MySQL Router
55
+
56
+
If the MySQL Router charm is related to the Data Integrator charm, it is possible for a user to configure MySQL Router to use a certain Virtual IP. This assumes that the user has somehow ensured that the Virtual IP resolves to the node on which the MySQL Router charm is deployed.
57
+
58
+
To configure the MySQL Router charm with a virtual IP, run
59
+
```shell
60
+
juju config mysql-router/0 vip=<your_virtual_ip>
61
+
```
62
+
63
+
### Integrate with HACluster
64
+
65
+
Alternatively, you can integrate with the [HACluster charm](https://charmhub.io/hacluster) if you would like a Virtual IP that is generated and maintained for you.
66
+
67
+
HACluster is a collection of solutions by [ClusterLabs](https://clusterlabs.org/) designed to create and manage resources. The creation of resources like Virtual IPs is handled by [Pacemaker](https://clusterlabs.org/pacemaker/), whereas the management of these resources is handled by [Corosync](https://clusterlabs.org/corosync.html).
68
+
69
+
Pacemaker will create and attach a Virtual IP to one of your Data Integrator nodes (that is related to MySQL Router), while Corosync will ensure automatic failover if the node with the Virtual IP faces connectivity or other issues. **This setup requires at least 3 Data Integrator nodes, each related to both MySQL Router and HACluster.**
70
+
71
+
[note type="warning"]
72
+
**Warning**: The Virtual IP supplied to MySQL Router should be in the same subnet as the nodes on which the MySQL Router charm is running. Else, you may encounter unexpected behavior from the HACluster charm when it tries to create the Virtual IP.
73
+
[/note]
74
+
75
+
#### Example setup
76
+
The steps below show you how to deploy and set up MySQL, MySQL Router, Data Integrator, and HACluster.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments