[discourse-gatekeeper] Migrate charm docs (#270)

This pull request was autogenerated by discourse-gatekeeper to migrate existing documentation from server to the git repository. Co-authored-by: discourse-gatekeeper-docs-bot <[email protected]>
canonical · Jun 24, 2024 · e722541 · e722541
1 parent efad9e5
commit e722541
Show file tree

Hide file tree

Showing 29 changed files with 1,397 additions and 0 deletions.
diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md
@@ -0,0 +1,33 @@
+# 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).
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-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)
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 and check the debug log to see the exception. 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: K8s 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,43 @@
+[note type="caution"]
+:construction: This page is under construction! More details coming soon.
+[/note]
+
+# How to contribute
+
+MySQL Router K8s 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 (WIP)
+* Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-router-k8s-operator/issues)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+
+## Contribute to the code (WIP)
+
+Before developing new features or fixes to this charm, you consider [opening an issue on GitHub](https://github.com/canonical/mysql-router-k8s-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 (WIP)
+
+There are several ways to contribute to the documentation:
+* Writing a comment
+* Proposing an edit to an existing page
+* Adding a new page
+
+...
+
+### Tips for a good contribution
+...
diff --git a/docs/how-to/h-monitor/h-enable-monitoring.md b/docs/how-to/h-monitor/h-enable-monitoring.md
@@ -0,0 +1,121 @@
+# 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 <k8s_cos_controller>:<cos_model_name>
+
+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 <k8s_db_controller>:<mysql_router_model_name>
+
+juju find-offers <k8s_cos_controller>:  # 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 <k8s_controller>:<cos_model_name>
+```
diff --git a/docs/how-to/h-setup/h-deploy-microk8s.md b/docs/how-to/h-setup/h-deploy-microk8s.md
@@ -0,0 +1,35 @@
+# 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.
diff --git a/docs/how-to/h-setup/h-enable-encryption.md b/docs/how-to/h-setup/h-enable-encryption.md
@@ -0,0 +1,64 @@
+[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
+
+<!---[Update and add to explanation]
+MySQL Router will enable encrypted connections by default with self generated certificates. Though also by default, connecting clients can disable encryption by setting the connection ssl-mode as disabled.
+When related with the `tls-certificates-operator` the charmed operator for MySQL Router will require that every client connection (new and running connections) use encryption, rendering an error when attempting to establish an unencrypted connection.-->
+
+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
+```