Skip to content

Commit d49eda8

Browse files
github-actions[bot]upload-charms-docs-botdiscourse-gatekeeper-docs-bot
authored
[discourse-gatekeeper] Migrate charm docs (#109)
This pull request was autogenerated by discourse-gatekeeper to migrate existing documentation from server to the git repository. --------- Co-authored-by: upload-charms-docs-bot <[email protected]> Co-authored-by: discourse-gatekeeper-docs-bot <[email protected]>
1 parent ed7d8e3 commit d49eda8

31 files changed

+1480
-0
lines changed

‎docs/explanation/e-interfaces.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Interfaces/endpoints
2+
3+
MySQL Router supports 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/).
4+
5+
### Modern `mysql_client` interface (`database` endpoint):
6+
7+
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:
8+
9+
```shell
10+
# Deploy Charmed MySQL and MySQL Router clusters
11+
juju deploy mysql -n 3
12+
juju deploy mysql-router -n 3 --channel dpe/edge
13+
14+
# Deploy the relevant charms, e.g. mysql-test-app
15+
juju deploy mysql-test-app
16+
17+
# Relate all applications
18+
juju integrate mysql mysql-router
19+
juju integrate mysql-router:database mysql-test-app
20+
21+
# Check established relation (using mysql_client interface):
22+
juju status --relations
23+
24+
# Example of the properly established relation:
25+
# > Integration provider Requirer Interface Type Message
26+
# > mysql:database mysql-router:backend-database mysql_client regular
27+
# > mysql-router:database mysql-test-app:database mysql_client regular
28+
# > ...
29+
```
30+
31+
**Note:** In order to relate with Charmed MySQL, every table created by the client 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.
32+
33+
See all the charm interfaces [here](https://charmhub.io/mysql-router/integrations).

‎docs/explanation/e-juju-details.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Juju tech details
2+
3+
[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.
4+
5+
This [charm](https://charmhub.io/mysql-router) 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/).
6+
7+
See also:
8+
9+
* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju)
10+
* [Charm SDK](https://juju.is/docs/sdk)
11+
12+
## Breaking changes between Juju 2.9.x and 3.x
13+
14+
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.
15+
16+
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.
17+
18+
In the context of this guide, the pertinent changes are shown here:
19+
20+
|2.9.x|3.x|
21+
| --- | --- |
22+
|**add-relation**|**integrate**|
23+
|**relate**|**integrate**|
24+
|**run**|**exec**|
25+
|**run-action --wait**|**run**|
26+
27+
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.
28+
29+
The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example:
30+
31+
### Juju 3.x:
32+
```shell
33+
juju integrate mysql-router:database mysql-test-app
34+
35+
juju run mysql/leader get-password
36+
```
37+
### Juju 2.9.x:
38+
```shell
39+
juju relate mysql-router:database mysql-test-app
40+
41+
juju run-action --wait mysql/leader get-password
42+
```
43+
> :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)

‎docs/explanation/e-statuses.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Charm Statuses
2+
3+
> :warning: **WARNING** : it is an work-in-progress article. Do NOT use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic.
4+
5+
The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses:
6+
7+
| Juju Status | Message | Expectations | Actions |
8+
|-------|-------|-------|-------|
9+
| **active** | any | Normal charm operations | No actions required |
10+
| **waiting** | any | Charm is waiting for relations to be finished | No actions required |
11+
| **maintenance** | any | Charm is performing the internal maintenance (e.g. re-configuration) | No actions required |
12+
| **blocked** | any | The manual user activity is required! | Follow the message hints (see below) |
13+
| **blocked** | Missing relation: ... | Normal behavior, charm needs all relations to work. | Follow the hint to establish a proper relation. |
14+
| **blocked** | Router was manually removed from MySQL ClusterSet. Remove & re-deploy unit | Scale-down temporary message OR split-brain for the unknown reason. | Wait to finish scale-down or remove and re-deploy unit if the message is persistent.|
15+
| **blocked** | ... app requested unsupported extra user role on database endpoint | Unsupported [role](https://charmhub.io/data-integrator/configure#extra-user-roles) requested. | Use supported extra-user-role. |
16+
| **blocked** | Upgrade incompatible. Rollback to previous revision with `juju refresh` | Incompatible charm channel/revision chosen. | [Rollback](/t/12239) the charm. |
17+
| **blocked** | Upgrading. Verify highest unit is healthy & run `resume-upgrade ` action. To rollback, `juju refresh` to last revision | Normal behavior, application is being upgraded and waiting for user confirmation to continue or rollback | [Continue upgrade](/t/12238) or [rollback](/t/12239). |
18+
| **error** | any | An unhanded internal error happened | Read the message hint. Execute `juju resolve <error_unit/0>` after addressing the root of the error state |
19+
| **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible |
20+
| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: the charm termination in progress. | Manual investigation required if status is permanent |

‎docs/how-to/h-contribute.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[note type="caution"]
2+
:construction: This page is under construction! More details for each section coming soon.
3+
[/note]
4+
5+
# How to contribute
6+
7+
Charmed MySQL Router is an open-source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.
8+
9+
This page explains the processes and practices recommended for contributing to this charm's code and documentation.
10+
11+
## Submit a bug or issue
12+
* Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-router-operator/issues)
13+
* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
14+
15+
## Contribute to the code
16+
17+
Before developing new features or fixes to this charm, you consider [opening an issue on GitHub](https://github.com/canonical/mysql-router-operator/issues) explaining your use case.
18+
19+
If you would like to chat with us about your use-cases or proposed implementation, you can reach us at our [Data Platform Matrix channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com).
20+
21+
### Tips for a good contribution
22+
23+
* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
24+
* All contributions require review before being merged. Code review typically examines
25+
* Code quality
26+
* Test coverage
27+
* User experience for Juju operators of this charm
28+
29+
## Contribute to the documentation
30+
31+
There are several ways to contribute to the documentation:
32+
* Writing a comment on Discourse
33+
* Submitting an [issue](https://github.com/canonical/mysql-router-operator/issues) on GitHub with the `documentation` label

‎docs/how-to/h-enable-monitoring.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Enable monitoring
2+
3+
> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju run ...` with `juju run-action --wait ...` and `juju integrate` with `juju relate` for Juju 2.9
4+
5+
Enabling monitoring requires that you:
6+
* [Have a Charmed MySQL and Charmed MySQLRouter deployed](https://charmhub.io/mysql-router/docs/t-deploy-charm?channel=dpe/edge)
7+
* [Deploy ‘cos-lite’ bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
8+
9+
Switch to the COS K8s environment and offer COS interfaces to be cross-model integrated (related) with Charmed MySQLRouter VM model:
10+
11+
```shell
12+
# Switch to the Kubernetes controller, in particular the COS model
13+
juju switch <k8s_controller>:<cos_model_name>
14+
15+
juju offer grafana:grafana-dashboard
16+
juju offer loki:logging
17+
juju offer prometheus:receive-remote-write
18+
```
19+
20+
Switch to the Charmed MySQLRouter VM model, find offers and integrate (relate) with them:
21+
22+
```shell
23+
# We are on the Kubernetes controller, for the COS model. Switch to the MySQLRouter model
24+
juju switch <machine_controller_name>:<mysql_router_model_name>
25+
26+
juju find-offers <k8s_controller>: # Do not miss ':' here
27+
```
28+
29+
A similar output should appear, if `k8s` is the k8s controller name and `cos` is the model where cos-lite has been deployed:
30+
31+
```shell
32+
Store URL Access Interfaces
33+
k8s admin/cos.grafana admin grafana_dashboard:grafana-dashboard
34+
k8s admin/cos.loki admin loki_push_api:logging
35+
k8s admin/cos.prometheus admin prometheus_remote_write:receive-remote-write
36+
```
37+
38+
Consume offers to be reachable in the current model:
39+
40+
```shell
41+
juju consume k8s:admin/cos.grafana
42+
juju consume k8s:admin/cos.loki
43+
juju consume k8s:admin/cos.prometheus
44+
```
45+
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:
47+
48+
```shell
49+
# Assume <client_application> is the principal application for the subordinate mysql router application
50+
juju deploy grafana-agent
51+
juju integrate <client_application> grafana-agent
52+
juju integrate grafana-agent mysql-router:cos-agent
53+
juju integrate grafana-agent grafana
54+
juju integrate grafana-agent loki
55+
juju integrate grafana-agent prometheus
56+
```
57+
58+
After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allows access for Charmed MySQLRouter logs on Loki.
59+
60+
An example of `juju status` on the Charmed MySQLRouter VM model:
61+
62+
```shell
63+
ubuntu@localhost:~$ juju status
64+
Model Controller Cloud/Region Version SLA Timestamp
65+
database lxd localhost/localhost 3.1.8 unsupported 12:34:26Z
66+
67+
SAAS Status Store URL
68+
grafana active k8s admin/cos.grafana
69+
loki active k8s admin/cos.loki
70+
prometheus active k8s admin/cos.prometheus
71+
72+
App Version Status Scale Charm Channel Rev Exposed Message
73+
grafana-agent active 1 grafana-agent stable 65 no
74+
mysql 8.0.34-0ubun... active 1 mysql 8.0/stable 196 no
75+
mysql-router 8.0.36-0ubun... active 1 mysql-router dpe/edge 153 no
76+
mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 no
77+
78+
Unit Workload Agent Machine Public address Ports Message
79+
mysql-test-app/0* active idle 1 10.205.193.82
80+
grafana-agent/0* active idle 10.205.193.82
81+
mysql-router/0* active idle 10.205.193.82
82+
mysql/0* active idle 0 10.205.193.13 3306,33060/tcp Primary
83+
84+
Machine State Address Inst id Base AZ Message
85+
0 started 10.205.193.13 juju-65afbd-0 [email protected] Running
86+
1 started 10.205.193.82 juju-65afbd-1 [email protected] Running
87+
```
88+
89+
Example of `juju status` on the COS K8s model:
90+
91+
```shell
92+
ubuntu@localhost:~$ juju status
93+
Model Controller Cloud/Region Version SLA Timestamp
94+
cos k8s microk8s/localhost 3.1.8 unsupported 20:29:12Z
95+
96+
App Version Status Scale Charm Channel Rev Address Exposed Message
97+
alertmanager 0.27.0 active 1 alertmanager-k8s stable 106 10.152.183.197 no
98+
catalogue active 1 catalogue-k8s stable 33 10.152.183.38 no
99+
grafana 9.5.3 active 1 grafana-k8s stable 106 10.152.183.238 no
100+
loki 2.9.4 active 1 loki-k8s stable 124 10.152.183.84 no
101+
prometheus 2.49.1 active 1 prometheus-k8s stable 171 10.152.183.182 no
102+
```
103+
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)”:
105+
106+
```shell
107+
juju run grafana/leader get-admin-password --model <k8s_controller>:<cos_model_name>
108+
```

‎docs/how-to/h-monitoring/h-enable-monitoring.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Enable monitoring
2+
3+
> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju run ...` with `juju run-action --wait ...` and `juju integrate` with `juju relate` for Juju 2.9
4+
5+
Enabling monitoring requires that you:
6+
* [Have a Charmed MySQL and Charmed MySQLRouter deployed](https://charmhub.io/mysql-router/docs/t-deploy-charm?channel=dpe/edge)
7+
* [Deploy ‘cos-lite’ bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
8+
9+
Switch to the COS K8s environment and offer COS interfaces to be cross-model integrated (related) with Charmed MySQLRouter VM model:
10+
11+
```shell
12+
# Switch to the Kubernetes controller, in particular the COS model
13+
juju switch <k8s_controller>:<cos_model_name>
14+
15+
juju offer grafana:grafana-dashboard
16+
juju offer loki:logging
17+
juju offer prometheus:receive-remote-write
18+
```
19+
20+
Switch to the Charmed MySQLRouter VM model, find offers and integrate (relate) with them:
21+
22+
```shell
23+
# We are on the Kubernetes controller, for the COS model. Switch to the MySQLRouter model
24+
juju switch <machine_controller_name>:<mysql_router_model_name>
25+
26+
juju find-offers <k8s_controller>: # Do not miss ':' here
27+
```
28+
29+
A similar output should appear, if `k8s` is the k8s controller name and `cos` is the model where cos-lite has been deployed:
30+
31+
```shell
32+
Store URL Access Interfaces
33+
k8s admin/cos.grafana admin grafana_dashboard:grafana-dashboard
34+
k8s admin/cos.loki admin loki_push_api:logging
35+
k8s admin/cos.prometheus admin prometheus_remote_write:receive-remote-write
36+
```
37+
38+
Consume offers to be reachable in the current model:
39+
40+
```shell
41+
juju consume k8s:admin/cos.grafana
42+
juju consume k8s:admin/cos.loki
43+
juju consume k8s:admin/cos.prometheus
44+
```
45+
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:
47+
48+
```shell
49+
# Assume <client_application> is the principal application for the subordinate mysql router application
50+
juju deploy grafana-agent
51+
juju integrate <client_application> grafana-agent
52+
juju integrate grafana-agent mysql-router:cos-agent
53+
juju integrate grafana-agent grafana
54+
juju integrate grafana-agent loki
55+
juju integrate grafana-agent prometheus
56+
```
57+
58+
After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allows access for Charmed MySQLRouter logs on Loki.
59+
60+
An example of `juju status` on the Charmed MySQLRouter VM model:
61+
62+
```shell
63+
ubuntu@localhost:~$ juju status
64+
Model Controller Cloud/Region Version SLA Timestamp
65+
database lxd localhost/localhost 3.1.8 unsupported 12:34:26Z
66+
67+
SAAS Status Store URL
68+
grafana active k8s admin/cos.grafana
69+
loki active k8s admin/cos.loki
70+
prometheus active k8s admin/cos.prometheus
71+
72+
App Version Status Scale Charm Channel Rev Exposed Message
73+
grafana-agent active 1 grafana-agent stable 65 no
74+
mysql 8.0.34-0ubun... active 1 mysql 8.0/stable 196 no
75+
mysql-router 8.0.36-0ubun... active 1 mysql-router dpe/edge 153 no
76+
mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 no
77+
78+
Unit Workload Agent Machine Public address Ports Message
79+
mysql-test-app/0* active idle 1 10.205.193.82
80+
grafana-agent/0* active idle 10.205.193.82
81+
mysql-router/0* active idle 10.205.193.82
82+
mysql/0* active idle 0 10.205.193.13 3306,33060/tcp Primary
83+
84+
Machine State Address Inst id Base AZ Message
85+
0 started 10.205.193.13 juju-65afbd-0 [email protected] Running
86+
1 started 10.205.193.82 juju-65afbd-1 [email protected] Running
87+
```
88+
89+
Example of `juju status` on the COS K8s model:
90+
91+
```shell
92+
ubuntu@localhost:~$ juju status
93+
Model Controller Cloud/Region Version SLA Timestamp
94+
cos k8s microk8s/localhost 3.1.8 unsupported 20:29:12Z
95+
96+
App Version Status Scale Charm Channel Rev Address Exposed Message
97+
alertmanager 0.27.0 active 1 alertmanager-k8s stable 106 10.152.183.197 no
98+
catalogue active 1 catalogue-k8s stable 33 10.152.183.38 no
99+
grafana 9.5.3 active 1 grafana-k8s stable 106 10.152.183.238 no
100+
loki 2.9.4 active 1 loki-k8s stable 124 10.152.183.84 no
101+
prometheus 2.49.1 active 1 prometheus-k8s stable 171 10.152.183.182 no
102+
```
103+
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)”:
105+
106+
```shell
107+
juju run grafana/leader get-admin-password --model <k8s_controller>:<cos_model_name>
108+
```

0 commit comments

Comments
 (0)