Skip to content

Commit 11080d8

Browse files
github-actions[bot]discourse-gatekeeper-docs-bot
github-actions[bot]
and
discourse-gatekeeper-docs-bot
authored
[discourse-gatekeeper] Migrate charm docs (#274)
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 179025b commit 11080d8

File tree

5 files changed

+162
-21
lines changed

5 files changed

+162
-21
lines changed

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

Lines changed: 7 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[note type="caution"]
2-
:construction: This page is under construction! More details coming soon.
2+
:construction: This page is under construction! More details for each section coming soon.
33
[/note]
44

55
# How to contribute
@@ -8,36 +8,26 @@ MySQL Router K8s is an open-source project that warmly welcomes community contri
88

99
This page explains the processes and practices recommended for contributing to this charm's code and documentation.
1010

11-
## Submit a bug or issue (WIP)
11+
## Submit a bug or issue
1212
* Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-router-k8s-operator/issues)
1313
* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
1414

15-
## Contribute to the code (WIP)
15+
## Contribute to the code
1616

1717
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.
1818

1919
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).
2020

21-
2221
### Tips for a good contribution
2322

2423
* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
2524
* All contributions require review before being merged. Code review typically examines
2625
* Code quality
2726
* Test coverage
28-
* User experience for Juju operators of this charm.
29-
30-
...
31-
27+
* User experience for Juju operators of this charm
3228

33-
## Contribute to the documentation (WIP)
29+
## Contribute to the documentation
3430

