From efad9e5033a88ac995434c8ba842d8f8455f9de7 Mon Sep 17 00:00:00 2001 From: Andreia Velasco Date: Mon, 24 Jun 2024 13:16:58 +0200 Subject: [PATCH] Removed docs folder and deleted base-content tag (#269) ## Issue Discourse gatekeeper fails due to the page before "Reference" (i.e. ("Minor rollback") being too far nested ## Solution As a temporary workaround, added a new page "[How to contribute](https://discourse.charmhub.io/t/how-to-contribute/14528)" in between "Minor rollback" and "Reference": Workflow still fails because it's using the previously generated index. This PR is to reset the docs by deleting the `/docs` folder and removing the `discourse-gatekeeper/base-content` tag. --- docs/explanation/e-interfaces.md | 33 ---- docs/explanation/e-juju-details.md | 43 ----- docs/explanation/e-statuses.md | 20 --- docs/how-to/h-monitor/h-enable-monitoring.md | 121 ------------- docs/how-to/h-setup/h-deploy-microk8s.md | 35 ---- docs/how-to/h-setup/h-enable-encryption.md | 64 ------- docs/how-to/h-setup/h-manage-app.md | 34 ---- docs/how-to/h-setup/h-manage-units.md | 20 --- docs/how-to/h-upgrade/h-rollback-major.md | 5 - docs/how-to/h-upgrade/h-rollback-minor.md | 44 ----- docs/how-to/h-upgrade/h-upgrade-intro.md | 17 -- docs/how-to/h-upgrade/h-upgrade-major.md | 5 - docs/how-to/h-upgrade/h-upgrade-minor.md | 163 ------------------ docs/index.md | 69 -------- docs/reference/r-contacts.md | 18 -- .../r-releases-group/r-releases-rev112.md | 52 ------ .../r-releases-group/r-releases-rev69.md | 40 ----- .../r-releases-group/r-releases-rev82.md | 43 ----- .../r-releases-group/r-releases-rev96.md | 39 ----- docs/reference/r-releases-group/r-releases.md | 10 -- docs/reference/r-requirements.md | 30 ---- docs/reference/r-testing.md | 71 -------- docs/tutorial/t-cleanup-environment.md | 19 -- docs/tutorial/t-deploy-charm.md | 148 ---------------- docs/tutorial/t-enable-security.md | 80 --------- docs/tutorial/t-managing-units.md | 77 --------- docs/tutorial/t-overview.md | 20 --- docs/tutorial/t-setup-environment.md | 39 ----- 28 files changed, 1359 deletions(-) delete mode 100644 docs/explanation/e-interfaces.md delete mode 100644 docs/explanation/e-juju-details.md delete mode 100644 docs/explanation/e-statuses.md delete mode 100644 docs/how-to/h-monitor/h-enable-monitoring.md delete mode 100644 docs/how-to/h-setup/h-deploy-microk8s.md delete mode 100644 docs/how-to/h-setup/h-enable-encryption.md delete mode 100644 docs/how-to/h-setup/h-manage-app.md delete mode 100644 docs/how-to/h-setup/h-manage-units.md delete mode 100644 docs/how-to/h-upgrade/h-rollback-major.md delete mode 100644 docs/how-to/h-upgrade/h-rollback-minor.md delete mode 100644 docs/how-to/h-upgrade/h-upgrade-intro.md delete mode 100644 docs/how-to/h-upgrade/h-upgrade-major.md delete mode 100644 docs/how-to/h-upgrade/h-upgrade-minor.md delete mode 100644 docs/index.md delete mode 100644 docs/reference/r-contacts.md delete mode 100644 docs/reference/r-releases-group/r-releases-rev112.md delete mode 100644 docs/reference/r-releases-group/r-releases-rev69.md delete mode 100644 docs/reference/r-releases-group/r-releases-rev82.md delete mode 100644 docs/reference/r-releases-group/r-releases-rev96.md delete mode 100644 docs/reference/r-releases-group/r-releases.md delete mode 100644 docs/reference/r-requirements.md delete mode 100644 docs/reference/r-testing.md delete mode 100644 docs/tutorial/t-cleanup-environment.md delete mode 100644 docs/tutorial/t-deploy-charm.md delete mode 100644 docs/tutorial/t-enable-security.md delete mode 100644 docs/tutorial/t-managing-units.md delete mode 100644 docs/tutorial/t-overview.md delete mode 100644 docs/tutorial/t-setup-environment.md diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md deleted file mode 100644 index c84365c1f..000000000 --- a/docs/explanation/e-interfaces.md +++ /dev/null @@ -1,33 +0,0 @@ -# Interfaces/endpoints - -MySQL Router K8s supports modern ['mysql_client'](https://github.com/canonical/charm-relation-interfaces) interface. Applications can easily connect MySQL using ['data_interfaces'](https://charmhub.io/data-platform-libs/libraries/data_interfaces) library from ['data-platform-libs'](https://github.com/canonical/data-platform-libs/). - -### Modern `mysql_client` interface (`database` endpoint): - -Adding a relation is accomplished with `juju relate` (or `juju integrate` for Juju 3.x) via endpoint `database`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example: - -```shell -# Deploy Charmed MySQL K8s and MySQL Router K8s clusters with 3 nodes each -juju deploy mysql-k8s -n 3 --trust -juju deploy mysql-router-k8s -n 3 --trust --channel 8.0 - -# Deploy the relevant charms, e.g. mysql-test-app -juju deploy mysql-test-app - -# Relate all applications -juju integrate mysql-k8s mysql-router-k8s -juju integrate mysql-router-k8s:database mysql-test-app - -# Check established relation (using mysql_client interface): -juju status --relations - -# Example of the properly established relation: -# > Integration provider Requirer Interface Type Message -# > mysql-k8s:database mysql-router-k8s:backend-database mysql_client regular -# > mysql-router-k8s:database mysql-test-app:database mysql_client regular -# > ... -``` - -**Note:** In order to relate with Charmed MySQL K8s, every table created by the client application must have a primary key. This is required by the [group replication plugin](https://dev.mysql.com/doc/refman/8.0/en/group-replication-requirements.html) enabled in this charm. - -See all the charm interfaces [here](https://charmhub.io/mysql-router-k8s/integrations). \ No newline at end of file diff --git a/docs/explanation/e-juju-details.md b/docs/explanation/e-juju-details.md deleted file mode 100644 index 2a3261aff..000000000 --- a/docs/explanation/e-juju-details.md +++ /dev/null @@ -1,43 +0,0 @@ -# Juju tech details - -[Juju](https://juju.is/) is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms. - -This [charm](https://charmhub.io/mysql-router-k8s) is an operator - business logic encapsulated in reusable software packages that automate every aspect of an application's life. Charms are shared via [CharmHub](https://charmhub.io/). - -See also: - -* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju) -* [Charm SDK](https://juju.is/docs/sdk) - -## Breaking changes between Juju 2.9.x and 3.x - -As this charm documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes. - -Breaking changes have been introduced in the Juju client between versions 2.9.x and 3.x. These are caused by the renaming and re-purposing of several commands - functionality and command options remain unchanged. - -In the context of this guide, the pertinent changes are shown here: - -|2.9.x|3.x| -| --- | --- | -|**add-relation**|**integrate**| -|**relate**|**integrate**| -|**run**|**exec**| -|**run-action --wait**|**run**| - -See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for the comprehensive list of changes. - -The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example: - -### Juju 3.x: -```shell -juju integrate mysql-router-k8s:database mysql-test-app - -juju run mysql-k8s/leader get-password -``` -### Juju 2.9.x: -```shell -juju relate mysql-router-k8s:database mysql-test-app - -juju run-action --wait mysql-k8s/leader get-password -``` -> :tipping_hand_man: [The document based on OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x) \ No newline at end of file diff --git a/docs/explanation/e-statuses.md b/docs/explanation/e-statuses.md deleted file mode 100644 index 471175b5e..000000000 --- a/docs/explanation/e-statuses.md +++ /dev/null @@ -1,20 +0,0 @@ -# Charm Statuses - -> :warning: **WARNING** : it is an work-in-progress article. Do NOT use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic. - -The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses: - -| Juju Status | Message | Expectations | Actions | -|-------|-------|-------|-------| -| **active** | any | Normal charm operations | No actions required | -| **waiting** | any | Charm is waiting for relations to be finished | No actions required | -| **maintenance** | any | Charm is performing the internal maintenance (e.g. re-configuration) | No actions required | -| **blocked** | any | The manual user activity is required! | Follow the message hints (see below) | -| **blocked** | Missing relation: ... | Normal behavior, charm needs all relations to work. | Follow the hint to establish a proper relation. | -| **blocked** | Router was manually removed from MySQL ClusterSet. Remove & re-deploy unit | Scale-down temporary message OR split-brain for the unknown reason. | Wait to finish scale-down or remove and re-deploy unit if the message is persistent.| -| **blocked** | ... app requested unsupported extra user role on database endpoint | Unsupported [role](https://charmhub.io/data-integrator/configure#extra-user-roles) requested. | Use supported extra-user-role. | -| **blocked** | Upgrade incompatible. Rollback to previous revision with `juju refresh` | Incompatible charm channel/revision chosen. | [Rollback](/t/12239) the charm. | -| **blocked** | Upgrading. Verify highest unit is healthy & run `resume-upgrade ` action. To rollback, `juju refresh` to last revision | Normal behavior, application is being upgraded and waiting for user confirmation to continue or rollback | [Continue upgrade](/t/12238) or [rollback](/t/12239). | -| **error** | any | An unhanded internal error happened | Read the message hint and check the debug log to see the exception. Execute `juju resolve ` after addressing the root of the error state | -| **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible | -| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent | \ No newline at end of file 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/how-to/h-setup/h-deploy-microk8s.md b/docs/how-to/h-setup/h-deploy-microk8s.md deleted file mode 100644 index 70078728f..000000000 --- a/docs/how-to/h-setup/h-deploy-microk8s.md +++ /dev/null @@ -1,35 +0,0 @@ -# Deploy MySQL Router K8s - -Please follow the [MySQL Router K8s Tutorial](/t/12176) for technical details and explanations. - -Short story for your Ubuntu 22.04 LTS (`Wordpress` used as an client example for `MySQL Router`: -```shell -sudo snap install multipass -multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs -multipass shell my-vm - -juju add-model wordpress-demo -juju deploy mysql-k8s --channel 8.0/stable --trust # --config profile=testing -juju deploy mysql-router-k8s --channel 8.0/stable --trust - -juju integrate mysql-k8s mysql-router-k8s - -juju status --watch 1s -``` - -The expected result: -```shell -Model Controller Cloud/Region Version SLA Timestamp -wordpress-demo microk8s microk8s/localhost 3.1.6 unsupported 14:39:27+02:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/stable 99 10.152.183.189 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 blocked 1 mysql-router-k8s 8.0/stable 69 10.152.183.81 no Missing relation: database - -Unit Workload Agent Address Ports Message -mysql-k8s/0* active idle 10.1.12.61 Primary -mysql-router-k8s/0* active idle 10.1.12.16 -``` -The charm MySQL Router K8s is now waiting for relations with a client application, e.g. [mysql-test-app](https://charmhub.io/mysql-test-app), [wordpress](https://charmhub.io/wordpress-k8s), ... - -Check the [Testing](/t/12234) reference to test your deployment. \ No newline at end of file diff --git a/docs/how-to/h-setup/h-enable-encryption.md b/docs/how-to/h-setup/h-enable-encryption.md deleted file mode 100644 index 54b89b049..000000000 --- a/docs/how-to/h-setup/h-enable-encryption.md +++ /dev/null @@ -1,64 +0,0 @@ -[note] -**Note**: All commands are written for `juju >= v.3.1` - -If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022). -[/note] - -# How to enable TLS encryption - - - -This guide will show how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example. - -[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 - -First, deploy the TLS charm: -```shell -juju deploy self-signed-certificates -``` -To enable TLS, integrate the two applications: -```shell -juju integrate self-signed-certificates mysql-router-k8s -``` - -## Manage keys - -Updates to private keys for certificate signing requests (CSR) can be made via the `set-tls-private-key` action. Note that passing keys to external/internal keys should *only be done with* `base64 -w0`, *not* `cat`. - -With three replicas, this schema should be followed: - -Generate a shared internal (private) key: -```shell -openssl genrsa -out internal-key.pem 3072 -``` - -Apply the newly generated internal key on each `juju` unit: -```shell -juju run mysql-router-k8s/0 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)" -juju run mysql-router-k8s/1 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)" -juju run mysql-router-k8s/2 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)" -``` - -Updates can also be done with auto-generated keys with: - -```shell -juju run mysql-router-k8s/0 set-tls-private-key -juju run mysql-router-k8s/1 set-tls-private-key -juju run mysql-router-k8s/2 set-tls-private-key -``` - -## Disable TLS -Disable TLS by removing the integration: -```shell -juju remove-relation self-signed-certificates mysql-router-k8s -``` \ No newline at end of file diff --git a/docs/how-to/h-setup/h-manage-app.md b/docs/how-to/h-setup/h-manage-app.md deleted file mode 100644 index c63206619..000000000 --- a/docs/how-to/h-setup/h-manage-app.md +++ /dev/null @@ -1,34 +0,0 @@ -# How to manage related applications - -## Modern `mysql_client` interface: - -Relations to new applications are supported via the "[mysql_client](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/mysql_client/v0/README.md)" interface. To create a relation: - -```shell -juju relate mysql-router-k8s application -``` - -To remove a relation: - -```shell -juju remove-relation mysql-router-k8s application -``` - -All listed on CharmHub applications are available [here](https://charmhub.io/mysql-router-k8s/integrations), e.g.: - * [mysql-test-app](https://charmhub.io/mysql-test-app) - * [wordpress-k8s](https://charmhub.io/wordpress-k8s) - * [slurmdbd](https://charmhub.io/slurmdbd) - -## Legacy `mysql` interface: - -This charm does NOT support legacy `mysql` interface. - -## Internal operator user - -To rotate the internal router passwords, the relation with backend-database should be removed and related again. That process will generate a new user and password for the application, while retaining the requested database and data. - -```shell -juju remove-relation mysql-k8s mysql-router-k8s - -juju integrate mysql-k8s mysql-router-k8s -``` \ No newline at end of file diff --git a/docs/how-to/h-setup/h-manage-units.md b/docs/how-to/h-setup/h-manage-units.md deleted file mode 100644 index c4c757a09..000000000 --- a/docs/how-to/h-setup/h-manage-units.md +++ /dev/null @@ -1,20 +0,0 @@ -# How to deploy and manage units - -## Basic Usage - -To deploy a single unit of MySQL Router using its default configuration -```shell -juju deploy mysql-router-k8s --channel 8.0 --trust -``` - -To deploy MySQL Router in high-availability mode, specify the number of desired units with the `-n` option. -```shell -juju deploy mysql-router-k8s --channel 8.0 --trust -n -``` - -## Scaling - -Both scaling-up and scaling-down operations are performed using `juju scale-application`: -```shell -juju scale-application mysql-router-k8s -``` \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-rollback-major.md b/docs/how-to/h-upgrade/h-rollback-major.md deleted file mode 100644 index 8a3c18938..000000000 --- a/docs/how-to/h-upgrade/h-rollback-major.md +++ /dev/null @@ -1,5 +0,0 @@ -# Major Rollback - -> :information_source: **Example**: MySQL Router 9.0 -> MySQL Router 8.0 - -Currently, the charm supports MySQL Router 8.0 only; therefore, minor rollbacks are only possible. Canonical is NOT planning to support in-place rollbacks for the major MySQL Router version change as the old MySQL cluster installation with old MySQL Router will stay nearby and can be reused for the rollback. \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-rollback-minor.md b/docs/how-to/h-upgrade/h-rollback-minor.md deleted file mode 100644 index d1660c415..000000000 --- a/docs/how-to/h-upgrade/h-rollback-minor.md +++ /dev/null @@ -1,44 +0,0 @@ -# Minor Rollback - -> :information_source: **Example**: MySQL Router 8.0.34 -> MySQL Router 8.0.33
-(including simple charm revision bump: from revision 43 to revision 42) - -> **:warning: WARNING**: do NOT trigger `rollback` during the **running** `upgrade` action! It may cause unpredictable MySQL Cluster and/or MySQL Router state! - -## Minor rollback steps -1. **Rollback**. Perform the charm rollback using `juju refresh`. The unit with the maximal ordinal will be rolled back first, and the rollback will continue for the entire application. -2. **Check**. Make sure the charm and cluster are in healthy state again. - -## Manual Rollback - -After a `juju refresh`, case there any version incompatibilities in charm revisions or it dependencies, or any other unexpected failure in the upgrade process, the upgrade process will be halted an enter a failure state. - -Although the underlying MySQL Cluster and MySQL Router continue to work, it’s important to rollback the charm to previous revision so an update can be later attempted after a further inspection of the failure. - -To execute a rollback we take the same procedure as the upgrade, the difference being the charm revision to upgrade to. In case of this tutorial example, one would refresh the charm back to revision `88`, the steps being: - -## Step 1: Rollback - -When using the charm from charmhub: - -```shell -juju refresh mysql-router-k8s --revision=88 --trust -``` - -When deploying from a local charm file, you need to have the previous revision's `.charm` file and the `mysql-image` resource. Then, run: - -```shell -juju refresh mysql-router-k8s --trust --path= \ - --resource mysql-router-image= -``` -The resource reference can be found under the `upstream-source` key in the charm's `metadata.yaml` file. You can access this file by: -* Simply unpacking the `.charm` file -* Finding the corresponding [release](https://github.com/canonical/mysql-router-k8s-operator/releases) in the charm's GitHub repository and navigating to `metadata.yaml`. - -After the refresh command, the `juju` controller revision for the application will be back in sync with the running MySQL Router K8s revision. - -## Step 2: Check - -Future [improvement are planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state on pod/cluster on a low level. - -For now, use `juju status` to check the cluster [state](/t/11866). \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-upgrade-intro.md b/docs/how-to/h-upgrade/h-upgrade-intro.md deleted file mode 100644 index 434e4cc59..000000000 --- a/docs/how-to/h-upgrade/h-upgrade-intro.md +++ /dev/null @@ -1,17 +0,0 @@ -# MySQL Router K8s Upgrade - -Please choose the appropriate upgrade/rollback tutorial. - -Migration: - -* [Major upgrade](/t/12236), e.g. MySQL Router 8.0 -> MySQL Router 9.0. - -* [Major rollback](/t/12237), e.g. MySQL Router 9.0 -> MySQL Router 8.0. - -In-place minor upgrade: - -* [Minor upgrade](/t/12238), e.g. MySQL Router 8.0.33 -> MySQL Router 8.0.34
-(including charm revision bump 99 -> 102). - -* [Minor rollback](/t/12239), e.g. MySQL Router 8.0.34 -> MySQL Router 8.0.33
-(including charm revision return 102 -> 99). \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-upgrade-major.md b/docs/how-to/h-upgrade/h-upgrade-major.md deleted file mode 100644 index 7ff9ab53a..000000000 --- a/docs/how-to/h-upgrade/h-upgrade-major.md +++ /dev/null @@ -1,5 +0,0 @@ -# Major Upgrade - -> :information_source: **Example**: MySQL Router 8.0 -> MySQL Router 9.0 - -Currently, the charm supports MySQL Router 8.0 only; therefore, minor upgrades are only possible. The support of the following [MySQL LTS releases](https://blogs.oracle.com/mysql/post/introducing-mysql-innovation-and-longterm-support-lts-versions) is planned. Canonical is NOT planning to support in-place upgrades for the Major version change. The new MySQL Router will have to be installed nearby, and the data will be copied from the old to the new installation. After announcing the next MySQL major version support, the appropriate manual will be published here. \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-upgrade-minor.md b/docs/how-to/h-upgrade/h-upgrade-minor.md deleted file mode 100644 index ba62e590c..000000000 --- a/docs/how-to/h-upgrade/h-upgrade-minor.md +++ /dev/null @@ -1,163 +0,0 @@ -# Minor Upgrade - -> :information_source: **Example**: MySQL Router 8.0.33 -> MySQL Router 8.0.34
-(including simple charm revision bump: from revision 99 to revision 102) - -We strongly recommend to **NOT** perform any other extraordinary operations on Charmed MySQL K8s cluster and/or MySQL Router K8s, while upgrading. Some examples would be: - -1. Adding or removing units -2. Creating or destroying new relations -3. Changes in workload configuration -4. Upgrading other connected/related/integrated applications simultaneously - -The concurrency with other operations is not supported, and it can lead the cluster into inconsistent states. - -> **:warning: NOTE:** Make sure to have a [Charmed MySQL K8s backups](/t/9653) of your data when running any type of upgrades. - -> **:warning: TIP:** The MySQL Router K8s upgrade should take place **before** the Charmed MySQL K8s upgrade!! - -## Minor upgrade steps - -1. **Collect** all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do NOT skip this step. -2. (optional) **Scale up**: The new `sacrificial` unit will be the first one to be updated, and it will simplify the rollback procedure in case of the upgrade failure. -3. **Prepare** "Charmed MySQL K8s" Juju application for the in-place upgrade. See the step description below for all technical details executed by charm here. -4. **Upgrade**: Once started, only one unit of the app will be upgraded. In case of failure, roll back with `juju refresh`. -5. **Resume** upgrade: If the new unit is OK after the refresh, the upgrade can be resumed. All units in an app will be executed sequentially from highest to lowest unit number. -6. (optional) Consider [**rolling back**](/t/11749) in case of disaster. Please [inform and include us](https://chat.charmhub.io/charmhub/channels/data-platform) in your case scenario troubleshooting to trace the source of the issue and prevent it in the future. -7. (optional) **Scale back**: Remove no longer necessary K8s units created in step 2 (if any). -8. **Post-upgrade check**: Make sure all units are in the proper state and the cluster is healthy. - -## Step 1: Collect -[note] -This step is only valid when deploying from charmhub. If the deployment is of a local charm (revision is small, e.g. 0-10), make sure you save a copy of the current `.charm` file BEFORE going further. You might need it for rollback. -[/note] -The first step is to record the revision of the running application, as a safety measure for a rollback action. To accomplish this, simply run the `juju status` command and look for the deployed Charmed MySQL and MySQL Router revisions in the command output, e.g.: - -```shell -Model Controller Cloud/Region Version SLA Timestamp -upgrade microk8s microk8s/localhost 3.1.6 unsupported 15:32:04+02:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-k8s 8.0/stable 99 10.152.183.238 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-router-k8s 8.0/stable 69 10.152.183.184 no -mysql-test-app 0.0.2 active 1 mysql-test-app stable 26 10.152.183.36 no - -Unit Workload Agent Address Ports Message -mysql-k8s/0* active idle 10.1.12.24 Primary -mysql-k8s/1 active idle 10.1.12.36 -mysql-k8s/2 active idle 10.1.12.22 -mysql-router-k8s/0 active idle 10.1.12.28 -mysql-router-k8s/1 active idle 10.1.12.10 -mysql-router-k8s/2* active idle 10.1.12.5 -mysql-test-app/0* active idle 10.1.12.57 -``` - -For this example, the current revision is `99` for MySQL K8s and `69` for Router. Store it safely to use in case of rollback! - -## Step 2: Scale-up (optional) - -Optionally, it is recommended to scale the application up by one unit before starting the upgrade process. - -The new unit will be the first one to be updated, and it will assert that the upgrade is possible. In case of failure, having the extra unit will ease the rollback procedure, without disrupting service. More on the [Minor rollback](/t/12239) tutorial. - -```shell -juju scale-application mysql-k8s -juju scale-application mysql-router-k8s -``` - -Wait for the new unit up and ready. - -## Step 3: Prepare - -After the application has settled, it’s necessary to run the `pre-upgrade-check` action against the leader unit (for the MySQL Server only): - -```shell -juju run mysql-k8s/leader pre-upgrade-check -``` - -The action will configure the charm to minimize the amount of primary switchover, among other preparations for the upgrade process. After successful execution, charms are ready to be upgraded. - -## Step 4: Upgrade - -Use the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command to trigger the charm upgrade process. If using juju version 3 or higher, it is necessary to add the `--trust` option. - -```shell -# example with channel selection and juju 2.9.x -juju refresh mysql-router-k8s --channel 8.0/edge - -# example with channel selection and juju 3.x -juju refresh mysql-router-k8s --channel 8.0/edge --trust - -# example with specific revision selection -juju refresh mysql-router-k8s --revision=89 -``` - -After the Router upgrade is completed, upgrade the Server: -```shell -# example with channel selection and juju 2.9.x -juju refresh mysql-k8s --channel 8.0/edge - -# example with channel selection and juju 3.x -juju refresh mysql-k8s --channel 8.0/edge --trust - -# example with specific revision selection -juju refresh mysql-k8s --revision=89 -``` - -> **:information_source: IMPORTANT:** The Server upgrade will execute only on the highest ordinal unit, for the running example `mysql-k8s/2`, the `juju status` will look like*: - - - -> **:information_source: Note:** The unit should recover shortly after, but the time can vary depending on the amount of data written to the cluster while the unit was not part of the cluster. Please be patient on the huge installations. - -## Step 5: Resume - -After the unit is upgraded, the charm will set the unit upgrade state as completed. If deemed necessary, the user can further assert the success of the upgrade. If the unit is healthy within the cluster, the next step is to resume the upgrade process by running: - -```shell -juju run-action mysql-k8s/leader resume-upgrade --wait -``` - -The `resume-upgrade` will roll out the Server upgrade for the following unit, always from highest from lowest. For each successfully upgraded unit beyond the first, the process will roll out the next one automatically. - -```shell -Model Controller Cloud/Region Version SLA Timestamp -upgrade microk8s microk8s/localhost 3.1.6 unsupported 15:56:25+02:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -mysql-k8s 8.0.34-0ubuntu0.22.04.1 waiting 3/4 mysql-k8s 8.0/edge 109 10.152.183.238 no installing agent -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 4 mysql-router-k8s 8.0/edge 69 10.152.183.184 no -mysql-test-app 0.0.2 active 1 mysql-test-app stable 26 10.152.183.36 no - -Unit Workload Agent Address Ports Message -mysql-k8s/0* waiting idle 10.1.12.24 other units upgrading first... -mysql-k8s/1 unknown lost 10.1.12.36 agent lost, see 'juju show-status-log mysql-k8s/1' -mysql-k8s/2 maintenance idle 10.1.12.14 upgrade completed -mysql-k8s/3 maintenance idle 10.1.12.32 upgrade completed -mysql-router-k8s/0 active idle 10.1.12.28 -mysql-router-k8s/1 active idle 10.1.12.10 -mysql-router-k8s/2* active idle 10.1.12.5 -mysql-router-k8s/3 active idle 10.1.12.9 -mysql-test-app/0* active idle 10.1.12.57 -``` - -## Step 6: Rollback (optional) - -If the upgrade was incompatible, it’s important to roll back the charm to a previous revision so that an update can be later attempted after a further inspection of the failure. See the [minor rollback](/t/12239) guide. - -## Step 7: Scale-back - -Case the application scale was changed for the upgrade procedure, it is now safe to scale it back to the desired unit count: - -```shell -juju scale-application mysql-k8s -juju scale-application mysql-router-k8s -``` - -## Step 8: Check - -Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state on pod/cluster on a low level. - -For now, use `juju status` to see the cluster's [state](/t/12231). \ 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-contacts.md b/docs/reference/r-contacts.md deleted file mode 100644 index 61dc2b636..000000000 --- a/docs/reference/r-contacts.md +++ /dev/null @@ -1,18 +0,0 @@ -# Contact - -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/new/choose) -* 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. -[note] -Our legacy [Mattermost](https://chat.charmhub.io/charmhub/channels/data-platform) channel is read-only until January 31, 2025. -[/note] - - -## Useful links -* [Canonical Data Fabric](https://ubuntu.com/data/) -* [Charmed MySQL K8s](https://charmhub.io/mysql-k8s) -* [MySQL Router K8s](https://charmhub.io/mysql-router-k8s) -* [Git sources for MySQL Router K8s](https://github.com/canonical/mysql-router-k8s-operator) -* [Canonical Data Platform on Launchpad](https://launchpad.net/~data-platform) -* [Mailing list on Launchpad](https://lists.launchpad.net/data-platform/) \ 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-rev69.md b/docs/reference/r-releases-group/r-releases-rev69.md deleted file mode 100644 index 1d9f42d5f..000000000 --- a/docs/reference/r-releases-group/r-releases-rev69.md +++ /dev/null @@ -1,40 +0,0 @@ -# MySQL Router K8s revision 69 -October 20, 2023 - -Dear community, this is to inform you that new MySQL Router K8s is published in `8.0/stable` [charmhub](https://charmhub.io/mysql-router-k8s?channel=8.0/stable) channel for Kubernetes. - -## The features you can start using today: - -* [Add Juju 3 support](/t/12179) (Juju 2 is still supported) -* Charm [minor upgrades](/t/TODO) and [minor rollbacks](/t/TODO) -* Workload updated to [MySQL Router 8.0.34](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-34.html) -* [Support](https://charmhub.io/mysql-router-k8s/integrations?channel=8.0/stable) for modern `mysql_client` and `tls-certificates` interfaces -* Support `juju expose` -* New and complete documentation on CharmHub - -## Bugfixes included: - -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/Git commits for each revision. - -## What is inside the charms: - -* 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) -* Principal charms supports the latest LTS series “22.04” only. - -## Technical notes: - -* Upgrade (`juju refresh`) is possible from this revision 69+. -* Use this operator together with [Charmed MySQL K8s](https://charmhub.io/mysql-k8s) - -## How to reach us: - -If you would like to chat with us about your use-cases or ideas, you can reach us at [Matrix public channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) or [Discourse](https://discourse.charmhub.io/). Check all other contact details [here](/t/12177). - -Consider [opening a GitHub issue](https://github.com/canonical/mysql-router-k8s-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md) to the project! - -## Footer: - -It is the first stable release of the operator "MySQL Router K8s" by Canonical Data.
Well done, Team! \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev82.md b/docs/reference/r-releases-group/r-releases-rev82.md deleted file mode 100644 index 8db2ddb62..000000000 --- a/docs/reference/r-releases-group/r-releases-rev82.md +++ /dev/null @@ -1,43 +0,0 @@ -# MySQL Router K8s revision 82 -January 3, 2024 - -Dear community, this is to inform you that new MySQL Router K8s is published in `8.0/stable` [charmhub](https://charmhub.io/mysql-router-k8s?channel=8.0/stable) channel for Kubernetes. - -## The features you can start using today: - -* [[DPE-1799](https://warthogs.atlassian.net/browse/DPE-1799)] Add rotation of mysql-router logs in [[PR#143](https://github.com/canonical/mysql-router-k8s-operator/pull/143)] -* [[DPE-3022](https://warthogs.atlassian.net/browse/DPE-3022)] Updated data_platform_libs/data_interfaces to version 24 in [[PR#163](https://github.com/canonical/mysql-router-k8s-operator/pull/163)] -* [[DPE-2760](https://warthogs.atlassian.net/browse/DPE-2760)] Use "Relation Secrets" in [[PR#152](https://github.com/canonical/mysql-router-k8s-operator/pull/152)] -* [[DPE-2807](https://warthogs.atlassian.net/browse/DPE-2807)] Add discourse documentation gatekeeper sync in [[PR#149](https://github.com/canonical/mysql-router-k8s-operator/pull/149)] - -## Bugfixes included: - -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/Git commits for each revision. - -* Updated logrotate dateformat to tolerate more than 24hrs of uptime in [[PR#169](https://github.com/canonical/mysql-router-k8s-operator/pull/169)][[DPE-3063](https://warthogs.atlassian.net/browse/DPE-3063)] -* Fixed recovering from hook errors when creating/deleting MySQL users in [[PR#165](https://github.com/canonical/mysql-router-k8s-operator/pull/165)] -* Fixed upgrade compatibility check in [[PR#164](https://github.com/canonical/mysql-router-k8s-operator/pull/164)] -* Improved upgrade stability in [[PR#153](https://github.com/canonical/mysql-router-k8s-operator/pull/153)] -* Decreased verbosity for `httpx` and `httpcore` logger level to WARNING in [[PR#176](https://github.com/canonical/mysql-router-k8s-operator/pull/176)] -* Switch to `maintenance` Juju status (instead of `waiting`) while router is starting in [[PR#147](https://github.com/canonical/mysql-router-k8s-operator/pull/147)] - -## What is inside the charms: - -* 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 -* Principal charms supports the latest LTS series “22.04” only -* Subordinate charms support LTS “22.04” and “20.04” only - -## Technical notes: - -* Upgrade (`juju refresh`) is possible from this revision 69+ -* **WARNING**: Downgrade from revision 82 to revision 69 is not possible due to [[PR#158](https://github.com/canonical/mysql-router-k8s-operator/pull/158)] -* Use this operator together with a modern operator "[Charmed MySQL K8s](https://charmhub.io/mysql-k8s)" - -## How to reach us: - -If you would like to chat with us about your use-cases or ideas, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/data-platform) or [Discourse](https://discourse.charmhub.io/). Check all other contact details [here](/t/12177). - -Consider [opening a GitHub issue](https://github.com/canonical/mysql-router-k8s-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md) to the project! \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev96.md b/docs/reference/r-releases-group/r-releases-rev96.md deleted file mode 100644 index 3de8c08fe..000000000 --- a/docs/reference/r-releases-group/r-releases-rev96.md +++ /dev/null @@ -1,39 +0,0 @@ -# MySQL Router K8s revision 96 -March 22, 2024 - -Dear community, this is to inform you that new MySQL Router K8s is published in `8.0/stable` [charmhub](https://charmhub.io/mysql-router-k8s?channel=8.0/stable) channel for Kubernetes. - -## The features you can start using today: - -* Updated [MySQL Router to 8.0.35](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-35.html) in [#191](https://github.com/canonical/mysql-router-k8s-operator/pull/191) -* Juju 3.1.7+ support in [#2037120](https://bugs.launchpad.net/juju/+bug/2037120) -* Enable poetry hashes & charmcraft strict dependencies in [#179](https://github.com/canonical/mysql-router-k8s-operator/pull/179) -* Add [Allure Report beta](https://canonical.github.io/mysql-router-k8s-operator) in [#198](https://github.com/canonical/mysql-router-k8s-operator/pull/198) - - -## Bugfixes included: - -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/Git commits for each revision. - -* Bootstrap mysql-router with force option in [#187](https://github.com/canonical/mysql-router-k8s-operator/pull/187) -* Fix upgrade compatibility check in [#202](https://github.com/canonical/mysql-router-k8s-operator/pull/202) -* Retry if MySQL Server is unreachable in [#190](https://github.com/canonical/mysql-router-k8s-operator/pull/190) - -## What is inside the charms: - -* 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) -* Principal charms supports the latest LTS series “22.04” only - -## Technical notes: - -* Upgrade (`juju refresh`) is possible from this revision 69+ -* Use this operator together with a modern operator "[Charmed MySQL K8s](https://charmhub.io/mysql-k8s)" - -## How to reach us: - -If you would like to chat with us about your use-cases or ideas, [choose your way from the list](/t/12177). - -Consider [opening a GitHub issue](https://github.com/canonical/mysql-router-k8s-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md) to the project! \ 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/reference/r-requirements.md b/docs/reference/r-requirements.md deleted file mode 100644 index cf3b793b9..000000000 --- a/docs/reference/r-requirements.md +++ /dev/null @@ -1,30 +0,0 @@ -## Juju version - -The charm supports both [Juju 2.9 LTS](https://github.com/juju/juju/releases) and [Juju 3.1](https://github.com/juju/juju/releases). - -The minimum supported Juju versions are: - -* 2.9.32+ -* 3.1.7+ (Juju secrets refactored/stabilized in Juju 3.1.7) - -## Kubernetes requirements - -* Kubernetes 1.27+ -* Canonical MicroK8s 1.27+ (snap channel 1.27-strict/stable and newer) - -## Minimum requirements - -Make sure your machine meets the following requirements: -- Ubuntu 22.04 (Jammy) or later. -- 8GB of RAM. -- 2 CPU threads. -- At least 20GB of available storage. -- Access to the internet for downloading the required OCI/ROCKs and charms. - -## Supported architectures - -The charm is based on [ROCK OCI](https://github.com/canonical/charmed-mysql-rock) named "[charmed-mysql](https://github.com/canonical/charmed-mysql-rock/pkgs/container/charmed-mysql)", which is recursively based on SNAP "[charmed-mysql](https://snapcraft.io/charmed-mysql)", which is currently available for `amd64` only! The architecture `arm64` support is planned. Please [contact us](/t/12177) if you are interested in new architecture! - - -## Charmed MySQL K8s requirements -* Please also keep in mind ["Charmed MySQL K8s" requirements](https://charmhub.io/mysql-k8s/docs/r-requirements#mysql-gr-limits). \ No newline at end of file diff --git a/docs/reference/r-testing.md b/docs/reference/r-testing.md deleted file mode 100644 index 853c2d31f..000000000 --- a/docs/reference/r-testing.md +++ /dev/null @@ -1,71 +0,0 @@ -# Charm Testing reference - -There are [a lot of test types](https://en.wikipedia.org/wiki/Software_testing) available and most of them are well applicable for MySQL Router K8s. Here is a list prepared by Canonical: - -* Smoke test -* Unit tests -* Integration tests -* System test -* Performance test - -**:information_source: Note:** below examples are written for Juju 3.x, but Juju 2.9 is [supported](/t/12179) as well.
Please adopt the `juju run ...` commands as `juju run-action ... --wait` for Juju 2.9. - -## Smoke test - -[u]Complexity[/u]: trivial
-[u]Speed[/u]: fast
-[u]Goal[/u]: ensure basic functionality works over short amount of time. - -[Setup an Juju 3.x environment](/t/12178), deploy DB with test application and start "continuous write" test: -```shell -juju add-model smoke-test - -juju deploy mysql-k8s --trust --channel 8.0/edge --config profile=testing -juju deploy mysql-router-k8s --trust --channel 8.0/edge -juju relate mysql-k8s mysql-router-k8s - -juju scale-application mysql-k8s 3 # (optional) -juju scale-application mysql-router-k8s 3 # (optional) - -juju deploy mysql-test-app --channel latest/edge -juju relate mysql-test-app mysql-router-k8s:database - -# Make sure random data inserted into DB by test application: -juju run mysql-test-app/leader get-inserted-data - -# Start "continuous write" test: -juju run mysql-test-app/leader start-continuous-writes -export password=$(juju run mysql-k8s/leader get-password username=root | yq '.. | select(. | has("password")).password') -watch -n1 -x juju ssh --container mysql mysql-k8s/leader "mysql -h 127.0.0.1 -uroot -p${password} -e \"select count(*) from continuous_writes_database.data\"" - -# Watch the counter is growing! -``` -[u]Expected results[/u]: - -* mysql-test-app continuously inserts records in database `continuous_writes_database` table `data`. -* the counters (amount of records in table) are growing on all cluster members - -[u]Hints[/u]: -```shell -# Stop "continuous write" test -juju run mysql-test-app/leader stop-continuous-writes - -# Truncate "continuous write" table (delete all records from DB) -juju run mysql-test-app/leader clear-continuous-writes -``` - -## Unit tests - -Please check the "[Contributing](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md#testing)" guide and follow `tox run -e unit` examples there. - -## Integration tests - -Please check the "[Contributing](https://github.com/canonical/mysql-router-k8s-operator/blob/main/CONTRIBUTING.md#testing)" guide and follow `tox run -e integration` examples there. - -## System test - -Please check/deploy the charm [mysql-k8s-bundle](https://charmhub.io/mysql-k8s-bundle) ([Git](https://github.com/canonical/mysql-k8s-bundle)). It deploy and test all the necessary parts at once. - -## Performance test - -Please use the separate [Charmed MySQL K8s performance testing document](https://charmhub.io/mysql-k8s/docs/r-testing) but deploy Charmed MySQL K8s behind MySQL Router K8s. \ No newline at end of file diff --git a/docs/tutorial/t-cleanup-environment.md b/docs/tutorial/t-cleanup-environment.md deleted file mode 100644 index b7f808a0d..000000000 --- a/docs/tutorial/t-cleanup-environment.md +++ /dev/null @@ -1,19 +0,0 @@ -# Cleanup and extra info - -This is part of the [MySQL Router K8s Tutorial](/t/12176). Please refer to this page for more information and the overview of the content. - -## Remove and cleanup environment -If you're done with testing and would like to free up resources on your machine, just remove Multipass VM. -*Warning: when you remove VM as shown below you will lose all the data in MySQL and any other applications inside Multipass VM!* -```shell -multipass delete --purge my-vm -``` - -## Next Steps -In this tutorial we've successfully deployed MySQL Router, added/removed cluster members, added/removed users to/from the database, and even enabled and disabled TLS. You may now keep your deployment running and write to the database or remove it entirely. If you're looking for what to do next you can: -- Run [Charmed MySQL VM on LXD](https://github.com/canonical/mysql-operator). -- Check out our Charmed offerings of [PostgreSQL K8s](https://charmhub.io/postgresql-k8s?channel=14) and [Kafka K8s](https://charmhub.io/kafka-k8s?channel=edge). -- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability) -- [Report](https://github.com/canonical/mysql-router-k8s-operator/issues) any problems you encountered. -- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform). -- [Contribute to the code base](https://github.com/canonical/mysql-router-k8s-operator) \ No newline at end of file diff --git a/docs/tutorial/t-deploy-charm.md b/docs/tutorial/t-deploy-charm.md deleted file mode 100644 index 2fbc99df1..000000000 --- a/docs/tutorial/t-deploy-charm.md +++ /dev/null @@ -1,148 +0,0 @@ -# Get a MySQL Router K8s up and running - -This is part of the [MySQL Router K8s Tutorial](/t/12176). Please refer to this page for more information and the overview of the content. The following document will deploy "MySQL Router" together with "MySQL server" (coming from the separate charm "[Charmed MySQL K8s](https://charmhub.io/mysql-k8s)"). - -## Deploy Charmed MySQL K8s + MySQL Router K8s -> :information_source: **Info**: [the minimum Juju version for "Charmed MySQL K8s" is 2.9.44](https://charmhub.io/mysql-k8s/docs/r-requirements) - -To deploy Charmed MySQL K8s + MySQL Router K8s, all you need to do is run the following commands: - -```shell -juju deploy mysql-router-k8s --channel 8.0 --trust -juju deploy mysql-k8s --channel 8.0 --trust -``` -Note: `--trust` is required to create some K8s resources. - -Juju will now fetch charms from [Charmhub](https://charmhub.io/) and begin deploying it to the Microk8s Kubernetes. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is. You can track the progress by running: -```shell -juju status --watch 1s -``` - -This command is useful for checking the status of Juju applications and gathering information about the machines hosting them. Some of the helpful information it displays include IP addresses, ports, state, etc. The command updates the status of charms every second and as the application starts you can watch the status and messages of their change. Wait until the application is ready - when it is ready, `juju status` will show: -```shell -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord microk8s/localhost 2.9.46 unsupported 22:33:45+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/edge 109 10.152.183.68 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 blocked 1 mysql-router-k8s 8.0/edge 68 10.152.183.52 no Missing relation: backend-database - -Unit Workload Agent Address Ports Message -mysql-k8s/0* active idle 10.1.12.36 Primary -mysql-router-k8s/0* active idle 10.1.12.14 -``` -> :tipping_hand_man: **Tip**: To exit the screen with `juju status --watch 1s`, enter `Ctrl+c`. -If you want to further inspect juju logs, can watch for logs with `juju debug-log`. -More info on logging at [juju logs](https://juju.is/docs/olm/juju-logs). - -At this stage MySQL Router will stay in blocked state due to missing relation/integration with MySQL DB, let's integrate them: -```shell -juju integrate mysql-k8s mysql-router-k8s -``` -Shortly the `juju status` will report new blocking reason `Missing relation: database` as it waits for a client to consume DB service, let's deploy [data-integrator](https://charmhub.io/data-integrator) and request access to database `test123`: -```shell -juju deploy data-integrator --config database-name=test123 -juju relate data-integrator mysql-router-k8s -``` -In couple of seconds, the status will be happy for entire model: -```shell -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord microk8s/localhost 2.9.46 unsupported 22:37:41+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -data-integrator active 1 data-integrator stable 13 10.152.183.142 no -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/edge 109 10.152.183.68 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 68 10.152.183.52 no - -Unit Workload Agent Address Ports Message -data-integrator/0* active idle 10.1.12.3 -mysql-k8s/0* active idle 10.1.12.36 Primary -mysql-router-k8s/0* active idle 10.1.12.14 -``` - -## Access database - -The first action most users take after installing MySQL is accessing MySQL. The easiest way to do this is via the [MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) `mysql`. Connecting to the database requires that you know the values for `host`, `username` and `password`. To retrieve the necessary fields please run data-integrator action `get-credentials`: -```shell -juju run data-integrator/leader get-credentials -``` -Running the command should output: -```yaml -mysql: - database: test123 - endpoints: mysql-router-k8s.tutorial.svc.cluster.local:6446 - password: Nu7wK85QU7dpVX66X56lozji - read-only-endpoints: mysql-router-k8s.tutorial.svc.cluster.local:6447 - username: relation-4-6 -``` - -The host’s IP address can be found with `juju status` (the application hosting the Router MySQL K8s application): -```shell -... -App Version Status Scale Charm Channel Rev Address Exposed Message -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-router-k8s 8.0/edge 68 10.152.183.52 no -... -``` - -To access the MySQL database via MySQL Router choose read-write (port 6446) or read-only (port 6447) endpoints: -```shell -mysql -h 10.152.183.52 -P6446 -urelation-4-6 -pNu7wK85QU7dpVX66X56lozji test123 -``` - -Inside MySQL list DBs available on the host `show databases`: -```shell -mysql> show databases; -+--------------------+ -| Database | -+--------------------+ -| information_schema | -| performance_schema | -| test123 | -+--------------------+ -3 rows in set (0.00 sec) - -``` -> :tipping_hand_man: **Tip**: if at any point you'd like to leave the MySQL client, enter `Ctrl+d` or type `exit`. - -You can now interact with MySQL directly using any [MySQL Queries](https://dev.mysql.com/doc/refman/8.0/en/entering-queries.html). For example entering `SELECT VERSION(), CURRENT_DATE;` should output something like: -```shell -mysql> SELECT VERSION(), CURRENT_DATE; -+-------------------------+--------------+ -| VERSION() | CURRENT_DATE | -+-------------------------+--------------+ -| 8.0.34-0ubuntu0.22.04.1 | 2023-10-17 | -+-------------------------+--------------+ -1 row in set (0.00 sec) -``` - -Feel free to test out any other MySQL queries. When you’re ready to leave the MySQL shell you can just type `exit`. Now you will be in your original shell where you first started the tutorial; here you can interact with Juju and Microk8s. - -### Remove the user - -To remove the user, remove the relation. Removing the relation automatically removes the user that was created when the relation was created. Enter the following to remove the relation: -```shell -juju remove-relation mysql-router-k8s data-integrator -``` - -Now try again to connect to the same MySQL Router K8s you just used above: -```shell -mysql -h 10.152.183.52 -P6446 -urelation-4-6 -pNu7wK85QU7dpVX66X56lozji test123 -``` - -This will output an error message: -```shell -ERROR 1045 (28000): Access denied for user 'relation-4-6'@'mysql-router-k8s-1.mysql-router-k8s-endpoints.tutorial.svc.clust' (using password: YES) -``` -As this user no longer exists. This is expected as `juju remove-relation mysql-router-k8s data-integrator` also removes the user. -Note: data stay remain on the server at this stage! - -Relate the the two applications again if you wanted to recreate the user: -```shell -juju relate data-integrator mysql-router-k8s -``` -Re-relating generates a new user and password: -```shell -juju run data-integrator/leader get-credentials -``` -You can connect to the database with this new credentials. -From here you will see all of your data is still present in the database. \ 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 diff --git a/docs/tutorial/t-managing-units.md b/docs/tutorial/t-managing-units.md deleted file mode 100644 index e78f173e4..000000000 --- a/docs/tutorial/t-managing-units.md +++ /dev/null @@ -1,77 +0,0 @@ -# Scale your MySQL Router K8s - -This is part of the [Charmed MySQL Tutorial](/t/12176). Please refer to this page for more information and the overview of the content. - -## Adding and Removing units - -Please check the explanation of scaling Charmed MySQL K8s operator [here](https://charmhub.io/mysql-k8s/docs/t-managing-units). - -### Add more mysql-router instances -You can add two more units to your deployed MySQL Router application by scaling it to three units using: -```shell -juju scale-application mysql-router-k8s 3 -``` - -You can now watch the scaling process in live using: `juju status --watch 1s`. It usually takes several minutes for new cluster members to be added. You’ll know that all three nodes are in sync when `juju status` reports `Workload=active` and `Agent=idle`: -```shell -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord microk8s/localhost 2.9.46 unsupported 22:48:57+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -data-integrator active 1 data-integrator stable 13 10.152.183.142 no -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 1 mysql-k8s 8.0/edge 109 10.152.183.68 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-router-k8s 8.0/edge 68 10.152.183.52 no - -Unit Workload Agent Address Ports Message -data-integrator/0* active idle 10.1.12.3 -mysql-k8s/0* active idle 10.1.12.36 Primary -mysql-router-k8s/0* active idle 10.1.12.14 -mysql-router-k8s/1 active idle 10.1.12.32 -mysql-router-k8s/2 active idle 10.1.12.31 -``` - -The same way you can scale Charmed MySQL: -```shell -juju scale-application mysql-k8s 3 -``` -Make sure all units are active (using `juju status`): -```shell -App Version Status Scale Charm Channel Rev Address Exposed Message -data-integrator active 1 data-integrator stable 13 10.152.183.142 no -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-k8s 8.0/edge 109 10.152.183.68 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 3 mysql-router-k8s 8.0/edge 68 10.152.183.52 no - -Unit Workload Agent Address Ports Message -data-integrator/0* active idle 10.1.12.3 -mysql-k8s/0* active idle 10.1.12.36 Primary -mysql-k8s/1 active idle 10.1.12.34 -mysql-k8s/2 active idle 10.1.12.43 -mysql-router-k8s/0* active idle 10.1.12.14 -mysql-router-k8s/1 active idle 10.1.12.32 -mysql-router-k8s/2 active idle 10.1.12.31 -``` - -### Remove extra members -Removing a unit from the application, scales the replicas down. -```shell -juju scale-application mysql-router-k8s 2 -juju scale-application mysql-k8s 2 -``` - -You’ll know that the replica was successfully removed when `juju status --watch 1s` reports: -```shell -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord microk8s/localhost 2.9.46 unsupported 22:48:57+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -data-integrator active 1 data-integrator stable 13 10.152.183.142 no -mysql-k8s 8.0.34-0ubuntu0.22.04.1 active 2 mysql-k8s 8.0/edge 109 10.152.183.68 no -mysql-router-k8s 8.0.34-0ubuntu0.22.04.1 active 2 mysql-router-k8s 8.0/edge 68 10.152.183.52 no - -Unit Workload Agent Address Ports Message -data-integrator/0* active idle 10.1.12.3 -mysql-k8s/0* active idle 10.1.12.36 Primary -mysql-k8s/1 active idle 10.1.12.34 -mysql-router-k8s/0* active idle 10.1.12.14 -mysql-router-k8s/1 active idle 10.1.12.32 -``` \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md deleted file mode 100644 index d5239cb39..000000000 --- a/docs/tutorial/t-overview.md +++ /dev/null @@ -1,20 +0,0 @@ -# MySQL Router K8s tutorial - -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/). As a first step this tutorial shows you how to get MySQL Router K8s up and running, but the tutorial does not stop there. Through this tutorial you will learn a variety of operations, everything from adding replicas to advanced operations such as enabling Transport Layer Security (TLS). In this tutorial we will walk through how to: -- Set up an environment using [Multipass](https://multipass.run/) with [Microk8s](https://microk8s.io/) and [Juju](https://juju.is/). -- Deploy MySQL Router K8s using a single command. -- Configure TLS certificate in one command. - -While this tutorial intends to guide and teach you as you deploy MySQL Router K8s, it will be most beneficial if you already have a familiarity with: -- Basic terminal commands. -- MySQL and MySQL Router concepts. -- [Charmed MySQL K8s operator](https://charmhub.io/mysql-k8s) - -## Step-by-step guide - -Here’s an overview of the steps required with links to our separate tutorials that deal with each individual step: -* [Set up the environment](/t/12178) -* [Deploy MySQL Router](/t/12180) -* [Managing your units](/t/12182) -* [Enable security](/t/12203) -* [Cleanup your environment](/t/12204) \ No newline at end of file diff --git a/docs/tutorial/t-setup-environment.md b/docs/tutorial/t-setup-environment.md deleted file mode 100644 index 9061b3fd9..000000000 --- a/docs/tutorial/t-setup-environment.md +++ /dev/null @@ -1,39 +0,0 @@ -# Environment Setup - -This is part of the [MySQL Router K8s Tutorial](/t/12176). Please refer to this page for more information and the overview of the content. - -## Minimum requirements -Before we start, make sure your machine meets [the following requirements](/t/12179). - -## Multipass environment -[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses "[cloud-init](https://cloud-init.io/)" standard to install and configure all the necessary parts automatically. - -Let's install Multipass from [Snap](https://snapcraft.io/multipass) and launch a new VM using "[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)" cloud-init config: -```shell -sudo snap install multipass && \ -multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev -``` -*Note: all 'multipass launch' params are [described here](https://multipass.run/docs/launch-command)*. - -Multipass [list of commands](https://multipass.run/docs/multipass-cli-commands) is short and self-explanatory, e.g. show all running VMs: -```shell -multipass list -``` - -As soon as new VM started, enter inside using: -```shell -multipass shell my-vm -``` -*Note: if at any point you'd like to leave Multipass VM, enter `Ctrl+d` or type `exit`*. - -All the parts have been pre-installed inside VM already, like MicroK8s and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). The Juju controller can work with different models; models host applications such as Charmed MySQL + MySQL Router K8s. Set up a specific model named ‘tutorial’: -```shell -juju add-model tutorial -``` - -You can now view the model you created above by entering the command `juju status` into the command line. You should see the following: -```shell -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord microk8s/localhost 2.9.38 unsupported 22:30:11+01:00 -Model "admin/tutorial" is empty. -``` \ No newline at end of file