From 07990ef5e3af5459f5e56b55385c1ebbf3eecaef Mon Sep 17 00:00:00 2001 From: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 01:19:06 +0000 Subject: [PATCH] Sync docs from Discourse --- docs/how-to/h-external-access.md | 170 ++++++++++++++++++++++------ docs/overview.md | 2 +- docs/reference/r-releases-group.md | 1 + docs/reference/r-releases-rev531.md | 82 ++++++++++++++ 4 files changed, 222 insertions(+), 33 deletions(-) create mode 100644 docs/reference/r-releases-rev531.md diff --git a/docs/how-to/h-external-access.md b/docs/how-to/h-external-access.md index 9b47433a8..cf2d6becb 100644 --- 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 -``` +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 -``` \ No newline at end of file + +[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] \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index 2f31e5a60..f827aaaf1 100644 --- 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 index 13b539136..0d48dcb1b 100644 --- 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 new file mode 100644 index 000000000..d8e991bbc --- /dev/null +++ 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` + + + +[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. + + +[All revisions]: /t/12201 +[system requirements]: /t/12179 + + +[`/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 + + +[8.0/stable channel]: https://charmhub.io/mysql-router?channel=8.0/stable + + +[`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 \ No newline at end of file