Sync docs from Discourse

canonical · Dec 28, 2024 · 34ffbc2 · 34ffbc2
1 parent c4f8162
commit 34ffbc2
Show file tree

Hide file tree

Showing 4 changed files with 222 additions and 33 deletions.
diff --git a/docs/how-to/h-external-access.md b/docs/how-to/h-external-access.md
@@ -1,54 +1,160 @@
 # How to connect DB from outside of Kubernetes
 
-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:
+To expose a Charmed MySQL K8s database externally, this charm (MySQL Router K8s) should be deployed and related with the Charmed MySQL K8s application. Charmed MySQL Router K8s then provides a configuration option `expose-external` (with options `false`, `nodeport` and `loadbalancer`) to control precisely how the database will be externally exposed.
 
-```shell
-kubectl get services -n <model>
-```
+By default (when `expose-external=false`), Charmed MySQL Router K8s creates a K8s service of type `ClusterIP` which it provides as endpoints to the related client applications. These endpoints are only accessible from within the K8s namespace (or juju model) where the MySQL Router K8s application is deployed.
 
-```
-TODO
-```
+Below is a juju model where MySQL Router K8s is related to MySQL K8s and Data Integrator, which we will later use to demonstrate the configuration of `expose-external`:
 
-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. 
+$ juju status --relations
+Model     Controller  Cloud/Region        Version  SLA          Timestamp
+database  uk8s-3-6-1  microk8s/localhost  3.6.1    unsupported  14:39:08Z
 
-> **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.
+App               Version                  Status  Scale  Charm             Channel        Rev  Address         Exposed  Message
+data-integrator                            active      1  data-integrator   latest/stable   78  10.152.183.44   no       
+mysql-k8s         8.0.39-0ubuntu0.22.04.1  active      1  mysql-k8s         8.0/candidate  210  10.152.183.143  no       
+mysql-router-k8s  8.0.39-0ubuntu0.22.04.1  active      1  mysql-router-k8s  8.0/candidate  531  10.152.183.201  no       
 
-## Client connections using the bootstrap service
+Unit                 Workload  Agent  Address       Ports  Message
+data-integrator/0*   active    idle   10.1.241.219         
+mysql-k8s/0*         active    idle   10.1.241.217         Primary
+mysql-router-k8s/0*  active    idle   10.1.241.218         
 
-A client can be configured to connect to the `TODO` service using a Kubernetes NodeIP, and desired NodePort.
+Integration provider                   Requirer                               Interface              Type     Message
+data-integrator:data-integrator-peers  data-integrator:data-integrator-peers  data-integrator-peers  peer     
+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              data-integrator:mysql                  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
+```
 
-To get NodeIPs:
+When `expose-external=false`, the following shows the endpoints returned to the client:
 
 ```shell
-kubectl get nodes -o wide -n model | awk -v OFS='\t\t' '{print $1, $6}'
+$ juju run data-integrator/0 get-credentials
+mysql:
+  data: '{"database": "test-database", "external-node-connectivity": "true", "requested-secrets":
+    "[\"username\", \"password\", \"tls\", \"tls-ca\", \"uris\"]"}'
+  database: test-database
+  endpoints: mysql-router-k8s-service.database.svc.cluster.local:6446
+  password: VRLNoVx6Br4Vn5SNHdoMK52Q
+  read-only-endpoints: mysql-router-k8s-service.database.svc.cluster.local:6447
+  username: relation-7_4fc92c2813524d6-8
+ok: "True"
 ```
 
-```
-NAME        INTERNAL-IP
-node-0      10.155.67.110
-node-1      10.155.67.120
-node-2      10.155.67.130
+The following shows a mysql client connecting to the the provided endpoints from the data integrator unit (which is deployed in the same K8s namespace, i.e. the same juju model, as MySQL Router K8s):
+
+```shell
+$ juju ssh data-integrator/0 bash 
+root@data-integrator-0:/var/lib/juju# mysql -h mysql-router-k8s-service.database.svc.cluster.local -P 6446 -u relation-7_4fc92c2813524d6-8 -pVRLNoVx6Br4Vn5SNHdoMK52Q
+mysql> show databases;
++--------------------+
+| Database           |
++--------------------+
+| information_schema |
+| performance_schema |
+| test-database      |
++--------------------+
+3 rows in set (0.01 sec)
+
+mysql> exit;
+Bye
+root@data-integrator-0:/var/lib/juju# mysql -h mysql-router-k8s-service.database.svc.cluster.local -P 6447 -u relation-7_4fc92c2813524d6-8 -pVRLNoVx6Br4Vn5SNHdoMK52Q
+mysql> show databases;
++--------------------+
+| Database           |
++--------------------+
+| information_schema |
+| performance_schema |
+| test-database      |
++--------------------+
+3 rows in set (0.01 sec)
 ```
 
