Skip to content

Commit 1e2ded4

Browse files
Sync docs from Discourse (#322)
Sync charm docs from https://discourse.charmhub.io Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
1 parent 31518a0 commit 1e2ded4

10 files changed

+119
-67
lines changed

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

Lines changed: 55 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ This guide contains the steps to enable tracing with [Grafana Tempo](https://gra
99

1010
To summarize:
1111
* [Deploy the Tempo charm in a COS K8s environment](#heading--deploy)
12-
* [Integrate it with the COS charms](#heading--integrate)
1312
* [Offer interfaces for cross-model integrations](#heading--offer)
13+
* [Consume and integrate cross-model integrations](#heading--consume)
1414
* [View MySQL Router K8s traces on Grafana](#heading--view)
1515

1616

@@ -37,31 +37,14 @@ First, switch to the Kubernetes controller where the COS model is deployed:
3737
```shell
3838
juju switch <k8s_controller_name>:<cos_model_name>
3939
```
40-
Then, deploy the [`tempo-k8s`](https://charmhub.io/tempo-k8s) charm:
41-
```shell
42-
juju deploy -n 1 tempo-k8s --channel latest/edge
43-
```
4440

45-
<a href="#heading--integrate"><h2 id="heading--integrate"> Integrate with the COS charms </h2></a>
41+
Then, deploy the dependencies of Tempo following [this tutorial](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). In particular, we would want to:
42+
- Deploy the minio charm
43+
- Deploy the s3 integrator charm
44+
- Add a bucket in minio using a python script
45+
- Configure s3 integrator with the minio credentials
4646

47-
Integrate `tempo-k8s` with the COS charms as follows:
48-
49-
```shell
50-
juju integrate tempo-k8s:grafana-dashboard grafana:grafana-dashboard
51-
juju integrate tempo-k8s:grafana-source grafana:grafana-source
52-
juju integrate tempo-k8s:ingress traefik:traefik-route
53-
juju integrate tempo-k8s:metrics-endpoint prometheus:metrics-endpoint
54-
juju integrate tempo-k8s:logging loki:logging
55-
```
56-
If you would like to instrument traces from the COS charms as well, create the following integrations:
57-
```shell
58-
juju integrate tempo-k8s:tracing alertmanager:tracing
59-
juju integrate tempo-k8s:tracing catalogue:tracing
60-
juju integrate tempo-k8s:tracing grafana:tracing
61-
juju integrate tempo-k8s:tracing loki:tracing
62-
juju integrate tempo-k8s:tracing prometheus:tracing
63-
juju integrate tempo-k8s:tracing traefik:tracing
64-
```
47+
Finally, deploy and integrate with Tempo HA in a [monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489#heading--deploy-monolithic-setup).
6548

6649
<a href="#heading--offer"><h2 id="heading--offer"> Offer interfaces </h2></a>
6750

@@ -70,7 +53,7 @@ Next, offer interfaces for cross-model integrations from the model where Charmed
7053
To offer the Tempo integration, run
7154

7255
```shell
73-
juju offer tempo-k8s:tracing
56+
juju offer <tempo_coordinator_k8s_application_name>:tracing
7457
```
7558

7659
Then, switch to the Charmed MySQL Router K8s model, find the offers, and integrate (relate) with them:
@@ -86,51 +69,66 @@ Below is a sample output where `k8s` is the K8s controller name and `cos` is the
8669

8770
```shell
8871
Store URL Access Interfaces
89-
k8s admin/cos.tempo-k8s admin tracing:tracing
72+
k8s admin/cos.tempo admin tracing:tracing
9073
```
9174

9275
Next, consume this offer so that it is reachable from the current model:
9376

9477
```shell
95-
juju consume k8s:admin/cos.tempo-k8s
78+
juju consume k8s:admin/cos.tempo
9679
```
9780

98-
Relate Charmed MySQL Router K8s with the above consumed interface:
81+
<a href="#heading--consume"><h2 id="heading--consume"> Offer interfaces </h2></a>
82+
83+
First, deploy [Grafana Agent K8s](https://charmhub.io/grafana-agent-k8s) from the `latest/edge` channel:
84+
```shell
85+
juju deploy grafana-agent-k8s --channel latest/edge
86+
```
87+
88+
Then, integrate Grafana Agent k8s with the consumed interface from the previous section:
89+
```shell
90+
juju integrate grafana-agent-k8s:tracing tempo:tracing
91+
```
9992

93+
Finally, integrate Charmed MySQL Router K8s with Grafana Agent K8s:
10094
```shell
101-
juju integrate mysql-router-k8s:tracing tempo-k8s:tracing
95+
juju integrate mysql-router-k8s:tracing grafana-agent-k8s:tracing-provider
10296
```
10397

10498
Wait until the model settles. The following is an example of the `juju status --relations` on the Charmed MySQL Router K8s model:
10599

106100
```shell
107-
Model Controller Cloud/Region Version SLA Timestamp
108-
database k8s microk8s/localhost 3.4.3 unsupported 20:15:35Z
109-
110-
SAAS Status Store URL
111-
tempo-k8s active k8s admin/cos.tempo-k8s
112-
113-
App Version Status Scale Charm Channel Rev Address Exposed Message
114-
mysql-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/edge 153 10.152.183.113 no
115-
mysql-router-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 120 10.152.183.129 no
116-
mysql-test-app 0.0.2 active 1 mysql-test-app latest/stable 37 10.152.183.48 no Last written value=12318
117-
118-
Unit Workload Agent Address Ports Message
119-
mysql-k8s/0* active idle 10.1.241.204 Primary
120-
mysql-router-k8s/0* active idle 10.1.241.218
121-
mysql-test-app/0* active idle 10.1.241.231 Last written value=12318
122-
123-
Integration provider Requirer Interface Type Message
124-
mysql-k8s:database mysql-router-k8s:backend-database mysql_client regular
125-
mysql-k8s:database-peers mysql-k8s:database-peers mysql_peers peer
126-
mysql-k8s:restart mysql-k8s:restart rolling_op peer
127-
mysql-k8s:upgrade mysql-k8s:upgrade upgrade peer
128-
mysql-router-k8s:cos mysql-router-k8s:cos cos peer
129-
mysql-router-k8s:database mysql-test-app:database mysql_client regular
130-
mysql-router-k8s:mysql-router-peers mysql-router-k8s:mysql-router-peers mysql_router_peers peer
131-
mysql-router-k8s:upgrade-version-a mysql-router-k8s:upgrade-version-a upgrade peer
132-
mysql-test-app:application-peers mysql-test-app:application-peers application-peers peer
133-
tempo-k8s:tracing mysql-router-k8s:tracing tracing regular
101+
Model Controller Cloud/Region Version SLA Timestamp
102+
database k8s microk8s/localhost 3.5.4 unsupported 18:32:28Z
103+
104+
SAAS Status Store URL
105+
tempo active k8s admin/cos.tempo
106+
107+
App Version Status Scale Charm Channel Rev Address Exposed Message
108+
grafana-agent-k8s 0.40.4 active 1 grafana-agent-k8s latest/edge 93 10.152.183.141 no grafana-dashboards-provider: off, logging-consumer: off, send-remote-write: off
109+
mysql-k8s 8.0.37-0ubuntu0.22.04.3 active 1 mysql-k8s 8.0/edge 201 10.152.183.58 no
110+
mysql-router-k8s 8.0.37-0ubuntu0.22.04.3 active 1 mysql-router-k8s 1 10.152.183.50 no
111+
mysql-test-app 0.0.2 active 1 mysql-test-app latest/stable 51 10.152.183.162 no
112+
113+
Unit Workload Agent Address Ports Message
114+
grafana-agent-k8s/0* active idle 10.1.241.221 grafana-dashboards-provider: off, logging-consumer: off, send-remote-write: off
115+
mysql-k8s/0* active idle 10.1.241.213 Primary
116+
mysql-router-k8s/0* active idle 10.1.241.222
117+
mysql-test-app/0* active idle 10.1.241.218
118+
119+
Integration provider Requirer Interface Type Message
120+
grafana-agent-k8s:peers grafana-agent-k8s:peers grafana_agent_replica peer
121+
grafana-agent-k8s:tracing-provider mysql-router-k8s:tracing tracing regular
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:tracing grafana-agent-k8s:tracing tracing regular
134132

135133
```
136134

@@ -146,4 +144,4 @@ Below is a screenshot demonstrating a Charmed MySQL Router K8s trace:
146144

147145
![Example MySQL Router K8s trace with Grafana Tempo|690x382](upload://kPOyBvWjizYAYoQykaVLSJt0N4n.jpeg)
148146

149-
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.
147+
Feel free to read through the [Tempo HA documentation](https://discourse.charmhub.io/t/charmed-tempo-ha/15531) at your leisure to explore its deployment and its integrations.

docs/how-to/h-external-access.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# How to connect DB from outside of Kubernetes
2+
3+
To make the Charmed MySQL K8s database reachable from outside the Kubernetes cluster, this charm MySQL Router K8s should be deployed. It creates and manages several K8s services including the NodePort one:
4+
5+
```shell
6+
kubectl get services -n <model>
7+
```
8+
9+
```
10+
TODO
11+
```
12+
13+
The `TODO` NodePort service exposes a port to access both R/W and R/O MySQL servers from outside of K8s. The charm opens NodePort if requested in relation as `external-node-connectivity: true`. Example (relate mysql-router-k8s with data-integrator):
14+
```shell
15+
> juju run data-integrator/0 get-credentials
16+
...
17+
TODO
18+
```
19+
> **Note**: the relation flag `external-node-connectivity` is experimental and will be replaced in the future. Follow https://warthogs.atlassian.net/browse/DPE-5636 for more details.
20+
21+
> **Note**: The `mysql-router-k8s` and `mysql-router-k8s-endpoints` ClusterIP services seen above are created for every Juju application by default as part of the StatefulSet they are associated with. These services are not relevant to users and can be safely ignored.
22+
23+
## Client connections using the bootstrap service
24+
25+
A client can be configured to connect to the `TODO` service using a Kubernetes NodeIP, and desired NodePort.
26+
27+
To get NodeIPs:
28+
29+
```shell
30+
kubectl get nodes -o wide -n model | awk -v OFS='\t\t' '{print $1, $6}'
31+
```
32+
33+
```
34+
NAME INTERNAL-IP
35+
node-0 10.155.67.110
36+
node-1 10.155.67.120
37+
node-2 10.155.67.130
38+
```
39+
40+
NodeIPs are different for each deployment as they are randomly allocated.
41+
For the example from the previous section, the created NodePorts was:
42+
43+
```shell
44+
TODO
45+
```
46+
47+
Users can use this NodePort to access read-write / Primary server from outside of K8s:
48+
```shell
49+
TODO
50+
```
51+
Read-only servers can be accessed using the `_readonly` suffix to the desired DB name:
52+
```shell
53+
TODO
54+
```

docs/overview.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
4343
| 3 | h-manage-units | [Manage units](/t/12240) |
4444
| 3 | h-enable-encryption | [Enable encryption](/t/12241) |
4545
| 3 | h-manage-app | [Manage applications](/t/12242) |
46+
| 3 | h-external-access | [External access](/t/15730) |
4647
| 2 | h-monitor | [Monitor (COS)]() |
4748
| 3 | h-enable-monitoring | [Enable monitoring](/t/14101) |
4849
| 3 | h-enable-tracing | [Enable tracing](/t/14553) |
@@ -54,14 +55,13 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
5455
| 3 | h-rollback-minor | [Minor rollback](/t/12239) |
5556
| 2 | h-contribute | [Contribute](/t/14528) |
5657
| 1 | reference | [Reference]() |
57-
| 2 | r-releases-group | [Release Notes]() |
58-
| 3 | r-releases | [All releases](/t/12201) |
58+
| 2 | r-releases-group | [Release Notes](/t/12201) |
5959
| 3 | r-releases-rev155 | [Revision 154/155](/t/15354) |
6060
| 3 | r-releases-rev117 | [Revision 117](/t/14074) |
6161
| 3 | r-releases-rev96 | [Revision 96](/t/13523) |
6262
| 3 | r-releases-rev82 | [Revision 82](/t/12796) |
6363
| 3 | r-releases-rev69 | [Revision 69](/t/12202) |
64-
| 2 | r-requirements | [Requirements](/t/12179) |
64+
| 2 | r-system-requirements | [System requirements](/t/12179) |
6565
| 2 | r-testing | [Testing](/t/12234) |
6666
| 2 | r-contacts | [Contacts](/t/12177) |
6767
| 1 | explanation | [Explanation]() |
File renamed without changes.

docs/reference/r-releases-rev117.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
3939
* Charmed MySQL Router K8s ships MySQL Router `8.0.36-0ubuntu0.22.04.1`
4040
* CLI mysql-shell version is `8.0.36+dfsg-0ubuntu0.22.04.1~ppa4`
4141
* The Prometheus `mysql-router-exporter` is `5.0.1-0ubuntu0.22.04.1~ppa1`
42-
* K8s charms based on our [ROCK OCI](https://github.com/canonical/charmed-mysql-rock) (Ubuntu LTS `22.04.4`), snap revision `103`
42+
* K8s charms based on our [ROCK OCI](https://github.com/canonical/charmed-mysql-rock) ([resource-revision 53](https://github.com/canonical/mysql-router-k8s-operator/releases/tag/rev117), based on Ubuntu LTS `22.04.4`), snap revision `103`
4343
* Principal charms supports the latest LTS series 22.04 only
4444

4545
## Technical notes

docs/reference/r-releases-rev155.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Dear community,
88
Canonical's newest Charmed MySQL Router K8s operator has been published in the [8.0/stable channel].
99

1010
Due to the newly added support for arm64 architecture, the MySQL Router K8s charm now releases two revisions simultaneously:
11-
* Revision 155 is built for `amd64`
12-
* Revision 154 is built for `arm64`
11+
* Revision 155 is built for `amd64` ( mysql-router-image r57 )
12+
* Revision 154 is built for `arm64` ( mysql-router-image r57 )
1313

1414
To make sure you deploy for the right architecture, we recommend setting an [architecture constraint](https://juju.is/docs/juju/constraint#heading--arch) for your entire Juju model.
1515

@@ -47,7 +47,7 @@ If you are jumping over several stable revisions, check [previous release notes]
4747
See the [system requirements][] page for more details about software and hardware prerequisites.
4848

4949
### Packaging
50-
This charm is based on the [`charmed-mysql` rock] Revision TODO. It packages:
50+
This charm is based on the [`charmed-mysql` rock] (CharmHub `mysql-router-image` [resource-revision 57](https://github.com/canonical/mysql-router-k8s-operator/releases/tag/rev155)). It packages:
5151
- mysql-router `v8.0.37`
5252
- [8.0.37-0ubuntu0.22.04.1]
5353
- mysql-shell `v8.0.37`

docs/reference/r-releases-rev69.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
2121
* Charmed MySQL Router K8s ships the latest MySQL Router “8.0.34-0ubuntu0.22.04.1”
2222
* CLI mysql-shell updated to "8.0.34-0ubuntu0.22.04.1~ppa1"
2323
* The Prometheus mysql-router-exporter is "4.0.5-0ubuntu0.22.04.1~ppa1"
24-
* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI (Ubuntu LTS “22.04” - ubuntu:22.04-based)
24+
* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI ([resource-revision 43](https://github.com/canonical/mysql-router-k8s-operator/releases/tag/rev69), based on Ubuntu LTS “22.04”)
2525
* Principal charms supports the latest LTS series “22.04” only.
2626

2727
## Technical notes:

docs/reference/r-releases-rev82.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
2626
* Charmed MySQL Router K8s ships MySQL Router “8.0.34-0ubuntu0.22.04.1”
2727
* CLI mysql-shell version is "8.0.34-0ubuntu0.22.04.1~ppa1"
2828
* The Prometheus mysql-router-exporter is "4.0.5-0ubuntu0.22.04.1~ppa1"
29-
* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI (Ubuntu LTS “22.04” - ubuntu:22.04-based) based on SNAP revision 69
29+
* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI ([resource-revision 46](https://github.com/canonical/mysql-router-k8s-operator/releases/tag/rev82), based on Ubuntu LTS “22.04” - ubuntu:22.04-based) based on SNAP revision 69
3030
* Principal charms supports the latest LTS series “22.04” only
3131
* Subordinate charms support LTS “22.04” and “20.04” only
3232

docs/reference/r-releases-rev96.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
2424
* Charmed MySQL Router K8s ships MySQL Router “8.0.35-0ubuntu0.22.04.1”
2525
* CLI mysql-shell version is "8.0.35-0ubuntu0.22.04.1~ppa1"
2626
* The Prometheus mysql-router-exporter is "4.0.5-0ubuntu0.22.04.1~ppa1"
27-
* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI (Ubuntu LTS “22.04” - ubuntu:22.04-based)
27+
* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI ([resource-revision 49](https://github.com/canonical/mysql-router-k8s-operator/releases/tag/rev96), based on Ubuntu LTS “22.04” - ubuntu:22.04-based)
2828
* Principal charms supports the latest LTS series “22.04” only
2929

3030
## Technical notes:
File renamed without changes.

0 commit comments

Comments
 (0)