3531
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-
...
32+
* Writing a comment on Discourse
33+
* Submitting an [issue](https://github.com/canonical/mysql-router-k8s-operator/issues) on GitHub with the `documentation` label

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

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
[note]
2+
**Note**: All commands are written for `juju >= v3.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+
# Enable tracing
8+
This guide contains the steps to enable tracing with [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for your MySQL Router K8s application.
9+
10+
To summarize:
11+
* [Deploy the Tempo charm in a COS K8s environment](#heading--deploy)
12+
* [Integrate it with the COS charms](#heading--integrate)
13+
* [Offer interfaces for cross-model integrations](#heading--offer)
14+
* [View MySQL Router K8s traces on Grafana](#heading--view)
15+
16+
17+
[note type="caution"]
18+
**Warning:** This is feature is in development. It is **not recommended** for production environments.
19+
20+
This feature is available for Charmed MySQL Router K8s revision 117+ only.
21+
[/note]
22+
23+
## Prerequisites
24+
Enabling tracing with Tempo requires that you:
25+
- Have deployed a Charmed MySQL Router K8s application
26+
- See [How to manage units](https://discourse.charmhub.io/t/mysql-router-k8s-how-to-manage-units/12240)
27+
- Have deployed a 'cos-lite' bundle from the `latest/edge` track in a Kubernetes environment
28+
- See [Getting started on MicroK8s](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
29+
30+
---
31+
<a href="#heading--deploy"><h2 id="heading--deploy"> Deploy Tempo </h2></a>
32+
33+
First, switch to the Kubernetes controller where the COS model is deployed:
34+
35+
```shell
36+
juju switch <k8s_controller_name>:<cos_model_name>
37+
```
38+
Then, deploy the [`tempo-k8s`](https://charmhub.io/tempo-k8s) charm:
39+
```shell
40+
juju deploy -n 1 tempo-k8s --channel latest/edge
41+
```
42+
43+
<a href="#heading--integrate"><h2 id="heading--integrate"> Integrate with the COS charms </h2></a>
44+
45+
Integrate `tempo-k8s` with the COS charms as follows:
46+
47+
```shell
48+
juju integrate tempo-k8s:grafana-dashboard grafana:grafana-dashboard
49+
juju integrate tempo-k8s:grafana-source grafana:grafana-source
50+
juju integrate tempo-k8s:ingress traefik:traefik
51+
juju integrate tempo-k8s:metrics-endpoint prometheus:metrics-endpoint
52+
juju integrate tempo-k8s:logging loki:logging
53+
```
54+
If you would like to instrument traces from the COS charms as well, create the following integrations:
55+
```shell
56+
juju integrate tempo-k8s:tracing alertmanager:tracing
57+
juju integrate tempo-k8s:tracing catalogue:tracing
58+
juju integrate tempo-k8s:tracing grafana:tracing
59+
juju integrate tempo-k8s:tracing loki:tracing
60+
juju integrate tempo-k8s:tracing prometheus:tracing
61+
juju integrate tempo-k8s:tracing traefik:tracing
62+
```
63+
64+
<a href="#heading--offer"><h2 id="heading--offer"> Offer interfaces </h2></a>
65+
66+
Next, offer interfaces for cross-model integrations from the model where Charmed MySQL Router is deployed.
67+
68+
To offer the Tempo integration, run
69+
70+
```shell
71+
juju offer tempo-k8s:tracing
72+
```
73+
74+
Then, switch to the Charmed MySQL Router K8s model, find the offers, and integrate (relate) with them:
75+
76+
```shell
77+
juju switch <k8s_controller_name>:<mysql_router_k8s_model_name>
78+
79+
juju find-offers <k8s_controller_name>:
80+
```
81+
> :exclamation: Do not miss the "`:`" in the command above.
82+
83+
Below is a sample output where `k8s` is the K8s controller name and `cos` is the model where `cos-lite` and `tempo-k8s` are deployed:
84+
85+
```shell
86+
Store URL Access Interfaces
87+
k8s admin/cos.tempo-k8s admin tracing:tracing
88+
```
89+
90+
Next, consume this offer so that it is reachable from the current model:
91+
92+
```shell
93+
juju consume k8s:admin/cos.tempo-k8s
94+
```
95+
96+
Relate Charmed MySQL Router K8s with the above consumed interface:
97+
98+
```shell
99+
juju integrate mysql-router-k8s:tracing tempo-k8s:tracing
100+
```
101+
102+
Wait until the model settles. The following is an example of the `juju status --relations` on the Charmed MySQL Router K8s model:
103+
104+
```shell
105+
Model Controller Cloud/Region Version SLA Timestamp
106+
database k8s microk8s/localhost 3.4.3 unsupported 20:15:35Z
107+
108+
SAAS Status Store URL
109+
tempo-k8s active k8s admin/cos.tempo-k8s
110+
111+
App Version Status Scale Charm Channel Rev Address Exposed Message
112+
mysql-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/edge 153 10.152.183.113 no
113+
mysql-router-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 120 10.152.183.129 no
114+
mysql-test-app 0.0.2 active 1 mysql-test-app latest/stable 37 10.152.183.48 no Last written value=12318
115+
116+
Unit Workload Agent Address Ports Message
117+
mysql-k8s/0* active idle 10.1.241.204 Primary
118+
mysql-router-k8s/0* active idle 10.1.241.218
119+
mysql-test-app/0* active idle 10.1.241.231 Last written value=12318
120+
121+
Integration provider Requirer Interface Type Message
122+
mysql-k8s:database mysql-router-k8s:backend-database mysql_client regular
123+
mysql-k8s:database-peers mysql-k8s:database-peers mysql_peers peer
124+
mysql-k8s:restart mysql-k8s:restart rolling_op peer
125+
mysql-k8s:upgrade mysql-k8s:upgrade upgrade peer
126+
mysql-router-k8s:cos mysql-router-k8s:cos cos peer
127+
mysql-router-k8s:database mysql-test-app:database mysql_client regular
128+
mysql-router-k8s:mysql-router-peers mysql-router-k8s:mysql-router-peers mysql_router_peers peer
129+
mysql-router-k8s:upgrade-version-a mysql-router-k8s:upgrade-version-a upgrade peer
130+
mysql-test-app:application-peers mysql-test-app:application-peers application-peers peer
131+
tempo-k8s:tracing mysql-router-k8s:tracing tracing regular
132+
133+
```
134+
135+
[note]
136+
**Note:** All traces are exported to Tempo using HTTP. Support for sending traces via HTTPS is an upcoming feature.
137+
[/note]
138+
139+
<a href="#heading--view"><h2 id="heading--view"> View traces </h2></a>
140+
141+
After this is complete, the Tempo traces will be accessible from Grafana under the `Explore` section with `tempo-k8s` as the data source. You will be able to select `mysql` as the `Service Name` under the `Search` tab to view traces belonging to Charmed MySQL Router K8s.
142+
143+
Below is a screenshot demonstrating a Charmed MySQL Router K8s trace:
144+
145+
![Example MySQL Router K8s trace with Grafana Tempo|690x382](upload://kPOyBvWjizYAYoQykaVLSJt0N4n.jpeg)
146+
147+
Feel free to read through the [Tempo documentation](https://discourse.charmhub.io/t/tempo-k8s-docs-index/14005) at your leisure to explore its deployment and its integrations.

‎docs/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
4141
1. [Manage applications](how-to/h-setup/h-manage-app.md)
4242
1. [Monitor (COS)](how-to/h-monitor)
4343
1. [Enable monitoring](how-to/h-monitor/h-enable-monitoring.md)
44+
1. [Enable tracing](how-to/h-monitor/h-enable-tracing.md)
4445
1. [Upgrade](how-to/h-upgrade)
4546
1. [Intro](how-to/h-upgrade/h-upgrade-intro.md)
4647
1. [Major upgrade](how-to/h-upgrade/h-upgrade-major.md)
@@ -51,7 +52,7 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
5152
1. [Reference](reference)
5253
1. [Release Notes](reference/r-releases-group)
5354
1. [All releases](reference/r-releases-group/r-releases.md)
54-
1. [Revision 112](reference/r-releases-group/r-releases-rev112.md)
55+
1. [Revision 117](reference/r-releases-group/r-releases-rev117.md)
5556
1. [Revision 96](reference/r-releases-group/r-releases-rev96.md)
5657
1. [Revision 82](reference/r-releases-group/r-releases-rev82.md)
5758
1. [Revision 69](reference/r-releases-group/r-releases-rev69.md)

‎docs/reference/r-releases-group/r-releases-rev112.md renamed to ‎docs/reference/r-releases-group/r-releases-rev117.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
>Reference > Release Notes > [All revisions](/t/12201) > Revision 112
2-
# Revision 112 (`8.0/candidate` only)
1+
>Reference > Release Notes > [All revisions](/t/12201) > Revision 117
2+
# Revision 117 (`8.0/candidate` only)
33

44
<sub>TODO: DD, MM, YYYY</sub>
55

@@ -16,11 +16,14 @@ If you are jumping over several stable revisions, make sure to check [previous r
1616
* 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)]
1717
* [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)]
1818
* [Observability with COS](/t/14101) [[PR#210](https://github.com/canonical/mysql-router-k8s-operator/pull/210)]
19+
* Introduced [COS Tracing support](/t/14553) [[PR#250](https://github.com/canonical/mysql-router-k8s-operator/pull/250)][[DPE-4615](https://warthogs.atlassian.net/browse/DPE-4615)]
1920
* Router version displayed in upgrade status [[PR#230](https://github.com/canonical/mysql-router-k8s-operator/pull/230)]
2021
* All the functionality from [previous revisions](/t/12201)
2122

2223
## Bugfixes
2324

25+
* Fix TLS configuration immediately deleted after enabling [[PR#249](https://github.com/canonical/mysql-router-k8s-operator/pull/249)]
26+
* Clear connection pool before relating with COS to avoid TIME_WAIT connections + stabilize exporter tests [[PR#245](https://github.com/canonical/mysql-router-k8s-operator/pull/245)][[DPE-3899](https://warthogs.atlassian.net/browse/DPE-3899), [DPE-4173](https://warthogs.atlassian.net/browse/DPE-4173)]
2427
* Updated charmed-mysql ROCK image to latest version [[PR#237](https://github.com/canonical/mysql-router-k8s-operator/pull/237)]
2528
* Removed redundant upgrade check [[PR#234](https://github.com/canonical/mysql-router-k8s-operator/pull/234)]
2629
* Ported over changes from VM operator related to external connectivity [[PR#225](https://github.com/canonical/mysql-router-k8s-operator/pull/225)]

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Canonical publishes here release notes for production ready revisions available in [CharmHub](https://charmhub.io) [channels](https://juju.is/docs/sdk/channel):
44

5-
* [revision 112](/t/14074) in `8.0/candidate` (WIP)
5+
* [revision 117](/t/14074) in `8.0/candidate` (WIP)
66
* [revision 96](/t/13523) in `8.0/stable`
77
* [revision 82](/t/12796) in `8.0/stable`
88
* [revision 69](/t/12202) in `8.0/stable`

0 commit comments

Comments
 (0)