-NodeIPs are different for each deployment as they are randomly allocated.
-For the example from the previous section, the created NodePorts was:
+## External Access
+
+MySQL Router K8s can be made externally accessible by setting `expose-external=nodeport` (corresponding to K8s NodePort service) or `expose-external=loadbalancer` (corresponding to K8s LoadBalancer service).
+
+When `expose-external=nodeport`, MySQL Router K8s will provide as endpoints comma-separated node:port values of the nodes where the MySQL Router K8s units are scheduled.
 
 ```shell
-TODO
+$ juju run data-integrator/0 get-credentials
+mysql:
+  data: '{"database": "test-database", "external-node-connectivity": "true", "requested-secrets":
+    "[\"username\", \"password\", \"tls\", \"tls-ca\", \"uris\"]"}'
+  database: test-database
+  endpoints: 10.0.0.44:31604
+  password: VRLNoVx6Br4Vn5SNHdoMK52Q
+  read-only-endpoints: 10.0.0.44:31907
+  username: relation-7_4fc92c2813524d6-8
+ok: "True"
+
+$ charmed-mysql.mysql -h 10.0.0.44 -P 31604 -u relation-7_4fc92c2813524d6-8 -pVRLNoVx6Br4Vn5SNHdoMK52Q
+mysql> show databases;
++--------------------+
+| Database           |
++--------------------+
+| information_schema |
+| performance_schema |
+| test-database      |
++--------------------+
+3 rows in set (0.00 sec)
+
+$ charmed-mysql.mysql -h 10.0.0.44 -P 31907 -u relation-7_4fc92c2813524d6-8 -pVRLNoVx6Br4Vn5SNHdoMK52Q
+mysql> show databases;
++--------------------+
+| Database           |
++--------------------+
+| information_schema |
+| performance_schema |
+| test-database      |
++--------------------+
+3 rows in set (0.00 sec)
 ```
 
-Users can use this NodePort to access read-write / Primary server from outside of K8s:
+Similarly, when `expose-external=loadbalancer`, MySQL Router K8s will provide as endpoints comma-separated node:port values of the load balancer nodes associated with the MySQL Router K8s service.
+
 ```shell
-TODO
+$ juju run data-integrator/0 get-credentials
+mysql:
+  data: '{"database": "test-database", "external-node-connectivity": "true", "requested-secrets":
+    "[\"username\", \"password\", \"tls\", \"tls-ca\", \"uris\"]"}'
+  database: test-database
+  endpoints: 10.0.0.44:6446
+  password: VRLNoVx6Br4Vn5SNHdoMK52Q
+  read-only-endpoints: 10.0.0.44:6447
+  username: relation-7_4fc92c2813524d6-8
+ok: "True"
+
+$ charmed-mysql.mysql -h 10.0.0.44 -P 6446 -u relation-7_4fc92c2813524d6-8 -pVRLNoVx6Br4Vn5SNHdoMK52Q
+mysql> show databases;
++--------------------+
+| Database           |
++--------------------+
+| information_schema |
+| performance_schema |
+| test-database      |
++--------------------+
+3 rows in set (0.00 sec)
+
+$ charmed-mysql.mysql -h 10.0.0.44 -P 6447 -u relation-7_4fc92c2813524d6-8 -pVRLNoVx6Br4Vn5SNHdoMK52Q
+mysql> show databases;
++--------------------+
+| Database           |
++--------------------+
+| information_schema |
+| performance_schema |
+| test-database      |
++--------------------+
+3 rows in set (0.00 sec)
 ```
