Sync docs from Discourse

canonical · Oct 7, 2024 · 472330c · 472330c
1 parent da06da4
commit 472330c
Show file tree

Hide file tree

Showing 8 changed files with 117 additions and 64 deletions.
diff --git a/docs/how-to/h-enable-tracing.md b/docs/how-to/h-enable-tracing.md
@@ -9,8 +9,8 @@ This guide contains the steps to enable tracing with [Grafana Tempo](https://gra
 
 To summarize:
 * [Deploy the Tempo charm in a COS K8s environment](#heading--deploy)
-* [Integrate it with the COS charms](#heading--integrate)
 * [Offer interfaces for cross-model integrations](#heading--offer)
+* [Consume and integrate cross-model integrations](#heading--consume)
 * [View MySQL Router K8s traces on Grafana](#heading--view)
 
 
@@ -37,31 +37,14 @@ First, switch to the Kubernetes controller where the COS model is deployed:
 ```shell
 juju switch <k8s_controller_name>:<cos_model_name>
 ```
-Then, deploy the [`tempo-k8s`](https://charmhub.io/tempo-k8s) charm:
-```shell
-juju deploy -n 1 tempo-k8s --channel latest/edge
-```
 
-<a href="#heading--integrate"><h2 id="heading--integrate"> Integrate with the COS charms </h2></a>
+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:
+- Deploy the minio charm
+- Deploy the s3 integrator charm
+- Add a bucket in minio using a python script
+- Configure s3 integrator with the minio credentials
 
-Integrate `tempo-k8s` with the COS charms as follows:
-
-```shell
-juju integrate tempo-k8s:grafana-dashboard grafana:grafana-dashboard
-juju integrate tempo-k8s:grafana-source grafana:grafana-source
-juju integrate tempo-k8s:ingress traefik:traefik-route
-juju integrate tempo-k8s:metrics-endpoint prometheus:metrics-endpoint
-juju integrate tempo-k8s:logging loki:logging
-```
-If you would like to instrument traces from the COS charms as well, create the following integrations:
-```shell
-juju integrate tempo-k8s:tracing alertmanager:tracing
-juju integrate tempo-k8s:tracing catalogue:tracing
-juju integrate tempo-k8s:tracing grafana:tracing
-juju integrate tempo-k8s:tracing loki:tracing
-juju integrate tempo-k8s:tracing prometheus:tracing
-juju integrate tempo-k8s:tracing traefik:tracing
-```
+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).
 
 <a href="#heading--offer"><h2 id="heading--offer"> Offer interfaces </h2></a>
 
@@ -70,7 +53,7 @@ Next, offer interfaces for cross-model integrations from the model where Charmed
 To offer the Tempo integration, run
 
 ```shell
-juju offer tempo-k8s:tracing
+juju offer <tempo_coordinator_k8s_application_name>:tracing
 ```
 
 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
 
 ```shell
 Store  URL                            Access  Interfaces
-k8s    admin/cos.tempo-k8s            admin   tracing:tracing
+k8s    admin/cos.tempo                admin   tracing:tracing
 ```
 
 Next, consume this offer so that it is reachable from the current model:
 
 ```shell
-juju consume k8s:admin/cos.tempo-k8s
+juju consume k8s:admin/cos.tempo
 ```
 
-Relate Charmed MySQL Router K8s with the above consumed interface:
+<a href="#heading--consume"><h2 id="heading--consume"> Offer interfaces </h2></a>
+
+First, deploy [Grafana Agent K8s](https://charmhub.io/grafana-agent-k8s) from the `latest/edge` channel:
+```shell
+juju deploy grafana-agent-k8s --channel latest/edge
+```
+
+Then, integrate Grafana Agent k8s with the consumed interface from the previous section:
+```shell
+juju integrate grafana-agent-k8s:tracing tempo:tracing
+```
 
+Finally, integrate Charmed MySQL Router K8s with Grafana Agent K8s:
 ```shell
-juju integrate mysql-router-k8s:tracing tempo-k8s:tracing
+juju integrate mysql-router-k8s:tracing grafana-agent-k8s:tracing-provider
 ```
 
 Wait until the model settles. The following is an example of the `juju status --relations` on the Charmed MySQL Router K8s model:
 
 ```shell
-Model      Controller  Cloud/Region        Version  SLA          Timestamp
-database   k8s         microk8s/localhost  3.4.3    unsupported  20:15:35Z
-
-SAAS       Status  Store  URL
-tempo-k8s  active  k8s    admin/cos.tempo-k8s
-
-App               Version                  Status  Scale  Charm             Channel        Rev  Address         Exposed  Message
-mysql-k8s         8.0.36-0ubuntu0.22.04.1  active      1  mysql-k8s         8.0/edge       153  10.152.183.113  no       
-mysql-router-k8s  8.0.36-0ubuntu0.22.04.1  active      1  mysql-router-k8s  8.0/edge       120  10.152.183.129  no       
-mysql-test-app    0.0.2                    active      1  mysql-test-app    latest/stable   37  10.152.183.48   no       Last written value=12318
-
-Unit                 Workload  Agent  Address       Ports  Message
-mysql-k8s/0*         active    idle   10.1.241.204         Primary
-mysql-router-k8s/0*  active    idle   10.1.241.218         
-mysql-test-app/0*    active    idle   10.1.241.231         Last written value=12318
-
-Integration provider                 Requirer                             Interface           Type     Message
-mysql-k8s:database                   mysql-router-k8s:backend-database    mysql_client        regular  
-mysql-k8s:database-peers             mysql-k8s:database-peers             mysql_peers         peer     
-mysql-k8s:restart                    mysql-k8s:restart                    rolling_op          peer     
-mysql-k8s:upgrade                    mysql-k8s:upgrade                    upgrade             peer     
-mysql-router-k8s:cos                 mysql-router-k8s:cos                 cos                 peer     
-mysql-router-k8s:database            mysql-test-app:database              mysql_client        regular  
-mysql-router-k8s:mysql-router-peers  mysql-router-k8s:mysql-router-peers  mysql_router_peers  peer     
-mysql-router-k8s:upgrade-version-a   mysql-router-k8s:upgrade-version-a   upgrade             peer     
-mysql-test-app:application-peers     mysql-test-app:application-peers     application-peers   peer     
-tempo-k8s:tracing                    mysql-router-k8s:tracing             tracing             regular  
+Model     Controller  Cloud/Region        Version  SLA          Timestamp
+database  k8s         microk8s/localhost  3.5.4    unsupported  18:32:28Z
+
+SAAS   Status  Store       URL
+tempo  active  k8s         admin/cos.tempo
+
+App                Version                  Status  Scale  Charm              Channel        Rev  Address         Exposed  Message
+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
+mysql-k8s          8.0.37-0ubuntu0.22.04.3  active      1  mysql-k8s          8.0/edge       201  10.152.183.58   no       
+mysql-router-k8s   8.0.37-0ubuntu0.22.04.3  active      1  mysql-router-k8s                    1  10.152.183.50   no       
+mysql-test-app     0.0.2                    active      1  mysql-test-app     latest/stable   51  10.152.183.162  no       
+
+Unit                  Workload  Agent  Address       Ports  Message
+grafana-agent-k8s/0*  active    idle   10.1.241.221         grafana-dashboards-provider: off, logging-consumer: off, send-remote-write: off
+mysql-k8s/0*          active    idle   10.1.241.213         Primary
+mysql-router-k8s/0*   active    idle   10.1.241.222         
+mysql-test-app/0*     active    idle   10.1.241.218         
+
+Integration provider                 Requirer                             Interface              Type     Message
+grafana-agent-k8s:peers              grafana-agent-k8s:peers              grafana_agent_replica  peer     
+grafana-agent-k8s:tracing-provider   mysql-router-k8s:tracing             tracing                regular  
+mysql-k8s:database                   mysql-router-k8s:backend-database    mysql_client           regular  
+mysql-k8s:database-peers             mysql-k8s:database-peers             mysql_peers            peer     
+mysql-k8s:restart                    mysql-k8s:restart                    rolling_op             peer     
+mysql-k8s:upgrade                    mysql-k8s:upgrade                    upgrade                peer     
+mysql-router-k8s:cos                 mysql-router-k8s:cos                 cos                    peer     
+mysql-router-k8s:database            mysql-test-app:database              mysql_client           regular  
+mysql-router-k8s:mysql-router-peers  mysql-router-k8s:mysql-router-peers  mysql_router_peers     peer     
+mysql-router-k8s:upgrade-version-a   mysql-router-k8s:upgrade-version-a   upgrade                peer     
+mysql-test-app:application-peers     mysql-test-app:application-peers     application-peers      peer     
+tempo:tracing                        grafana-agent-k8s:tracing            tracing                regular  
 
 ```
 
@@ -146,4 +144,4 @@ Below is a screenshot demonstrating a Charmed MySQL Router K8s trace:
 
 ![Example MySQL Router K8s trace with Grafana Tempo|690x382](upload://kPOyBvWjizYAYoQykaVLSJt0N4n.jpeg)
 
-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.
+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.
diff --git a/docs/how-to/h-external-k8s-connection.md b/docs/how-to/h-external-k8s-connection.md
@@ -0,0 +1,54 @@
+# External K8s connection
+
+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:
+
+```shell
+kubectl get services -n <model>
+```
+
+```
+TODO
+```
+
+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):
+```shell
+> juju run data-integrator/0 get-credentials
+...
+TODO
+```
+> **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. 
+
+> **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.
+
+## Client connections using the bootstrap service
+
+A client can be configured to connect to the `TODO` service using a Kubernetes NodeIP, and desired NodePort.
+
+To get NodeIPs:
+
+```shell
+kubectl get nodes -o wide -n model | awk -v OFS='\t\t' '{print $1, $6}'
+```
+
+```
+NAME        INTERNAL-IP
+node-0      10.155.67.110
+node-1      10.155.67.120
+node-2      10.155.67.130
+```
+
+NodeIPs are different for each deployment as they are randomly allocated.
+For the example from the previous section, the created NodePorts was:
+
+```shell
+TODO
+```
+
+Users can use this NodePort to access read-write / Primary server from outside of K8s:
+```shell
+TODO
+```
+Read-only servers can be accessed using the `_readonly` suffix to the desired DB name:
+```shell
+TODO
+```
diff --git a/docs/overview.md b/docs/overview.md
@@ -43,6 +43,7 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
 | 3 | h-manage-units | [Manage units](/t/12240) |
 | 3 | h-enable-encryption | [Enable encryption](/t/12241) |
 | 3 | h-manage-app | [Manage applications](/t/12242) |
+| 3 | h-external-k8s-connection | [External k8s connection](/t/15730) |
 | 2 | h-monitor | [Monitor (COS)]() |
 | 3 | h-enable-monitoring | [Enable monitoring](/t/14101) |
 | 3 | h-enable-tracing | [Enable tracing](/t/14553) |

diff --git a/docs/reference/r-releases-rev117.md b/docs/reference/r-releases-rev117.md
@@ -39,7 +39,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
 * Charmed MySQL Router K8s ships MySQL Router `8.0.36-0ubuntu0.22.04.1`
 * CLI mysql-shell version is `8.0.36+dfsg-0ubuntu0.22.04.1~ppa4`
 * The Prometheus `mysql-router-exporter` is `5.0.1-0ubuntu0.22.04.1~ppa1`
-* K8s charms based on our [ROCK OCI](https://github.com/canonical/charmed-mysql-rock) (Ubuntu LTS `22.04.4`), snap revision `103`
+* 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`
 * Principal charms supports the latest LTS series 22.04 only
 
 ## Technical notes

diff --git a/docs/reference/r-releases-rev155.md b/docs/reference/r-releases-rev155.md
@@ -8,8 +8,8 @@ Dear community,
 Canonical's newest Charmed MySQL Router K8s operator has been published in the [8.0/stable channel].
 
 Due to the newly added support for arm64 architecture, the MySQL Router K8s charm now releases two revisions simultaneously:
-* Revision 155 is built for `amd64`
-* Revision 154 is built for `arm64`
+* Revision 155 is built for `amd64` ( mysql-router-image r57 )
+* Revision 154 is built for `arm64` ( mysql-router-image r57 )
 
 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.
 
@@ -47,7 +47,7 @@ If you are jumping over several stable revisions, check [previous release notes]
 See the [system requirements][] page for more details about software and hardware prerequisites.
 
 ### Packaging
-This charm is based on the [`charmed-mysql` rock] Revision TODO. It packages:
+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:
 - mysql-router `v8.0.37`
   - [8.0.37-0ubuntu0.22.04.1]
 - mysql-shell `v8.0.37`

diff --git a/docs/reference/r-releases-rev69.md b/docs/reference/r-releases-rev69.md
@@ -21,7 +21,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
 * Charmed MySQL Router K8s ships the latest MySQL Router “8.0.34-0ubuntu0.22.04.1”
 * CLI mysql-shell updated to "8.0.34-0ubuntu0.22.04.1~ppa1"
 * The Prometheus mysql-router-exporter is "4.0.5-0ubuntu0.22.04.1~ppa1"
-* 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)
+* 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”)
 * Principal charms supports the latest LTS series “22.04” only.
 
 ## Technical notes:

diff --git a/docs/reference/r-releases-rev82.md b/docs/reference/r-releases-rev82.md
@@ -26,7 +26,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
 * Charmed MySQL Router K8s ships MySQL Router “8.0.34-0ubuntu0.22.04.1”
 * CLI mysql-shell version is "8.0.34-0ubuntu0.22.04.1~ppa1"
 * The Prometheus mysql-router-exporter is "4.0.5-0ubuntu0.22.04.1~ppa1"
-* 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
+* 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
 * Principal charms supports the latest LTS series “22.04” only
 * Subordinate charms support LTS “22.04” and “20.04” only
 

diff --git a/docs/reference/r-releases-rev96.md b/docs/reference/r-releases-rev96.md
@@ -24,7 +24,7 @@ Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.n
 * Charmed MySQL Router K8s ships MySQL Router “8.0.35-0ubuntu0.22.04.1”
 * CLI mysql-shell version is "8.0.35-0ubuntu0.22.04.1~ppa1"
 * The Prometheus mysql-router-exporter is "4.0.5-0ubuntu0.22.04.1~ppa1"
-* 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)
+* 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)
 * Principal charms supports the latest LTS series “22.04” only
 
 ## Technical notes: