Skip to content

Commit e722541

Browse files
github-actions[bot]discourse-gatekeeper-docs-bot
github-actions[bot]
and
discourse-gatekeeper-docs-bot
authored
[discourse-gatekeeper] Migrate charm docs (#270)
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 efad9e5 commit e722541

29 files changed

+1397
-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 K8s 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 K8s and MySQL Router K8s clusters with 3 nodes each
11+
juju deploy mysql-k8s -n 3 --trust
12+
juju deploy mysql-router-k8s -n 3 --trust --channel 8.0
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-k8s mysql-router-k8s
19+
juju integrate mysql-router-k8s: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-k8s:database mysql-router-k8s:backend-database mysql_client regular
27+
# > mysql-router-k8s:database mysql-test-app:database mysql_client regular
28+
# > ...
29+
```
30+
31+
**Note:** In order to relate with Charmed MySQL K8s, 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-k8s/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-k8s) 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-k8s:database mysql-test-app
34+
35+
juju run mysql-k8s/leader get-password
36+
```
37+
### Juju 2.9.x:
38+
```shell
39+
juju relate mysql-router-k8s:database mysql-test-app
40+
41+
juju run-action --wait mysql-k8s/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 and check the debug log to see the exception. 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: K8s charm termination in progress. | Manual investigation required if status is permanent |

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[note type="caution"]
2+
:construction: This page is under construction! More details coming soon.
3+
[/note]
4+
5+
# How to contribute
6+
7+
MySQL Router K8s 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 (WIP)
12+
* Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-router-k8s-operator/issues)
13+
* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
14+
15+
## Contribute to the code (WIP)
16+
17+
Before developing new features or fixes to this charm, you consider [opening an issue on GitHub](https://github.com/canonical/mysql-router-k8s-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+
22+
### Tips for a good contribution
23+
24+
* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
25+
* All contributions require review before being merged. Code review typically examines
26+
* Code quality
27+
* Test coverage
28+
* User experience for Juju operators of this charm.
29+
30+
...
31+
32+
33+
## Contribute to the documentation (WIP)
34+
35+
There are several ways to contribute to the documentation:
36+
* Writing a comment
37+
* Proposing an edit to an existing page
38+
* Adding a new page
39+
40+
...
41+
42+
### Tips for a good contribution
43+
...

‎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/how-to/h-setup/h-deploy-microk8s.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Deploy MySQL Router K8s
2+
3+
Please follow the [MySQL Router K8s Tutorial](/t/12176) for technical details and explanations.
4+
5+
Short story for your Ubuntu 22.04 LTS (`Wordpress` used as an client example for `MySQL Router`:
6+
```shell
7+
sudo snap install multipass
8+
multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs
9+
multipass shell my-vm
10+
11+
juju add-model wordpress-demo
12+
juju deploy mysql-k8s --channel 8.0/stable --trust # --config profile=testing
13+
juju deploy mysql-router-k8s --channel 8.0/stable --trust
14+
15+
juju integrate mysql-k8s mysql-router-k8s
16+
17+
juju status --watch 1s
18+
```
19+
20+
The expected result:
21+
```shell
22+
Model Controller Cloud/Region Version SLA Timestamp
23+
wordpress-demo microk8s microk8s/localhost 3.1.6 unsupported 14:39:27+02:00
24+
25+
App Version Status Scale Charm Channel Rev Address Exposed Message
26+
mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/stable 99 10.152.183.189 no
27+
mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 blocked 1 mysql-router-k8s 8.0/stable 69 10.152.183.81 no Missing relation: database
28+
29+
Unit Workload Agent Address Ports Message
30+
mysql-k8s/0* active idle 10.1.12.61 Primary
31+
mysql-router-k8s/0* active idle 10.1.12.16
32+
```
33+
The charm MySQL Router K8s is now waiting for relations with a client application, e.g. [mysql-test-app](https://charmhub.io/mysql-test-app), [wordpress](https://charmhub.io/wordpress-k8s), ...
34+
35+
Check the [Testing](/t/12234) reference to test your deployment.

‎docs/how-to/h-setup/h-enable-encryption.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
[note]
2+
**Note**: All commands are written for `juju >= v.3.1`
3+
4+
If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
5+
[/note]
6+
7+
# How to enable TLS encryption
8+
9+
<!---[Update and add to explanation]
10+
MySQL Router will enable encrypted connections by default with self generated certificates. Though also by default, connecting clients can disable encryption by setting the connection ssl-mode as disabled.
11+
When related with the `tls-certificates-operator` the charmed operator for MySQL Router will require that every client connection (new and running connections) use encryption, rendering an error when attempting to establish an unencrypted connection.-->
12+
13+
This guide will show how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example.
14+
15+
[note type="caution"]
16+
**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
17+
18+
Check [this guide](/t/11664) for an overview of the TLS certificates charms available.
19+
[/note]
20+
21+
---
22+
23+
## Enable TLS
24+
25+
First, deploy the TLS charm:
26+
```shell
27+
juju deploy self-signed-certificates
28+
```
29+
To enable TLS, integrate the two applications:
30+
```shell
31+
juju integrate self-signed-certificates mysql-router-k8s
32+
```
33+
34+
## Manage keys
35+
36+
Updates to private keys for certificate signing requests (CSR) can be made via the `set-tls-private-key` action. Note that passing keys to external/internal keys should *only be done with* `base64 -w0`, *not* `cat`.
37+
38+
With three replicas, this schema should be followed:
39+
40+
Generate a shared internal (private) key:
41+
```shell
42+
openssl genrsa -out internal-key.pem 3072
43+
```
44+
45+
Apply the newly generated internal key on each `juju` unit:
46+
```shell
47+
juju run mysql-router-k8s/0 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
48+
juju run mysql-router-k8s/1 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
49+
juju run mysql-router-k8s/2 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
50+
```
51+
52+
Updates can also be done with auto-generated keys with:
53+
54+
```shell
55+
juju run mysql-router-k8s/0 set-tls-private-key
56+
juju run mysql-router-k8s/1 set-tls-private-key
57+
juju run mysql-router-k8s/2 set-tls-private-key
58+
```
59+
60+
## Disable TLS
61+
Disable TLS by removing the integration:
62+
```shell
63+
juju remove-relation self-signed-certificates mysql-router-k8s
64+
```

0 commit comments

Comments
 (0)