canonical · github-actions · Feb 14, 2024 · Feb 24, 2024 · Mar 14, 2024 · May 2, 2024
diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md
@@ -0,0 +1,33 @@
+# Interfaces/endpoints
+
+MySQL Router 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 and MySQL Router clusters
+juju deploy mysql -n 3
+juju deploy mysql-router -n 3 --channel dpe/edge
+
+# Deploy the relevant charms, e.g. mysql-test-app
+juju deploy mysql-test-app
+
+# Relate all applications
+juju integrate mysql mysql-router
+juju integrate mysql-router: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:database              mysql-router:backend-database    mysql_client        regular
+# > mysql-router:database       mysql-test-app:database          mysql_client        regular         
+# > ...
+```
+
+**Note:** In order to relate with Charmed MySQL, 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/integrations).
diff --git a/docs/explanation/e-juju-details.md b/docs/explanation/e-juju-details.md
@@ -0,0 +1,43 @@
+# 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) 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:database mysql-test-app
+
+juju run mysql/leader get-password 
+```
+### Juju 2.9.x:
+```shell
+juju relate mysql-router:database mysql-test-app
+
+juju run-action --wait mysql/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)
diff --git a/docs/explanation/e-statuses.md b/docs/explanation/e-statuses.md
@@ -0,0 +1,20 @@
+# 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. Execute `juju resolve <error_unit/0>` 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: the charm termination in progress. | Manual investigation required if status is permanent |
diff --git a/docs/how-to/h-contribute.md b/docs/how-to/h-contribute.md
@@ -0,0 +1,33 @@
+[note type="caution"]
+:construction: This page is under construction! More details for each section coming soon.
+[/note]
+
+# How to contribute
+
+Charmed MySQL Router is an open-source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.
+
+This page explains the processes and practices recommended for contributing to this charm's code and documentation.
+
+## Submit a bug or issue 
+* Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-router-operator/issues)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+
+## Contribute to the code
+
+Before developing new features or fixes to this charm, you consider [opening an issue on GitHub](https://github.com/canonical/mysql-router-operator/issues) explaining your use case.
+
+If you would like to chat with us about your use-cases or proposed implementation, you can reach us at our [Data Platform Matrix channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com).
+
+### Tips for a good contribution
+
+* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
+* All contributions require review before being merged. Code review typically examines
+  * Code quality
+  * Test coverage
+  * User experience for Juju operators of this charm
+
+## Contribute to the documentation
+
+There are several ways to contribute to the documentation:
+* Writing a comment on Discourse
+* Submitting an [issue](https://github.com/canonical/mysql-router-operator/issues) on GitHub with the `documentation` label
diff --git a/docs/how-to/h-enable-monitoring.md b/docs/how-to/h-enable-monitoring.md
@@ -0,0 +1,108 @@
+# 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 MySQL and Charmed MySQLRouter 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 integrated (related) with Charmed MySQLRouter VM model:
+
+```shell
+# Switch to the Kubernetes controller, in particular the COS model
+juju switch <k8s_controller>:<cos_model_name>
+
+juju offer grafana:grafana-dashboard
+juju offer loki:logging
+juju offer prometheus:receive-remote-write
+```
+
+ Switch to the Charmed MySQLRouter VM model, find offers and integrate (relate) with them:
+
+```shell
+# We are on the Kubernetes controller, for the COS model. Switch to the MySQLRouter model
+juju switch <machine_controller_name>:<mysql_router_model_name>
+
+juju find-offers <k8s_controller>:  # Do not miss ':' 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 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](https://charmhub.io/grafana-agent)’ (subordinate charm) alongside the Charmed MySQL Router application (also subordinate) and integrate (relate) it with Charmed MySQLRouter, then later integrate (relate) `grafana-agent `with the consumed COS offers:
+
+```shell
+# Assume <client_application> is the principal application for the subordinate mysql router application
+juju deploy grafana-agent
+juju integrate <client_application> grafana-agent
+juju integrate grafana-agent mysql-router:cos-agent
+juju integrate grafana-agent grafana
+juju integrate grafana-agent loki
+juju integrate grafana-agent prometheus
+```
+
+After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allows access for Charmed MySQLRouter logs on Loki.
+
+An example of `juju status` on the Charmed MySQLRouter VM model:
+
+```shell
+ubuntu@localhost:~$ juju status
+Model 	Controller  Cloud/Region     	Version  SLA      	Timestamp
+database  lxd     	localhost/localhost  3.1.8	unsupported  12:34:26Z
+
+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  Exposed  Message
+grafana-agent                	active  	1  grafana-agent   stable   	65  no  	 
+mysql       	8.0.34-0ubun...  active  	1  mysql       	8.0/stable  196  no  	 
+mysql-router	8.0.36-0ubun...  active  	1  mysql-router	dpe/edge	153  no  	 
+mysql-test-app  0.0.2        	active  	1  mysql-test-app  stable   	36  no  	 
+
+Unit            	Workload  Agent  Machine  Public address  Ports       	Message
+mysql-test-app/0*   active	idle   1    	10.205.193.82              	 
+  grafana-agent/0*  active	idle        	10.205.193.82              	 
+  mysql-router/0*   active	idle        	10.205.193.82              	 
+mysql/0*        	active	idle   0    	10.205.193.13   3306,33060/tcp  Primary
+
+Machine  State	Address    	Inst id    	Base      	AZ  Message
+0    	started  10.205.193.13  juju-65afbd-0  [email protected]  	Running
+1    	started  10.205.193.82  juju-65afbd-1  [email protected]  	Running
+```
+
+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  20:29:12Z
+
+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  	 
+```
+
+To connect to the 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 <k8s_controller>:<cos_model_name>
+```
diff --git a/docs/how-to/h-monitoring/h-enable-monitoring.md b/docs/how-to/h-monitoring/h-enable-monitoring.md
@@ -0,0 +1,108 @@
+# 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 MySQL and Charmed MySQLRouter 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 integrated (related) with Charmed MySQLRouter VM model:
+
+```shell
+# Switch to the Kubernetes controller, in particular the COS model
+juju switch <k8s_controller>:<cos_model_name>
+
+juju offer grafana:grafana-dashboard
+juju offer loki:logging
+juju offer prometheus:receive-remote-write
+```
+
+ Switch to the Charmed MySQLRouter VM model, find offers and integrate (relate) with them:
+
+```shell
+# We are on the Kubernetes controller, for the COS model. Switch to the MySQLRouter model
+juju switch <machine_controller_name>:<mysql_router_model_name>
+
+juju find-offers <k8s_controller>:  # Do not miss ':' 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 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](https://charmhub.io/grafana-agent)’ (subordinate charm) alongside the Charmed MySQL Router application (also subordinate) and integrate (relate) it with Charmed MySQLRouter, then later integrate (relate) `grafana-agent `with the consumed COS offers:
+
+```shell
+# Assume <client_application> is the principal application for the subordinate mysql router application
+juju deploy grafana-agent
+juju integrate <client_application> grafana-agent
+juju integrate grafana-agent mysql-router:cos-agent
+juju integrate grafana-agent grafana
+juju integrate grafana-agent loki
+juju integrate grafana-agent prometheus
+```
+
+After this is complete, Grafana will show the new dashboards `MySQLRouter Exporter` and allows access for Charmed MySQLRouter logs on Loki.
+
+An example of `juju status` on the Charmed MySQLRouter VM model:
+
+```shell
+ubuntu@localhost:~$ juju status
+Model 	Controller  Cloud/Region     	Version  SLA      	Timestamp
+database  lxd     	localhost/localhost  3.1.8	unsupported  12:34:26Z
+
+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  Exposed  Message
+grafana-agent                	active  	1  grafana-agent   stable   	65  no  	 
+mysql       	8.0.34-0ubun...  active  	1  mysql       	8.0/stable  196  no  	 
+mysql-router	8.0.36-0ubun...  active  	1  mysql-router	dpe/edge	153  no  	 
+mysql-test-app  0.0.2        	active  	1  mysql-test-app  stable   	36  no  	 
+
+Unit            	Workload  Agent  Machine  Public address  Ports       	Message
+mysql-test-app/0*   active	idle   1    	10.205.193.82              	 
+  grafana-agent/0*  active	idle        	10.205.193.82              	 
+  mysql-router/0*   active	idle        	10.205.193.82              	 
+mysql/0*        	active	idle   0    	10.205.193.13   3306,33060/tcp  Primary
+
+Machine  State	Address    	Inst id    	Base      	AZ  Message
+0    	started  10.205.193.13  juju-65afbd-0  [email protected]  	Running
+1    	started  10.205.193.82  juju-65afbd-1  [email protected]  	Running
+```
+
+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  20:29:12Z
+
+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  	 
+```
+
+To connect to the 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 <k8s_controller>:<cos_model_name>
+```