generated from canonical/template-operator
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[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 <discourse-gatekeeper-bot@users.noreply.github.com>
- Loading branch information
1 parent
efad9e5
commit e722541
Showing
29 changed files
with
1,397 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` |
Oops, something went wrong.