-Read-only servers can be accessed using the `_readonly` suffix to the desired DB name:
-```shell
-TODO
-```
+
+[note]
+**Note**:  The K8s service created by MySQL Router K8s is owned by the K8s StatefulSet that represents the MySQL Router K8s juju application. Thus, the K8s service is cleaned up when the MySQL Router K8s application is removed. 
+[/note]
diff --git a/docs/overview.md b/docs/overview.md
@@ -56,6 +56,7 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
 | 2 | h-contribute | [Contribute](/t/14528) |
 | 1 | reference | [Reference]() |
 | 2 | r-releases-group | [Release Notes](/t/12201) |
+| 3 | r-releases-rev531 | [Revision 530/531](/t/16134) |
 | 3 | r-releases-rev155 | [Revision 154/155](/t/15354) |
 | 3 | r-releases-rev117 | [Revision 117](/t/14074) |
 | 3 | r-releases-rev96 | [Revision 96](/t/13523) |
@@ -72,7 +73,6 @@ This MySQL Router K8s charm is an official distribution of MySQL Router. It’s
 [/details]
 
 
-
 # Redirects
 
 [details=Mapping table]

diff --git a/docs/reference/r-releases-group.md b/docs/reference/r-releases-group.md
@@ -2,6 +2,7 @@
 
 Canonical publishes here release notes for production ready revisions available in [CharmHub](https://charmhub.io) [channels](https://juju.is/docs/sdk/channel):
 
+* [revision 530/531](/t/16134) in `8.0/edge`
 * [revision 154/155](/t/15354) in `8.0/stable`
 * [revision 117](/t/14074) in `8.0/stable`
 * [revision 96](/t/13523) in `8.0/stable`

diff --git a/docs/reference/r-releases-rev531.md b/docs/reference/r-releases-rev531.md
@@ -0,0 +1,82 @@
+> Reference > Release Notes > [All revisions] > Revision 530/531
+
+# Revision 530/531
+
+> **WARNING**: This is WIP release notes and will be announced soon. Try `8.0/candidate` if you need an early access.
+
+Dear community,
+
+Canonical's newest Charmed MySQL Router K8s operator has been published in the [8.0/stable channel]:
+* Revision 531 is built for `amd64` on Ubuntu 22.04 LTS
+* Revision 530 is built for `arm64` on Ubuntu 22.04 LTS
+
+If you are jumping over several stable revisions, check [previous release notes][All revisions] before upgrading.
+
+---
+
+## Highlights 
+* Updated MySQL Router to `v8.0.39` ([PR #308](https://github.com/canonical/mysql-router-k8s-operator/pull/308)) ([DPE-4573](https://warthogs.atlassian.net/browse/DPE-4573))
+* Add K8s LoadBalancer support via [expose-external](https://charmhub.io/mysql-router-k8s/configurations?channel=8.0/candidate#expose-external) config option ([PR #328](https://github.com/canonical/mysql-router-k8s-operator/pull/328)) ([DPE-5637](https://warthogs.atlassian.net/browse/DPE-5637))
+
+## Features and improvements
+* Add [COS Tracing](/t/14553) support using [Tempo K8s coordinator](https://charmhub.io/tempo-coordinator-k8s) ([PR #324](https://github.com/canonical/mysql-router-k8s-operator/pull/324)) ([DPE-5312](https://warthogs.atlassian.net/browse/DPE-5312))
+* Truncated TLS common name to 64 characters ([PR #318](https://github.com/canonical/mysql-router-k8s-operator/pull/318))
+* Bumped supported juju versions ([PR #325](https://github.com/canonical/mysql-router-k8s-operator/pull/325)) ([DPE-5625](https://warthogs.atlassian.net/browse/DPE-5625))
+  * `v2.9.50` → `v2.9.51`
+  * `v3.4.5` → `v3.6.1`
+
+<!--## Bugfixes and maintenance-->
+
+[details=Libraries, testing, and CI]
+
+* Switched from tox build wrapper to `charmcraft.yaml` overrides ([PR #319](https://github.com/canonical/mysql-router-k8s-operator/pull/319))
+* Test against juju 3.6/candidate + upgrade dpw to v23.0.5 ([PR #335](https://github.com/canonical/mysql-router-k8s-operator/pull/335))
+* Run juju 3.6 nightly tests against 3.6/stable ([PR #337](https://github.com/canonical/mysql-router-k8s-operator/pull/337))
+* Run tests on juju 3.6 on a nightly schedule ([PR #311](https://github.com/canonical/mysql-router-k8s-operator/pull/311)) ([DPE-4976](https://warthogs.atlassian.net/browse/DPE-4976))
+* Update canonical/charming-actions action to v2.6.3 ([PR #280](https://github.com/canonical/mysql-router-k8s-operator/pull/280))
+* Update data-platform-workflows to v23 ([PR #326](https://github.com/canonical/mysql-router-k8s-operator/pull/326))
+* Update dependency canonical/microk8s to v1.31 ([PR #316](https://github.com/canonical/mysql-router-k8s-operator/pull/316))
+* Update dependency cryptography to v43 [SECURITY] ([PR #317](https://github.com/canonical/mysql-router-k8s-operator/pull/317))
+* Update Juju agents (patch) ([PR #287](https://github.com/canonical/mysql-router-k8s-operator/pull/287))
+[/details]
+
+## Requirements and compatibility
+* (increased) MySQL version: `v8.0.37` → `v8.0.39`
+* (increased) Minimum Juju 2 version: `v2.9.50` → `v2.9.51`
+* (increased) Minimum Juju 3 version: `v3.4.5` → `v3.6.1`
+
+See the [system requirements] for more details about Juju versions and other software and hardware prerequisites.
+
+### Packaging
+
+This charm is based on the Charmed MySQL [rock image]. It packages:
+* [mysql-router] `v8.0.39`
+* [mysql-shell] `v8.0.38`
+* [prometheus-mysqlrouter-exporter] `v5.0.1`
+
+See the [`/lib/charms` directory on GitHub] for more details about all supported libraries.
+
+See the [`metadata.yaml` file on GitHub] for a full list of supported interfaces.
+
+<!-- Topics -->
+[All revisions]: /t/12201
+[system requirements]: /t/12179
+
+<!-- GitHub -->
+[`/lib/charms` directory on GitHub]: https://github.com/canonical/mysql-router-k8s-operator/tree/main/lib/charms
+[`metadata.yaml` file on GitHub]: https://github.com/canonical/mysql-router-k8s-operator/blob/main/metadata.yaml
+
+<!-- Charmhub -->
+[8.0/stable channel]: https://charmhub.io/mysql-router?channel=8.0/stable
+
+<!-- Snap/Rock -->
+[`charmed-mysql-router` packaging]: https://github.com/canonical/charmed-mysql-router-rock
+
+[MySQL Libraries tab]: https://charmhub.io/mysql/libraries
+
+[snap]: https://github.com/canonical/charmed-mysql-snap/releases/tag/rev114
+[rock image]: https://github.com/canonical/charmed-mysql-rock/pkgs/container/charmed-mysql
+
+[mysql-router]: https://launchpad.net/ubuntu/+source/mysql-8.0/
+[mysql-shell]: https://launchpad.net/~data-platform/+archive/ubuntu/mysql-shell
+[prometheus-mysqlrouter-exporter]: https://launchpad.net/~data-platform/+archive/ubuntu/mysqlrouter-exporter