Skip to content

Commit a0ef676

Browse files
github-actions[bot]discourse-gatekeeper-docs-bot
github-actions[bot]
and
discourse-gatekeeper-docs-bot
authored
[discourse-gatekeeper] Migrate charm docs (#261)
This pull request was autogenerated by discourse-gatekeeper to migrate existing documentation from server to the git repository. Co-authored-by: discourse-gatekeeper-docs-bot <[email protected]>
1 parent 0105d34 commit a0ef676

File tree

5 files changed

+332
-0
lines changed

5 files changed

+332
-0
lines changed

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

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
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+
7+
* [Have a Charmed MySQLRouter K8s deployed](https://charmhub.io/mysql-router/docs/t-deploy-charm?channel=dpe/edge)
8+
* [Deploy cos-lite bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
9+
10+
Switch to the COS K8s environment and offer COS interfaces to be cross-model related with Charmed MySQLRouter K8s model:
11+
12+
```shell
13+
# Switch to the Kubernetes controller, on the COS model
14+
juju switch <k8s_cos_controller>:<cos_model_name>
15+
16+
juju offer grafana:grafana-dashboard
17+
juju offer loki:logging
18+
juju offer prometheus:receive-remote-write
19+
```
20+
21+
Switch to the Charmed MySQLRouter K8s model, find offers and consume them:
22+
23+
```shell
24+
# We are on the Kubernetes controller, on the COS model. Switch the mysqlrouter model
25+
juju switch <k8s_db_controller>:<mysql_router_model_name>
26+
27+
juju find-offers <k8s_cos_controller>: # Do not miss the ':' here!
28+
```
29+
30+
A similar output should appear, if `k8s` is the k8s controller name and `cos` is the model where cos-lite has been deployed:
31+
32+
```shell
33+
Store URL Access Interfaces
34+
k8s admin/cos.grafana admin grafana_dashboard:grafana-dashboard
35+
k8s admin/cos.loki admin loki_push_api:logging
36+
k8s admin/cos.prometheus admin prometheus_remote_write:receive-remote-write
37+
```
38+
39+
Consume the offers to be reachable in the current model:
40+
41+
```shell
42+
juju consume k8s:admin/cos.grafana
43+
juju consume k8s:admin/cos.loki
44+
juju consume k8s:admin/cos.prometheus
45+
```
46+
47+
Now, deploy ‘[grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s)’ and integrate (relate) it with Charmed MySQLRouter K8s, then later integrate (relate) `grafana-agent-k8s` with the consumed COS offers:
48+
49+
```shell
50+
juju deploy grafana-agent-k8s --trust
51+
52+
juju integrate grafana-agent-k8s grafana
53+
juju integrate grafana-agent-k8s loki
54+
juju integrate grafana-agent-k8s prometheus
55+
56+
juju integrate grafana-agent-k8s mysql-router-k8s:grafana-dashboard
57+
juju integrate grafana-agent-k8s mysql-router-k8s:logging
58+
juju integrate grafana-agent-k8s mysql-router-k8s:metrics-endpoint
59+
```
60+
61+
After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allow access for Charmed MySQLRouter K8s logs on Loki.
62+
63+
An example of `juju status` on Charmed MySQLRouter K8s model:
64+
65+
```shell
66+
ubuntu@localhost:~$ juju status
67+
Model Controller Cloud/Region Version SLA Timestamp
68+
database k8s microk8s/localhost 3.1.8 unsupported 13:27:08Z
69+
70+
SAAS Status Store URL
71+
grafana active k8s admin/cos.grafana
72+
loki active k8s admin/cos.loki
73+
prometheus active k8s admin/cos.prometheus
74+
75+
App Version Status Scale Charm Channel Rev Address Exposed Message
76+
grafana-agent-k8s 0.35.2 active 1 grafana-agent-k8s stable 64 10.152.183.141 no
77+
mysql-k8s 8.0.35-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/stable 127 10.152.183.105 no
78+
mysql-router-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 102 10.152.183.92 no
79+
mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 10.152.183.35 no
80+
81+
Unit Workload Agent Address Ports Message
82+
grafana-agent-k8s/0* active idle 10.1.241.243
83+
mysql-k8s/0* active idle 10.1.241.239 Primary
84+
mysql-router-k8s/0* active idle 10.1.241.240
85+
mysql-test-app/0* active idle 10.1.241.241
86+
```
87+
88+
An example of `juju status` on the COS K8s model:
89+
90+
```shell
91+
ubuntu@localhost:~$ juju status
92+
Model Controller Cloud/Region Version SLA Timestamp
93+
cos k8s microk8s/localhost 3.1.8 unsupported 13:28:02Z
94+
95+
App Version Status Scale Charm Channel Rev Address Exposed Message
96+
alertmanager 0.27.0 active 1 alertmanager-k8s stable 106 10.152.183.197 no
97+
catalogue active 1 catalogue-k8s stable 33 10.152.183.38 no
98+
grafana 9.5.3 active 1 grafana-k8s stable 106 10.152.183.238 no
99+
loki 2.9.4 active 1 loki-k8s stable 124 10.152.183.84 no
100+
prometheus 2.49.1 active 1 prometheus-k8s stable 171 10.152.183.182 no
101+
traefik 2.10.5 active 1 traefik-k8s stable 174 10.0.0.44 no
102+
103+
Unit Workload Agent Address Ports Message
104+
alertmanager/0* active idle 10.1.241.222
105+
catalogue/0* active idle 10.1.241.225
106+
grafana/0* active idle 10.1.241.228
107+
loki/0* active idle 10.1.241.226
108+
prometheus/0* active idle 10.1.241.227
109+
traefik/0* active idle 10.1.241.221
110+
111+
Offer Application Charm Rev Connected Endpoint Interface Role
112+
grafana grafana grafana-k8s 106 2/2 grafana-dashboard grafana_dashboard requirer
113+
loki loki loki-k8s 124 2/2 logging loki_push_api provider
114+
prometheus prometheus prometheus-k8s 171 2/2 receive-remote-write prometheus_remote_write provider
115+
```
116+
117+
To connect Grafana WEB interface, follow the COS section “[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s#heading--browse-dashboards)”:
118+
119+
```shell
120+
juju run grafana/leader get-admin-password --model <k8s_controller>:<cos_model_name>
121+
```

‎docs/index.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# MySQL Router K8s Documentation
2+
3+
The MySQL Router K8s Operator delivers automated operations management from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/) on the [MySQL Router Community Edition](https://www.mysql.com/products/community/) lightweight middleware that provides transparent routing between your application and back-end MySQL Servers. It is an open source, end-to-end, production-ready data platform component [on top of Juju](https://juju.is/).
4+
5+
![image|690x424](upload://vpevillwv3S9C44LDFBxkGCxpGq.png)
6+
7+
MySQL Router is part of InnoDB Cluster, and is lightweight middleware that provides transparent routing between your application and back-end MySQL Servers. It can be used for a wide variety of use cases, such as providing high availability and scalability by effectively routing database traffic to appropriate back-end MySQL Servers. The pluggable architecture also enables developers to extend MySQL Router for custom use cases.
8+
9+
This MySQL Router K8s operator charm comes in two flavours to deploy and operate MySQL Router on [physical/virtual machines](https://github.com/canonical/mysql-router-operator) and [Kubernetes](https://github.com/canonical/mysql-router-k8s-operator). Both offer features identical set of features and simplifies deployment, scaling, configuration and management of MySQL Router in production at scale in a reliable way.
10+
11+
## Project and community
12+
13+
This MySQL Router K8s charm is an official distribution of MySQL Router. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
14+
- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
15+
- [Join the Discourse forum](https://discourse.charmhub.io/tag/mysql-router)
16+
- [Contribute](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/mysql-router-k8s-operator/issues/new/choose)
17+
- Explore [Canonical Data Fabric solutions](https://canonical.com/data)
18+
- [Contacts us](/t/12177) for all further questions
19+
20+
## In this documentation
21+
22+
| | |
23+
|--|--|
24+
| [Tutorials](/t/12176)</br> Get started - a hands-on introduction to using Charmed MySQL operator for new users </br> | [How-to guides](/t/12233) </br> Step-by-step guides covering key operations and common tasks |
25+
| [Reference](/t/12201) </br> Technical information - specifications, APIs, architecture | [Explanation](/t/12223) </br> Concepts - discussion and clarification of key topics |
26+
27+
# Contents
28+
29+
1. [Tutorial](tutorial)
30+
1. [1. Introduction](tutorial/t-overview.md)
31+
1. [2. Set up the environment](tutorial/t-setup-environment.md)
32+
1. [3. Deploy MySQL Router](tutorial/t-deploy-charm.md)
33+
1. [4. Manage units](tutorial/t-managing-units.md)
34+
1. [5. Enable security](tutorial/t-enable-security.md)
35+
1. [6. Cleanup environment](tutorial/t-cleanup-environment.md)
36+
1. [How To](how-to)
37+
1. [Setup](how-to/h-setup)
38+
1. [Deploy on MicroK8s](how-to/h-setup/h-deploy-microk8s.md)
39+
1. [Manage units](how-to/h-setup/h-manage-units.md)
40+
1. [Enable encryption](how-to/h-setup/h-enable-encryption.md)
41+
1. [Manage applications](how-to/h-setup/h-manage-app.md)
42+
1. [Monitor (COS)](how-to/h-monitor)
43+
1. [Enable monitoring](how-to/h-monitor/h-enable-monitoring.md)
44+
1. [Upgrade](how-to/h-upgrade)
45+
1. [Intro](how-to/h-upgrade/h-upgrade-intro.md)
46+
1. [Major upgrade](how-to/h-upgrade/h-upgrade-major.md)
47+
1. [Major rollback](how-to/h-upgrade/h-rollback-major.md)
48+
1. [Minor upgrade](how-to/h-upgrade/h-upgrade-minor.md)
49+
1. [Minor rollback](how-to/h-upgrade/h-rollback-minor.md)
50+
1. [Reference](reference)
51+
1. [Release Notes](reference/r-releases-group)
52+
1. [All releases](reference/r-releases-group/r-releases.md)
53+
1. [Revision 112](reference/r-releases-group/r-releases-rev112.md)
54+
1. [Revision 96](reference/r-releases-group/r-releases-rev96.md)
55+
1. [Revision 82](reference/r-releases-group/r-releases-rev82.md)
56+
1. [Revision 69](reference/r-releases-group/r-releases-rev69.md)
57+
1. [Requirements](reference/r-requirements.md)
58+
1. [Contributing](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md)
59+
1. [Testing](reference/r-testing.md)
60+
1. [Actions](https://charmhub.io/mysql-router-k8s/actions)
61+
1. [Configurations](https://charmhub.io/mysql-router-k8s/configure)
62+
1. [Libraries](https://charmhub.io/mysql-router-k8s/libraries)
63+
1. [Integrations](https://charmhub.io/mysql-router-k8s/integrations)
64+
1. [Resources](https://charmhub.io/mysql-router-k8s/resources)
65+
1. [Contacts](reference/r-contacts.md)
66+
1. [Explanation](explanation)
67+
1. [Interfaces/endpoints](explanation/e-interfaces.md)
68+
1. [Statuses](explanation/e-statuses.md)
69+
1. [Juju](explanation/e-juju-details.md)

‎docs/reference/r-releases-group/r-releases-rev112.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
>Reference > Release Notes > [All revisions](/t/12201) > Revision 112
2+
# Revision 112 (`8.0/candidate` only)
3+
4+
<sub>TODO: DD, MM, YYYY</sub>
5+
6+
Dear community,
7+
8+
We'd like to announce that Canonical's newest Charmed MySQL Router K8s operator has been published in the '8.0/stable' [channel](https://charmhub.io/mysql-router-k8s/docs/r-releases?channel=8.0/stable) :tada:
9+
10+
[note]
11+
If you are jumping over several stable revisions, make sure to check [previous release notes](/t/12201) before upgrading to this revision.
12+
[/note]
13+
14+
## Features you can start using today
15+
16+
* New workload version [MySQL Router 8.0.36](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-36.html) [[PR#209](https://github.com/canonical/mysql-router-k8s-operator/pull/209)]
17+
* [K8s NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport) support [[PR#211](https://github.com/canonical/mysql-router-k8s-operator/pull/211)]
18+
* [Observability with COS](/t/14101) [[PR#210](https://github.com/canonical/mysql-router-k8s-operator/pull/210)]
19+
* Router version displayed in upgrade status [[PR#230](https://github.com/canonical/mysql-router-k8s-operator/pull/230)]
20+
* All the functionality from [previous revisions](/t/12201)
21+
22+
## Bugfixes
23+
24+
* Updated charmed-mysql ROCK image to latest version [[PR#237](https://github.com/canonical/mysql-router-k8s-operator/pull/237)]
25+
* Removed redundant upgrade check [[PR#234](https://github.com/canonical/mysql-router-k8s-operator/pull/234)]
26+
* Ported over changes from VM operator related to external connectivity [[PR#225](https://github.com/canonical/mysql-router-k8s-operator/pull/225)]
27+
* Updated `resume-upgrade` action `force` description [[PR#232](https://github.com/canonical/mysql-router-k8s-operator/pull/232)]
28+
* Fixed issue if incompatible upgrade is forced [[PR#231](https://github.com/canonical/mysql-router-k8s-operator/pull/231)]
29+
30+
Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/mysql-router-k8s-operator/issues) platforms.
31+
[GitHub Releases](https://github.com/canonical/mysql-router-k8s-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision.
32+
33+
## Inside the charms
34+
35+
* Charmed MySQL Router K8s ships MySQL Router `8.0.36-0ubuntu0.22.04.1`
36+
* CLI mysql-shell version is `8.0.36+dfsg-0ubuntu0.22.04.1~ppa4`
37+
* The Prometheus `mysql-router-exporter` is `5.0.1-0ubuntu0.22.04.1~ppa1`
38+
* K8s charms based on our [ROCK OCI](https://github.com/canonical/charmed-mysql-rock) (Ubuntu LTS `22.04.4`), snap revision `103`
39+
* Principal charms supports the latest LTS series 22.04 only
40+
41+
## Technical notes
42+
43+
* Upgrade (`juju refresh`) is possible from revision 69+
44+
* Use this operator together with modern operator [Charmed MySQL K8s](https://charmhub.io/mysql-k8s)
45+
* Please check restrictions from [previous release notes](https://charmhub.io/mysql-router-k8s/docs/r-releases)
46+
47+
## Contact us
48+
49+
Charmed MySQL Router K8s is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
50+
* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/mysql-router-k8s-operator/issues)
51+
* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
52+
* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.

‎docs/reference/r-releases-group/r-releases.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Release Notes
2+
3+
Canonical publishes here release notes for production ready revisions available in [CharmHub](https://charmhub.io) [channels](https://juju.is/docs/sdk/channel):
4+
5+
* [revision 112](/t/14074) in `8.0/candidate` (WIP)
6+
* [revision 96](/t/13523) in `8.0/stable`
7+
* [revision 82](/t/12796) in `8.0/stable`
8+
* [revision 69](/t/12202) in `8.0/stable`
9+
10+
All other [risks](https://juju.is/docs/sdk/channel#heading--risk) (`candidate`, `beta`, `edge`) are NOT recommended for production usage.

‎docs/tutorial/t-enable-security.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
>This is part of the [Charmed MySQLRouter K8s Tutorial](/t/12176). Please refer to this page for more information and the overview of the content.
2+
3+
# Enable encryption with TLS
4+
5+
[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a protocol used to encrypt data exchanged between two applications. Essentially, it secures data transmitted over a network.
6+
7+
Typically, enabling TLS internally within a highly available database or between a highly available database and client/server applications requires a high level of expertise. This has all been encoded into Charmed MySQL Router K8s so that configuring TLS requires minimal effort on your end.
8+
9+
TLS is enabled by integrating Charmed MySQL Router K8s with the [Self Signed Certificates Charm](https://charmhub.io/self-signed-certificates). This charm centralises TLS certificate management consistently and handles operations like providing, requesting, and renewing TLS certificates.
10+
11+
In this section, you will learn how to enable security in your MySQL Router K8s deployment using TLS encryption.
12+
13+
[note type="caution"]
14+
**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
15+
16+
Check [this guide](/t/11664) for an overview of the TLS certificates charms available.
17+
[/note]
18+
19+
---
20+
21+
## Enable TLS
22+
Before enabling TLS on Charmed MySQL Router K8s, we must first deploy the `self-signed-certificates` charm:
23+
```shell
24+
juju deploy self-signed-certificates --config ca-common-name="Tutorial CA"
25+
```
26+
27+
Wait until `self-signed-certificates` is up and active with `juju status --watch 1s` to monitor the progress.
28+
```shell
29+
Model Controller Cloud/Region Version SLA Timestamp
30+
database k8s microk8s/localhost 3.1.8 unsupported 12:10:33Z
31+
32+
App Version Status Scale Charm Channel Rev Address Exposed Message
33+
mysql-k8s 8.0.35-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/stable 127 10.152.183.101 no
34+
mysql-router-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 102 10.152.183.92 no
35+
mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 10.152.183.224 no
36+
self-signed-certificates active 1 self-signed-certificates stable 72 10.152.183.114 no
37+
38+
Unit Workload Agent Address Ports Message
39+
mysql-k8s/0* active idle 10.1.241.252 Primary
40+
mysql-router-k8s/0* active idle 10.1.241.253
41+
mysql-test-app/0* active idle 10.1.241.254
42+
self-signed-certificates/0* active idle 10.1.241.255
43+
```
44+
45+
To enable TLS on Charmed MySQLRouter K8s, integrate the two applications:
46+
```shell
47+
juju integrate mysql-router self-signed-certificates
48+
```
49+
50+
### Check the TLS certificate in use:
51+
Use `openssl` to connect to MySQLRouter K8s in the juju machine, and check the TLS certificate in use:
52+
```shell
53+
ubuntu@localhost:~$ juju ssh mysql-router-k8s/0 "openssl s_client -showcerts -starttls mysql -connect 127.0.0.1:6446 < /dev/null | openssl x509 -text | grep Issuer"
54+
...
55+
Issuer: C = US, CN = Tutorial CA
56+
...
57+
```
58+
59+
Congratulations! MySQLRouter K8s is now using a TLS certificate generated by the external application `self-signed-certificates`.
60+
61+
## Disable TLS
62+
To remove the external TLS and return to the locally generated one, unrelate the applications:
63+
```shell
64+
juju remove-relation mysql-router self-signed-certificates
65+
```
66+
67+
### Check the TLS certificate in use:
68+
```shell
69+
ubuntu@localhost:~$ juju ssh mysql-router-k8s/0 "openssl s_client -showcerts -starttls mysql -connect 127.0.0.1:6446 < /dev/null | openssl x509 -text | grep Issuer"
70+
```
71+
72+
The output should be similar to:
73+
```shell
74+
...
75+
Issuer: CN = MySQL_Router_Auto_Generated_CA_Certificate
76+
...
77+
```
78+
79+
80+
The Charmed MySQLRouter K8s application reverted to the placeholder certificate that was created locally during the MySQLRouter K8s installation.

0 commit comments

Comments
 (0)