diff --git a/.github/workflows/sync_docs.yaml b/.github/workflows/sync_docs.yaml index ca6b03804..165ca1222 100644 --- a/.github/workflows/sync_docs.yaml +++ b/.github/workflows/sync_docs.yaml @@ -18,7 +18,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: Open PR with docs changes - uses: canonical/discourse-gatekeeper@main + uses: canonical/discourse-gatekeeper@stable id: docs-pr with: discourse_host: discourse.charmhub.io diff --git a/docs/how-to/h-monitor/h-enable-monitoring.md b/docs/how-to/h-monitor/h-enable-monitoring.md deleted file mode 100644 index e9315c3d5..000000000 --- a/docs/how-to/h-monitor/h-enable-monitoring.md +++ /dev/null @@ -1,121 +0,0 @@ -# Enable monitoring - -> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju run ...` with `juju run-action --wait ...` and `juju integrate` with `juju relate` for Juju 2.9 - -Enabling monitoring requires that you: - -* [Have a Charmed MySQLRouter K8s deployed](https://charmhub.io/mysql-router/docs/t-deploy-charm?channel=dpe/edge) -* [Deploy cos-lite bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) - -Switch to the COS K8s environment and offer COS interfaces to be cross-model related with Charmed MySQLRouter K8s model: - -```shell -# Switch to the Kubernetes controller, on the COS model -juju switch : - -juju offer grafana:grafana-dashboard -juju offer loki:logging -juju offer prometheus:receive-remote-write -``` - -Switch to the Charmed MySQLRouter K8s model, find offers and consume them: - -```shell -# We are on the Kubernetes controller, on the COS model. Switch the mysqlrouter model -juju switch : - -juju find-offers : # Do not miss the ':' here! -``` - -A similar output should appear, if `k8s` is the k8s controller name and `cos` is the model where cos-lite has been deployed: - -```shell -Store URL Access Interfaces -k8s admin/cos.grafana admin grafana_dashboard:grafana-dashboard -k8s admin/cos.loki admin loki_push_api:logging -k8s admin/cos.prometheus admin prometheus_remote_write:receive-remote-write -``` - -Consume the offers to be reachable in the current model: - -```shell -juju consume k8s:admin/cos.grafana -juju consume k8s:admin/cos.loki -juju consume k8s:admin/cos.prometheus -``` - -Now, deploy ‘[grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s)’ and integrate (relate) it with Charmed MySQLRouter K8s, then later integrate (relate) `grafana-agent-k8s` with the consumed COS offers: - -```shell -juju deploy grafana-agent-k8s --trust - -juju integrate grafana-agent-k8s grafana -juju integrate grafana-agent-k8s loki -juju integrate grafana-agent-k8s prometheus - -juju integrate grafana-agent-k8s mysql-router-k8s:grafana-dashboard -juju integrate grafana-agent-k8s mysql-router-k8s:logging -juju integrate grafana-agent-k8s mysql-router-k8s:metrics-endpoint -``` - -After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allow access for Charmed MySQLRouter K8s logs on Loki. - -An example of `juju status` on Charmed MySQLRouter K8s model: - -```shell -ubuntu@localhost:~$ juju status -Model Controller Cloud/Region Version SLA Timestamp -database k8s microk8s/localhost 3.1.8 unsupported 13:27:08Z - -SAAS Status Store URL -grafana active k8s admin/cos.grafana -loki active k8s admin/cos.loki -prometheus active k8s admin/cos.prometheus - -App Version Status Scale Charm Channel Rev Address Exposed Message -grafana-agent-k8s 0.35.2 active 1 grafana-agent-k8s stable 64 10.152.183.141 no -mysql-k8s 8.0.35-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/stable 127 10.152.183.105 no -mysql-router-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 102 10.152.183.92 no -mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 10.152.183.35 no - -Unit Workload Agent Address Ports Message -grafana-agent-k8s/0* active idle 10.1.241.243 -mysql-k8s/0* active idle 10.1.241.239 Primary -mysql-router-k8s/0* active idle 10.1.241.240 -mysql-test-app/0* active idle 10.1.241.241 -``` - -An example of `juju status` on the COS K8s model: - -```shell -ubuntu@localhost:~$ juju status -Model Controller Cloud/Region Version SLA Timestamp -cos k8s microk8s/localhost 3.1.8 unsupported 13:28:02Z - -App Version Status Scale Charm Channel Rev Address Exposed Message -alertmanager 0.27.0 active 1 alertmanager-k8s stable 106 10.152.183.197 no -catalogue active 1 catalogue-k8s stable 33 10.152.183.38 no -grafana 9.5.3 active 1 grafana-k8s stable 106 10.152.183.238 no -loki 2.9.4 active 1 loki-k8s stable 124 10.152.183.84 no -prometheus 2.49.1 active 1 prometheus-k8s stable 171 10.152.183.182 no -traefik 2.10.5 active 1 traefik-k8s stable 174 10.0.0.44 no - -Unit Workload Agent Address Ports Message -alertmanager/0* active idle 10.1.241.222 -catalogue/0* active idle 10.1.241.225 -grafana/0* active idle 10.1.241.228 -loki/0* active idle 10.1.241.226 -prometheus/0* active idle 10.1.241.227 -traefik/0* active idle 10.1.241.221 - -Offer Application Charm Rev Connected Endpoint Interface Role -grafana grafana grafana-k8s 106 2/2 grafana-dashboard grafana_dashboard requirer -loki loki loki-k8s 124 2/2 logging loki_push_api provider -prometheus prometheus prometheus-k8s 171 2/2 receive-remote-write prometheus_remote_write provider -``` - -To connect Grafana WEB interface, follow the COS section “[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s#heading--browse-dashboards)”: - -```shell -juju run grafana/leader get-admin-password --model : -``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index dbd23568f..000000000 --- a/docs/index.md +++ /dev/null @@ -1,69 +0,0 @@ -# MySQL Router K8s Documentation - -The MySQL Router K8s Operator delivers automated operations management from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/) on the [MySQL Router Community Edition](https://www.mysql.com/products/community/) lightweight middleware that provides transparent routing between your application and back-end MySQL Servers. It is an open source, end-to-end, production-ready data platform component [on top of Juju](https://juju.is/). - -![image|690x424](upload://vpevillwv3S9C44LDFBxkGCxpGq.png) - -MySQL Router is part of InnoDB Cluster, and is lightweight middleware that provides transparent routing between your application and back-end MySQL Servers. It can be used for a wide variety of use cases, such as providing high availability and scalability by effectively routing database traffic to appropriate back-end MySQL Servers. The pluggable architecture also enables developers to extend MySQL Router for custom use cases. - -This MySQL Router K8s operator charm comes in two flavours to deploy and operate MySQL Router on [physical/virtual machines](https://github.com/canonical/mysql-router-operator) and [Kubernetes](https://github.com/canonical/mysql-router-k8s-operator). Both offer features identical set of features and simplifies deployment, scaling, configuration and management of MySQL Router in production at scale in a reliable way. - -## Project and community - -This MySQL Router K8s charm is an official distribution of MySQL Router. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback. -- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct) -- [Join the Discourse forum](https://discourse.charmhub.io/tag/mysql-router) -- [Contribute](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/mysql-router-k8s-operator/issues/new/choose) -- Explore [Canonical Data Fabric solutions](https://canonical.com/data) -- [Contacts us](/t/12177) for all further questions - -## In this documentation - -| | | -|--|--| -| [Tutorials](/t/12176)
Get started - a hands-on introduction to using Charmed MySQL operator for new users
| [How-to guides](/t/12233)
Step-by-step guides covering key operations and common tasks | -| [Reference](/t/12201)
Technical information - specifications, APIs, architecture | [Explanation](/t/12223)
Concepts - discussion and clarification of key topics | - -# Contents - -1. [Tutorial](tutorial) - 1. [1. Introduction](tutorial/t-overview.md) - 1. [2. Set up the environment](tutorial/t-setup-environment.md) - 1. [3. Deploy MySQL Router](tutorial/t-deploy-charm.md) - 1. [4. Manage units](tutorial/t-managing-units.md) - 1. [5. Enable security](tutorial/t-enable-security.md) - 1. [6. Cleanup environment](tutorial/t-cleanup-environment.md) -1. [How To](how-to) - 1. [Setup](how-to/h-setup) - 1. [Deploy on MicroK8s](how-to/h-setup/h-deploy-microk8s.md) - 1. [Manage units](how-to/h-setup/h-manage-units.md) - 1. [Enable encryption](how-to/h-setup/h-enable-encryption.md) - 1. [Manage applications](how-to/h-setup/h-manage-app.md) - 1. [Monitor (COS)](how-to/h-monitor) - 1. [Enable monitoring](how-to/h-monitor/h-enable-monitoring.md) - 1. [Upgrade](how-to/h-upgrade) - 1. [Intro](how-to/h-upgrade/h-upgrade-intro.md) - 1. [Major upgrade](how-to/h-upgrade/h-upgrade-major.md) - 1. [Major rollback](how-to/h-upgrade/h-rollback-major.md) - 1. [Minor upgrade](how-to/h-upgrade/h-upgrade-minor.md) - 1. [Minor rollback](how-to/h-upgrade/h-rollback-minor.md) -1. [Reference](reference) - 1. [Release Notes](reference/r-releases-group) - 1. [All releases](reference/r-releases-group/r-releases.md) - 1. [Revision 112](reference/r-releases-group/r-releases-rev112.md) - 1. [Revision 96](reference/r-releases-group/r-releases-rev96.md) - 1. [Revision 82](reference/r-releases-group/r-releases-rev82.md) - 1. [Revision 69](reference/r-releases-group/r-releases-rev69.md) - 1. [Requirements](reference/r-requirements.md) - 1. [Contributing](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md) - 1. [Testing](reference/r-testing.md) - 1. [Actions](https://charmhub.io/mysql-router-k8s/actions) - 1. [Configurations](https://charmhub.io/mysql-router-k8s/configure) - 1. [Libraries](https://charmhub.io/mysql-router-k8s/libraries) - 1. [Integrations](https://charmhub.io/mysql-router-k8s/integrations) - 1. [Resources](https://charmhub.io/mysql-router-k8s/resources) - 1. [Contacts](reference/r-contacts.md) -1. [Explanation](explanation) - 1. [Interfaces/endpoints](explanation/e-interfaces.md) - 1. [Statuses](explanation/e-statuses.md) - 1. [Juju](explanation/e-juju-details.md) \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev112.md b/docs/reference/r-releases-group/r-releases-rev112.md deleted file mode 100644 index 53a29395e..000000000 --- a/docs/reference/r-releases-group/r-releases-rev112.md +++ /dev/null @@ -1,52 +0,0 @@ ->Reference > Release Notes > [All revisions](/t/12201) > Revision 112 -# Revision 112 (`8.0/candidate` only) - -TODO: DD, MM, YYYY - -Dear community, - -We'd like to announce that Canonical's newest Charmed MySQL Router K8s operator has been published in the '8.0/stable' [channel](https://charmhub.io/mysql-router-k8s/docs/r-releases?channel=8.0/stable) :tada: - -[note] -If you are jumping over several stable revisions, make sure to check [previous release notes](/t/12201) before upgrading to this revision. -[/note] - -## Features you can start using today - -* 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)] -* [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)] -* [Observability with COS](/t/14101) [[PR#210](https://github.com/canonical/mysql-router-k8s-operator/pull/210)] -* Router version displayed in upgrade status [[PR#230](https://github.com/canonical/mysql-router-k8s-operator/pull/230)] -* All the functionality from [previous revisions](/t/12201) - -## Bugfixes - -* Updated charmed-mysql ROCK image to latest version [[PR#237](https://github.com/canonical/mysql-router-k8s-operator/pull/237)] -* Removed redundant upgrade check [[PR#234](https://github.com/canonical/mysql-router-k8s-operator/pull/234)] -* Ported over changes from VM operator related to external connectivity [[PR#225](https://github.com/canonical/mysql-router-k8s-operator/pull/225)] -* Updated `resume-upgrade` action `force` description [[PR#232](https://github.com/canonical/mysql-router-k8s-operator/pull/232)] -* Fixed issue if incompatible upgrade is forced [[PR#231](https://github.com/canonical/mysql-router-k8s-operator/pull/231)] - -Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/mysql-router-k8s-operator/issues) platforms. -[GitHub Releases](https://github.com/canonical/mysql-router-k8s-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision. - -## Inside the charms - -* 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` -* Principal charms supports the latest LTS series 22.04 only - -## Technical notes - -* Upgrade (`juju refresh`) is possible from revision 69+ -* Use this operator together with modern operator [Charmed MySQL K8s](https://charmhub.io/mysql-k8s) -* Please check restrictions from [previous release notes](https://charmhub.io/mysql-router-k8s/docs/r-releases) - -## Contact us - -Charmed MySQL Router K8s is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback. -* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/mysql-router-k8s-operator/issues) -* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File) -* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel. \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases.md b/docs/reference/r-releases-group/r-releases.md deleted file mode 100644 index 37571cd13..000000000 --- a/docs/reference/r-releases-group/r-releases.md +++ /dev/null @@ -1,10 +0,0 @@ -# Release Notes - -Canonical publishes here release notes for production ready revisions available in [CharmHub](https://charmhub.io) [channels](https://juju.is/docs/sdk/channel): - -* [revision 112](/t/14074) in `8.0/candidate` (WIP) -* [revision 96](/t/13523) in `8.0/stable` -* [revision 82](/t/12796) in `8.0/stable` -* [revision 69](/t/12202) in `8.0/stable` - -All other [risks](https://juju.is/docs/sdk/channel#heading--risk) (`candidate`, `beta`, `edge`) are NOT recommended for production usage. \ No newline at end of file diff --git a/docs/tutorial/t-enable-security.md b/docs/tutorial/t-enable-security.md deleted file mode 100644 index fa70f8267..000000000 --- a/docs/tutorial/t-enable-security.md +++ /dev/null @@ -1,80 +0,0 @@ ->This is part of the [Charmed MySQLRouter K8s Tutorial](/t/12176). Please refer to this page for more information and the overview of the content. - -# Enable encryption with TLS - -[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a protocol used to encrypt data exchanged between two applications. Essentially, it secures data transmitted over a network. - -Typically, enabling TLS internally within a highly available database or between a highly available database and client/server applications requires a high level of expertise. This has all been encoded into Charmed MySQL Router K8s so that configuring TLS requires minimal effort on your end. - -TLS is enabled by integrating Charmed MySQL Router K8s with the [Self Signed Certificates Charm](https://charmhub.io/self-signed-certificates). This charm centralises TLS certificate management consistently and handles operations like providing, requesting, and renewing TLS certificates. - -In this section, you will learn how to enable security in your MySQL Router K8s deployment using TLS encryption. - -[note type="caution"] -**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.** - -Check [this guide](/t/11664) for an overview of the TLS certificates charms available. -[/note] - ---- - -## Enable TLS -Before enabling TLS on Charmed MySQL Router K8s, we must first deploy the `self-signed-certificates` charm: -```shell -juju deploy self-signed-certificates --config ca-common-name="Tutorial CA" -``` - -Wait until `self-signed-certificates` is up and active with `juju status --watch 1s` to monitor the progress. -```shell -Model Controller Cloud/Region Version SLA Timestamp -database k8s microk8s/localhost 3.1.8 unsupported 12:10:33Z - -App Version Status Scale Charm Channel Rev Address Exposed Message -mysql-k8s 8.0.35-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/stable 127 10.152.183.101 no -mysql-router-k8s 8.0.36-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 102 10.152.183.92 no -mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 10.152.183.224 no -self-signed-certificates active 1 self-signed-certificates stable 72 10.152.183.114 no - -Unit Workload Agent Address Ports Message -mysql-k8s/0* active idle 10.1.241.252 Primary -mysql-router-k8s/0* active idle 10.1.241.253 -mysql-test-app/0* active idle 10.1.241.254 -self-signed-certificates/0* active idle 10.1.241.255 -``` - -To enable TLS on Charmed MySQLRouter K8s, integrate the two applications: -```shell -juju integrate mysql-router self-signed-certificates -``` - -### Check the TLS certificate in use: -Use `openssl` to connect to MySQLRouter K8s in the juju machine, and check the TLS certificate in use: -```shell -ubuntu@localhost:~$ juju ssh mysql-router-k8s/0 "openssl s_client -showcerts -starttls mysql -connect 127.0.0.1:6446 < /dev/null | openssl x509 -text | grep Issuer" -... - Issuer: C = US, CN = Tutorial CA -... -``` - -Congratulations! MySQLRouter K8s is now using a TLS certificate generated by the external application `self-signed-certificates`. - -## Disable TLS -To remove the external TLS and return to the locally generated one, unrelate the applications: -```shell -juju remove-relation mysql-router self-signed-certificates -``` - -### Check the TLS certificate in use: -```shell -ubuntu@localhost:~$ juju ssh mysql-router-k8s/0 "openssl s_client -showcerts -starttls mysql -connect 127.0.0.1:6446 < /dev/null | openssl x509 -text | grep Issuer" -``` - -The output should be similar to: -```shell -... - Issuer: CN = MySQL_Router_Auto_Generated_CA_Certificate -... -``` - - -The Charmed MySQLRouter K8s application reverted to the placeholder certificate that was created locally during the MySQLRouter K8s installation. \ No newline at end of file