From 1830d3cc0813cc60a98a2f86a429d165a7cdd166 Mon Sep 17 00:00:00 2001 From: shayancanonical <99665202+shayancanonical@users.noreply.github.com> Date: Thu, 21 Nov 2024 14:08:52 -0500 Subject: [PATCH 1/8] Update 3.6 nightly tests to run against 3.6/candidate instead of 3.6/beta (#187) ## Issue We are not running tests on juju 3.6/* ## Solution Run tests against juju 3.6/candidate on a nightly schedule --- .github/workflows/ci.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 6dedba14..fb89a8cd 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -116,17 +116,17 @@ jobs: bases-index: 0 - series: jammy bases-index: 1 - juju-snap-channel: ["2.9/stable", "3.4/stable", "3.6/beta"] + juju-snap-channel: ["2.9/stable", "3.4/stable", "3.6/candidate"] include: - - juju-snap-channel: "3.6/beta" - agent-version: "3.6-beta2" + - juju-snap-channel: "3.6/candidate" + agent-version: "3.6-rc2" libjuju-version: "3.5.2.0" - juju-snap-channel: "3.4/stable" agent-version: "3.4.3" libjuju-version: "3.5.2.0" - juju-snap-channel: "2.9/stable" - agent-version: "2.9.45" - libjuju-version: "2.9.44.1" + agent-version: "2.9.51" + libjuju-version: "2.9.49.0" exclude: - groups: {path_to_test_file: tests/integration/test_data_integrator.py} ubuntu-versions: {series: focal} @@ -154,7 +154,7 @@ jobs: bootstrap-options: "--agent-version ${{ matrix.agent-version }}" juju-channel: ${{ matrix.juju-snap-channel }} - name: Update python-libjuju version - if: ${{ matrix.libjuju-version == '2.9.44.1' }} + if: ${{ matrix.libjuju-version == '2.9.49.0' }} run: poetry add --lock --group integration juju@'${{ matrix.libjuju-version }}' - name: Download packed charm(s) uses: actions/download-artifact@v4 From 3512ac4f277f44959ebc1af6873a5cf1633d5aa1 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Wed, 27 Nov 2024 09:19:23 -0300 Subject: [PATCH 2/8] Update data-platform-workflows to v23 (#181) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [canonical/data-platform-workflows](https://redirect.github.com/canonical/data-platform-workflows) | action | major | `v22.0.0` -> `v23.1.0` | | [pytest-github-secrets](https://redirect.github.com/canonical/data-platform-workflows) | integration | major | `v22.0.0` -> `v23.1.0` | | [pytest-operator-cache](https://redirect.github.com/canonical/data-platform-workflows) | integration | major | `v22.0.0` -> `v23.1.0` | | [pytest-operator-groups](https://redirect.github.com/canonical/data-platform-workflows) | integration | major | `v22.0.0` -> `v23.1.0` | --- ### Release Notes
canonical/data-platform-workflows (canonical/data-platform-workflows) ### [`v23.1.0`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.1.0) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v23.0.5...v23.1.0) ##### What's Changed - compatible(integration_test_charm): Add input that would enable metallb for integration tests by [@​shayancanonical](https://redirect.github.com/shayancanonical) in [https://github.com/canonical/data-platform-workflows/pull/244](https://redirect.github.com/canonical/data-platform-workflows/pull/244) ##### New Contributors - [@​shayancanonical](https://redirect.github.com/shayancanonical) made their first contribution in [https://github.com/canonical/data-platform-workflows/pull/244](https://redirect.github.com/canonical/data-platform-workflows/pull/244) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v23.0.5...v23.1.0 ### [`v23.0.5`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.0.5) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v23.0.4...v23.0.5) #### What's Changed - patch(integration_test_charm.yaml): Remove tcpdump debug by [@​carlcsaposs-canonical](https://redirect.github.com/carlcsaposs-canonical) in [https://github.com/canonical/data-platform-workflows/pull/248](https://redirect.github.com/canonical/data-platform-workflows/pull/248) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v23.0.4...v23.0.5 ### [`v23.0.4`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.0.4) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v23.0.3...v23.0.4) #### What's Changed - patch(\_update_bundle.yaml): Alphabetically sort snap revision list by [@​lucasgameiroborges](https://redirect.github.com/lucasgameiroborges) in [https://github.com/canonical/data-platform-workflows/pull/243](https://redirect.github.com/canonical/data-platform-workflows/pull/243) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v23.0.3...v23.0.4 ### [`v23.0.3`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.0.3) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v23.0.2...v23.0.3) #### What's Changed - patch(integration_test_charm.yaml): Wait for microk8s to populate iptables before restarting on IS-hosted runners by [@​carlcsaposs-canonical](https://redirect.github.com/carlcsaposs-canonical) in [https://github.com/canonical/data-platform-workflows/pull/242](https://redirect.github.com/canonical/data-platform-workflows/pull/242) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v23.0.2...v23.0.3 ### [`v23.0.2`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.0.2) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v23.0.1...v23.0.2) #### What's Changed - patch(\_update_bundle.yaml): Hardcode snap channels for `charmed_postgresql` and `charmed_pgbouncer` by [@​lucasgameiroborges](https://redirect.github.com/lucasgameiroborges) in [https://github.com/canonical/data-platform-workflows/pull/241](https://redirect.github.com/canonical/data-platform-workflows/pull/241) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v23.0.1...v23.0.2 ### [`v23.0.1`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.0.1) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v23...v23.0.1) #### What's Changed - patch: Add \_update_bundle.yaml by [@​lucasgameiroborges](https://redirect.github.com/lucasgameiroborges) in [https://github.com/canonical/data-platform-workflows/pull/239](https://redirect.github.com/canonical/data-platform-workflows/pull/239) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v23.0.0...v23.0.1 ### [`v23.0.0`](https://redirect.github.com/canonical/data-platform-workflows/releases/tag/v23.0.0) [Compare Source](https://redirect.github.com/canonical/data-platform-workflows/compare/v22.0.0...v23.0.0) #### What's Changed - breaking: Remove update_bundle.yaml by [@​carlcsaposs-canonical](https://redirect.github.com/carlcsaposs-canonical) in [https://github.com/canonical/data-platform-workflows/pull/238](https://redirect.github.com/canonical/data-platform-workflows/pull/238) **Full Changelog**: https://github.com/canonical/data-platform-workflows/compare/v22...v23.0.0
--- ### Configuration ๐Ÿ“… **Schedule**: Branch creation - "after 1am and before 3am every weekday" in timezone Etc/UTC, Automerge - At any time (no schedule defined). ๐Ÿšฆ **Automerge**: Disabled by config. Please merge this manually once you are satisfied. โ™ป **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. ๐Ÿ”• **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR was generated by [Mend Renovate](https://mend.io/renovate/). View the [repository job log](https://developer.mend.io/github/canonical/mysql-router-operator). Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/workflows/ci.yaml | 2 +- .github/workflows/release.yaml | 4 ++-- .github/workflows/sync_docs.yaml | 2 +- poetry.lock | 15 ++++++++------- pyproject.toml | 6 +++--- 5 files changed, 15 insertions(+), 14 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index fb89a8cd..83098ade 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -66,7 +66,7 @@ jobs: build: name: Build charm - uses: canonical/data-platform-workflows/.github/workflows/build_charm.yaml@v22.0.0 + uses: canonical/data-platform-workflows/.github/workflows/build_charm.yaml@v23.1.0 with: # Use of cache blocked by https://github.com/canonical/charmcraft/issues/1456 # Details: https://github.com/canonical/charmcraftcache/issues/3 diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index c6f78636..9233dd6a 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -15,14 +15,14 @@ jobs: build: name: Build charm - uses: canonical/data-platform-workflows/.github/workflows/build_charm.yaml@v22.0.0 + uses: canonical/data-platform-workflows/.github/workflows/build_charm.yaml@v23.1.0 release: name: Release charm needs: - ci-tests - build - uses: canonical/data-platform-workflows/.github/workflows/release_charm.yaml@v22.0.0 + uses: canonical/data-platform-workflows/.github/workflows/release_charm.yaml@v23.1.0 with: channel: dpe/edge artifact-prefix: ${{ needs.build.outputs.artifact-prefix }} diff --git a/.github/workflows/sync_docs.yaml b/.github/workflows/sync_docs.yaml index 4e48da8e..a094605c 100644 --- a/.github/workflows/sync_docs.yaml +++ b/.github/workflows/sync_docs.yaml @@ -10,7 +10,7 @@ on: jobs: sync-docs: name: Sync docs from Discourse - uses: canonical/data-platform-workflows/.github/workflows/sync_docs.yaml@v22.0.0 + uses: canonical/data-platform-workflows/.github/workflows/sync_docs.yaml@v23.1.0 with: reviewers: a-velasco permissions: diff --git a/poetry.lock b/poetry.lock index 2d8d3809..69d3d1f7 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1528,8 +1528,8 @@ develop = false [package.source] type = "git" url = "https://github.com/canonical/data-platform-workflows" -reference = "v22.0.0" -resolved_reference = "da2da4b1e4469b5ed8f9187981fe2d747f8ee129" +reference = "v23.1.0" +resolved_reference = "b8b359d4bf3413332f9638a4510e84f8c4cdacdc" subdirectory = "python/pytest_plugins/github_secrets" [[package]] @@ -1583,8 +1583,8 @@ pyyaml = "*" [package.source] type = "git" url = "https://github.com/canonical/data-platform-workflows" -reference = "v22.0.0" -resolved_reference = "da2da4b1e4469b5ed8f9187981fe2d747f8ee129" +reference = "v23.1.0" +resolved_reference = "b8b359d4bf3413332f9638a4510e84f8c4cdacdc" subdirectory = "python/pytest_plugins/pytest_operator_cache" [[package]] @@ -1602,8 +1602,8 @@ pytest = "*" [package.source] type = "git" url = "https://github.com/canonical/data-platform-workflows" -reference = "v22.0.0" -resolved_reference = "da2da4b1e4469b5ed8f9187981fe2d747f8ee129" +reference = "v23.1.0" +resolved_reference = "b8b359d4bf3413332f9638a4510e84f8c4cdacdc" subdirectory = "python/pytest_plugins/pytest_operator_groups" [[package]] @@ -1676,6 +1676,7 @@ files = [ {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"}, {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"}, {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"}, + {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"}, {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"}, {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"}, {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"}, @@ -2242,4 +2243,4 @@ test = ["big-O", "importlib-resources", "jaraco.functools", "jaraco.itertools", [metadata] lock-version = "2.0" python-versions = "^3.8.1" -content-hash = "a8ba5b27ffced4a8452d0a2c16e06bd1140d9b52f7e45ab60e64a89ed7896e82" +content-hash = "0bf2f32f9b067a0472959726c7a0252957568a4108c621f83d49f765073123c5" diff --git a/pyproject.toml b/pyproject.toml index d8460909..3dd6071c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,9 +55,9 @@ pytest-mock = "^3.14.0" [tool.poetry.group.integration.dependencies] pytest = "^8.2.2" pytest-operator = "^0.35.0" -pytest-operator-cache = {git = "https://github.com/canonical/data-platform-workflows", tag = "v22.0.0", subdirectory = "python/pytest_plugins/pytest_operator_cache"} -pytest-operator-groups = {git = "https://github.com/canonical/data-platform-workflows", tag = "v22.0.0", subdirectory = "python/pytest_plugins/pytest_operator_groups"} -pytest-github-secrets = {git = "https://github.com/canonical/data-platform-workflows", tag = "v22.0.0", subdirectory = "python/pytest_plugins/github_secrets"} +pytest-operator-cache = {git = "https://github.com/canonical/data-platform-workflows", tag = "v23.1.0", subdirectory = "python/pytest_plugins/pytest_operator_cache"} +pytest-operator-groups = {git = "https://github.com/canonical/data-platform-workflows", tag = "v23.1.0", subdirectory = "python/pytest_plugins/pytest_operator_groups"} +pytest-github-secrets = {git = "https://github.com/canonical/data-platform-workflows", tag = "v23.1.0", subdirectory = "python/pytest_plugins/github_secrets"} juju = "^3.5.2.0" mysql-connector-python = "~8.0.33" tenacity = "^8.5.0" From cb64def7877618a23fa8221b915165b19dcf1072 Mon Sep 17 00:00:00 2001 From: shayancanonical <99665202+shayancanonical@users.noreply.github.com> Date: Wed, 27 Nov 2024 08:43:14 -0500 Subject: [PATCH 3/8] Run juju 3.6 nightly tests against 3.6/stable (#189) ## Issue Juju 3.6/stable was released ## Solution Run juju 3.6 nightly tests against 3.6/stable --- .github/workflows/ci.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 83098ade..9a27d4db 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -116,10 +116,10 @@ jobs: bases-index: 0 - series: jammy bases-index: 1 - juju-snap-channel: ["2.9/stable", "3.4/stable", "3.6/candidate"] + juju-snap-channel: ["2.9/stable", "3.4/stable", "3.6/stable"] include: - - juju-snap-channel: "3.6/candidate" - agent-version: "3.6-rc2" + - juju-snap-channel: "3.6/stable" + agent-version: "3.6.0" libjuju-version: "3.5.2.0" - juju-snap-channel: "3.4/stable" agent-version: "3.4.3" From 0f42207bd911a925dc969394bfd7bc479b33dd8f Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Wed, 27 Nov 2024 10:44:53 -0300 Subject: [PATCH 4/8] Update codecov/codecov-action action to v5 (#186) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [codecov/codecov-action](https://redirect.github.com/codecov/codecov-action) | action | major | `v4` -> `v5` | --- ### Release Notes
codecov/codecov-action (codecov/codecov-action) ### [`v5`](https://redirect.github.com/codecov/codecov-action/blob/HEAD/CHANGELOG.md#v507) [Compare Source](https://redirect.github.com/codecov/codecov-action/compare/v4...v5) ##### What's Changed - fix: use HEAD_REPO by [@​thomasrockhu-codecov](https://redirect.github.com/thomasrockhu-codecov) in [https://github.com/codecov/codecov-action/pull/1690](https://redirect.github.com/codecov/codecov-action/pull/1690) **Full Changelog**: https://github.com/codecov/codecov-action/compare/v5.0.6..v5.0.7
--- ### Configuration ๐Ÿ“… **Schedule**: Branch creation - "after 1am and before 3am every weekday" in timezone Etc/UTC, Automerge - At any time (no schedule defined). ๐Ÿšฆ **Automerge**: Disabled by config. Please merge this manually once you are satisfied. โ™ป **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. ๐Ÿ”• **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR was generated by [Mend Renovate](https://mend.io/renovate/). View the [repository job log](https://developer.mend.io/github/canonical/mysql-router-operator). Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/workflows/ci.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 9a27d4db..bd1ca0d5 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -42,7 +42,7 @@ jobs: - name: Run tests run: tox run -e unit - name: Upload Coverage to Codecov - uses: codecov/codecov-action@v4 + uses: codecov/codecov-action@v5 lib-check: name: Check libraries From 950a9eac5af5a3cc315a16ac57d17a1878739e6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sinclert=20P=C3=A9rez?= Date: Thu, 28 Nov 2024 17:20:45 +0100 Subject: [PATCH 5/8] [DPE-5711] Add warnings to destructive actions (#188) --- src/machine_charm.py | 5 +++-- src/workload.py | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/machine_charm.py b/src/machine_charm.py index cdc2bdc6..45c727e0 100755 --- a/src/machine_charm.py +++ b/src/machine_charm.py @@ -197,14 +197,15 @@ def _on_force_upgrade_action(self, event: ops.ActionEvent) -> None: logger.debug(f"Force upgrade event failed: {message}") event.fail(message) return - logger.debug("Forcing upgrade") + + logger.warning("Forcing upgrade") event.log(f"Forcefully upgrading {self.unit.name}") self._upgrade.upgrade_unit( event=event, workload_=self.get_workload(event=None), tls=self._tls_certificate_saved ) self.reconcile() event.set_results({"result": f"Forcefully upgraded {self.unit.name}"}) - logger.debug("Forced upgrade") + logger.warning("Forced upgrade") if __name__ == "__main__": diff --git a/src/workload.py b/src/workload.py index 33131e7b..56fd7411 100644 --- a/src/workload.py +++ b/src/workload.py @@ -145,14 +145,14 @@ def _disable_tls(self) -> None: def _disable_router(self) -> None: """Disable router and clean up corresponding router files.""" - logger.debug("Disabling MySQL Router service") + logger.info("Disabling MySQL Router service") self._container.update_mysql_router_service(enabled=False) self._logrotate.disable() self._container.router_config_directory.rmtree() self._container.router_config_directory.mkdir() self._router_data_directory.rmtree() self._router_data_directory.mkdir() - logger.debug("Disabled MySQL Router service") + logger.info("Disabled MySQL Router service") def reconcile( self, From 56d94135f7e1b45031c91b0ea24e226dac02e080 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Thu, 28 Nov 2024 21:39:30 -0300 Subject: [PATCH 6/8] Update canonical/charming-actions action to v2.6.3 (#155) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [canonical/charming-actions](https://redirect.github.com/canonical/charming-actions) | action | patch | `2.6.0` -> `2.6.3` | --- ### Release Notes
canonical/charming-actions (canonical/charming-actions) ### [`v2.6.3`](https://redirect.github.com/canonical/charming-actions/releases/tag/2.6.3) [Compare Source](https://redirect.github.com/canonical/charming-actions/compare/2.6.2...2.6.3) ##### What's Changed - fix(upload-bundle): Implement the same functionality without using `juju-bundle` by [@​mvlassis](https://redirect.github.com/mvlassis) in [https://github.com/canonical/charming-actions/pull/151](https://redirect.github.com/canonical/charming-actions/pull/151) ##### New Contributors - [@​mvlassis](https://redirect.github.com/mvlassis) made their first contribution in [https://github.com/canonical/charming-actions/pull/151](https://redirect.github.com/canonical/charming-actions/pull/151) **Full Changelog**: https://github.com/canonical/charming-actions/compare/2.6.2...2.6.3 ### [`v2.6.2`](https://redirect.github.com/canonical/charming-actions/releases/tag/2.6.2) [Compare Source](https://redirect.github.com/canonical/charming-actions/compare/2.6.1...2.6.2) #### What's Changed - fix(upload-charm): Use resource revision from upload-resource command by [@​orfeas-k](https://redirect.github.com/orfeas-k) in [https://github.com/canonical/charming-actions/pull/147](https://redirect.github.com/canonical/charming-actions/pull/147) #### New Contributors - [@​orfeas-k](https://redirect.github.com/orfeas-k) made their first contribution in [https://github.com/canonical/charming-actions/pull/147](https://redirect.github.com/canonical/charming-actions/pull/147) **Full Changelog**: https://github.com/canonical/charming-actions/compare/2.6.1...2.6.2 ### [`v2.6.1`](https://redirect.github.com/canonical/charming-actions/releases/tag/2.6.1) [Compare Source](https://redirect.github.com/canonical/charming-actions/compare/2.6.0...2.6.1) #### What's Changed - Support charms using charmcraft extensions by [@​weiiwang01](https://redirect.github.com/weiiwang01) in [https://github.com/canonical/charming-actions/pull/142](https://redirect.github.com/canonical/charming-actions/pull/142) #### New Contributors - [@​weiiwang01](https://redirect.github.com/weiiwang01) made their first contribution in [https://github.com/canonical/charming-actions/pull/142](https://redirect.github.com/canonical/charming-actions/pull/142) **Full Changelog**: https://github.com/canonical/charming-actions/compare/2.6.0...2.6.1
--- ### Configuration ๐Ÿ“… **Schedule**: Branch creation - "after 1am and before 3am every weekday" in timezone Etc/UTC, Automerge - At any time (no schedule defined). ๐Ÿšฆ **Automerge**: Disabled by config. Please merge this manually once you are satisfied. โ™ป **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. ๐Ÿ”• **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR was generated by [Mend Renovate](https://mend.io/renovate/). View the [repository job log](https://developer.mend.io/github/canonical/mysql-router-operator). Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/workflows/ci.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index bd1ca0d5..e3fd72fd 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -57,7 +57,7 @@ jobs: # Workaround for https://github.com/canonical/charmcraft/issues/1389#issuecomment-1880921728 touch requirements.txt - name: Check libs - uses: canonical/charming-actions/check-libraries@2.6.0 + uses: canonical/charming-actions/check-libraries@2.6.3 with: credentials: "${{ secrets.CHARMHUB_TOKEN }}" # FIXME: current token will expire around 2023-09-23 github-token: "${{ secrets.GITHUB_TOKEN }}" From ed7d8e3082e345cf9c35134fb6599982f89dc602 Mon Sep 17 00:00:00 2001 From: shayancanonical <99665202+shayancanonical@users.noreply.github.com> Date: Mon, 2 Dec 2024 08:19:11 -0500 Subject: [PATCH 7/8] [DPE-4573] Update to MySQL v8.0.39 (#172) ## Issue We have new snap revisions for MySQL and related dependencies 8.0.39 ## Solution Update MySQL Co-authored-by: Paulo Machado --- src/snap.py | 4 ++-- workload_version | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/snap.py b/src/snap.py index 1f9bf7c7..922b689e 100644 --- a/src/snap.py +++ b/src/snap.py @@ -25,8 +25,8 @@ _SNAP_NAME = "charmed-mysql" REVISIONS: typing.Dict[str, str] = { # Keep in sync with `workload_version` file - "x86_64": "109", - "aarch64": "110", + "x86_64": "121", + "aarch64": "122", } revision = REVISIONS[platform.machine()] _snap = snap_lib.SnapCache()[_SNAP_NAME] diff --git a/workload_version b/workload_version index 3e1939c4..452b8f58 100644 --- a/workload_version +++ b/workload_version @@ -1 +1 @@ -8.0.37 +8.0.39 From d49eda8e9861a95a8579be34410baaa03bd7ba50 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 3 Dec 2024 16:50:28 +0100 Subject: [PATCH 8/8] [discourse-gatekeeper] Migrate charm docs (#109) This pull request was autogenerated by discourse-gatekeeper to migrate existing documentation from server to the git repository. --------- Co-authored-by: upload-charms-docs-bot Co-authored-by: discourse-gatekeeper-docs-bot --- docs/explanation/e-interfaces.md | 33 ++++ docs/explanation/e-juju-details.md | 43 +++++ docs/explanation/e-statuses.md | 20 +++ docs/how-to/h-contribute.md | 33 ++++ docs/how-to/h-enable-monitoring.md | 108 ++++++++++++ .../h-monitoring/h-enable-monitoring.md | 108 ++++++++++++ docs/how-to/h-monitoring/h-enable-tracing.md | 154 ++++++++++++++++++ docs/how-to/h-setup/h-deploy-lxd.md | 41 +++++ docs/how-to/h-setup/h-enable-encryption.md | 5 + docs/how-to/h-setup/h-manage-app.md | 35 ++++ docs/how-to/h-setup/h-manage-units.md | 17 ++ docs/how-to/h-upgrade/h-rollback-major.md | 5 + docs/how-to/h-upgrade/h-rollback-minor.md | 43 +++++ 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 | 22 +++ docs/index.md | 63 +++++++ docs/reference/r-contacts.md | 17 ++ .../r-releases-group/r-releases-rev119.md | 46 ++++++ .../r-releases-group/r-releases-rev186.md | 66 ++++++++ .../r-releases-group/r-releases-rev197.md | 68 ++++++++ .../r-releases-group/r-releases-revNEXT.md | 41 +++++ docs/reference/r-releases-group/r-releases.md | 17 ++ docs/reference/r-requirements.md | 23 +++ docs/reference/r-testing.md | 70 ++++++++ docs/tutorial/t-cleanup-environment.md | 19 +++ docs/tutorial/t-deploy-charm.md | 119 ++++++++++++++ docs/tutorial/t-enable-security.md | 95 +++++++++++ docs/tutorial/t-managing-units.md | 80 +++++++++ docs/tutorial/t-overview.md | 20 +++ docs/tutorial/t-setup-environment.md | 47 ++++++ 31 files changed, 1480 insertions(+) create mode 100644 docs/explanation/e-interfaces.md create mode 100644 docs/explanation/e-juju-details.md create mode 100644 docs/explanation/e-statuses.md create mode 100644 docs/how-to/h-contribute.md create mode 100644 docs/how-to/h-enable-monitoring.md create mode 100644 docs/how-to/h-monitoring/h-enable-monitoring.md create mode 100644 docs/how-to/h-monitoring/h-enable-tracing.md create mode 100644 docs/how-to/h-setup/h-deploy-lxd.md create mode 100644 docs/how-to/h-setup/h-enable-encryption.md create mode 100644 docs/how-to/h-setup/h-manage-app.md create mode 100644 docs/how-to/h-setup/h-manage-units.md create mode 100644 docs/how-to/h-upgrade/h-rollback-major.md create mode 100644 docs/how-to/h-upgrade/h-rollback-minor.md create mode 100644 docs/how-to/h-upgrade/h-upgrade-intro.md create mode 100644 docs/how-to/h-upgrade/h-upgrade-major.md create mode 100644 docs/how-to/h-upgrade/h-upgrade-minor.md create mode 100644 docs/index.md create mode 100644 docs/reference/r-contacts.md create mode 100644 docs/reference/r-releases-group/r-releases-rev119.md create mode 100644 docs/reference/r-releases-group/r-releases-rev186.md create mode 100644 docs/reference/r-releases-group/r-releases-rev197.md create mode 100644 docs/reference/r-releases-group/r-releases-revNEXT.md create mode 100644 docs/reference/r-releases-group/r-releases.md create mode 100644 docs/reference/r-requirements.md create mode 100644 docs/reference/r-testing.md create mode 100644 docs/tutorial/t-cleanup-environment.md create mode 100644 docs/tutorial/t-deploy-charm.md create mode 100644 docs/tutorial/t-enable-security.md create mode 100644 docs/tutorial/t-managing-units.md create mode 100644 docs/tutorial/t-overview.md create mode 100644 docs/tutorial/t-setup-environment.md diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md new file mode 100644 index 00000000..2cfcc7f4 --- /dev/null +++ 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). \ No newline at end of file diff --git a/docs/explanation/e-juju-details.md b/docs/explanation/e-juju-details.md new file mode 100644 index 00000000..3dd90ddb --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/explanation/e-statuses.md b/docs/explanation/e-statuses.md new file mode 100644 index 00000000..ae0b6bf4 --- /dev/null +++ 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 ` 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 | \ No newline at end of file diff --git a/docs/how-to/h-contribute.md b/docs/how-to/h-contribute.md new file mode 100644 index 00000000..b95ee9a0 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/how-to/h-enable-monitoring.md b/docs/how-to/h-enable-monitoring.md new file mode 100644 index 00000000..384dff0f --- /dev/null +++ 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 : + +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 : + +juju find-offers : # 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 is the principal application for the subordinate mysql router application +juju deploy grafana-agent +juju integrate 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 ubuntu@22.04 Running +1 started 10.205.193.82 juju-65afbd-1 ubuntu@22.04 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 : +``` \ No newline at end of file diff --git a/docs/how-to/h-monitoring/h-enable-monitoring.md b/docs/how-to/h-monitoring/h-enable-monitoring.md new file mode 100644 index 00000000..384dff0f --- /dev/null +++ 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 : + +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 : + +juju find-offers : # 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 is the principal application for the subordinate mysql router application +juju deploy grafana-agent +juju integrate 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 ubuntu@22.04 Running +1 started 10.205.193.82 juju-65afbd-1 ubuntu@22.04 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 : +``` \ No newline at end of file diff --git a/docs/how-to/h-monitoring/h-enable-tracing.md b/docs/how-to/h-monitoring/h-enable-tracing.md new file mode 100644 index 00000000..347ede62 --- /dev/null +++ b/docs/how-to/h-monitoring/h-enable-tracing.md @@ -0,0 +1,154 @@ +[note] +**Note**: All commands are written for `juju >= v3.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] + +# Enable tracing +This guide contains the steps to enable tracing with [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for your MySQL Router application. + +To summarize: +* [Deploy the Tempo charm in a COS K8s environment](#heading--deploy) +* [Integrate it with the COS charms](#heading--integrate) +* [Offer interfaces for cross-model integrations](#heading--offer) +* [View MySQLRouter traces on Grafana](#heading--view) + + +[note type="caution"] +**Warning:** This is feature is in development. It is **not recommended** for production environments. + +This feature is available for Charmed MySQL Router revision 208+ only. +[/note] + +## Prerequisites +Enabling tracing with Tempo requires that you: +- Have deployed a Charmed MySQL application + - See [How to manage MySQL units](https://discourse.charmhub.io/t/charmed-mysql-how-to-manage-units/9904) +- Have deployed a Charmed MySQL Router application in the same model as the Charmed MySQL application + - See [How to manage MySQL Router units](https://discourse.charmhub.io/t/mysql-router-how-to-manage-units/12338) +- Have deployed a 'cos-lite' bundle from the `latest/edge` track in a Kubernetes environment + - See [Getting started on MicroK8s](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) + +--- +

Deploy Tempo

+ + +First, switch to the Kubernetes controller where the COS model is deployed: + +```shell +juju switch : +``` +Then, deploy the [`tempo-k8s`](https://charmhub.io/tempo-k8s) charm: +```shell +juju deploy -n 1 tempo-k8s --channel latest/edge +``` + +

Integrate with the COS charms

+ +Integrate `tempo-k8s` with the COS charms as follows: + +```shell +juju integrate tempo-k8s:grafana-dashboard grafana:grafana-dashboard +juju integrate tempo-k8s:grafana-source grafana:grafana-source +juju integrate tempo-k8s:ingress traefik:traefik-route +juju integrate tempo-k8s:metrics-endpoint prometheus:metrics-endpoint +juju integrate tempo-k8s:logging loki:logging +``` +If you would like to instrument traces from the COS charms as well, create the following integrations: +```shell +juju integrate tempo-k8s:tracing alertmanager:tracing +juju integrate tempo-k8s:tracing catalogue:tracing +juju integrate tempo-k8s:tracing grafana:tracing +juju integrate tempo-k8s:tracing loki:tracing +juju integrate tempo-k8s:tracing prometheus:tracing +juju integrate tempo-k8s:tracing traefik:tracing +``` + +

Offer interfaces

+ +Next, offer interfaces for cross-model integrations from the model where Charmed MySQL Router is deployed. + +To offer the Tempo integration, run + +```shell +juju offer tempo-k8s:tracing +``` + +Then, switch to the Charmed MySQL Router model, find the offers, and integrate (relate) with them: + +```shell +juju switch : + +juju find-offers : +``` +> :exclamation: Do not miss the "`:`" in the command above. + +Below is a sample output where `k8s` is the K8s controller name and `cos` is the model where `cos-lite` and `tempo-k8s` are deployed: + +```shell +Store URL Access Interfaces +k8s admin/cos.tempo-k8s admin tracing:tracing +``` + +Next, consume this offer so that it is reachable from the current model: + +```shell +juju consume k8s:admin/cos.tempo-k8s +``` + +Relate Charmed MySQL Router with the above consumed interface: + +```shell +juju integrate mysql-router:tracing tempo-k8s:tracing +``` + +Wait until the model settles. The following is an example of the `juju status --relations` on the Charmed MySQL Router model: + +```shell +Model Controller Cloud/Region Version SLA Timestamp +database lxd localhost/localhost 3.4.3 unsupported 12:48:46Z + +SAAS Status Store URL +tempo-k8s active uk8s admin/cos.tempo-k8s + +App Version Status Scale Charm Channel Rev Exposed Message +mysql 8.0.37-0ubun... active 1 mysql 8.0/edge 253 no +mysql-router 8.0.37-0ubun... active 1 mysql-router dpe/edge 216 no +mysql-test-app 0.0.2 active 1 mysql-test-app latest/edge 46 no Last written value=54713 + +Unit Workload Agent Machine Public address Ports Message +mysql-test-app/0* active idle 1 10.205.193.43 Last written value=54713 + mysql-router/0* active idle 10.205.193.43 +mysql/0* active idle 0 10.205.193.72 3306,33060/tcp Primary + +Machine State Address Inst id Base AZ Message +0 started 10.205.193.72 juju-7f1fdf-0 ubuntu@22.04 Running +1 started 10.205.193.43 juju-7f1fdf-1 ubuntu@22.04 Running + +Integration provider Requirer Interface Type Message +mysql-router:cos mysql-router:cos cos peer +mysql-router:database mysql-test-app:database mysql_client subordinate +mysql-router:deprecated-shared-db-credentials mysql-router:deprecated-shared-db-credentials _deprecated_shared_db_peers peer +mysql-router:tls mysql-router:tls tls peer +mysql-router:upgrade-version-a mysql-router:upgrade-version-a upgrade peer +mysql-test-app:application-peers mysql-test-app:application-peers application-peers peer +mysql:database mysql-router:backend-database mysql_client regular +mysql:database-peers mysql:database-peers mysql_peers peer +mysql:restart mysql:restart rolling_op peer +mysql:upgrade mysql:upgrade upgrade peer +tempo-k8s:tracing mysql-router:tracing tracing regular +``` + +[note] +**Note:** All traces are exported to Tempo using HTTP. Support for sending traces via HTTPS is an upcoming feature. +[/note] + +

View traces

+ +After this is complete, the Tempo traces will be accessible from Grafana under the `Explore` section with `tempo-k8s` as the data source. You will be able to select `mysql-router` as the `Service Name` under the `Search` tab to view traces belonging to Charmed MySQL Router. + +Below is a screenshot demonstrating a Charmed MySQL Router trace: +![Example MySQL Router trace with Grafana Tempo|690x382](upload://iXdGsc3ACrhMal43QwNU5q5OCJ7.jpeg) + + +Feel free to read through the [Tempo documentation](https://discourse.charmhub.io/t/tempo-k8s-docs-index/14005) at your leisure to explore its deployment and its integrations. \ No newline at end of file diff --git a/docs/how-to/h-setup/h-deploy-lxd.md b/docs/how-to/h-setup/h-deploy-lxd.md new file mode 100644 index 00000000..daa864af --- /dev/null +++ b/docs/how-to/h-setup/h-deploy-lxd.md @@ -0,0 +1,41 @@ +# Deploy MySQL Router + +Please follow the [Tutorial](/t/12334) to deploy the charm on LXD. + +Short story for your Ubuntu 22.04 LTS: +```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 mysql +juju deploy mysql --channel 8.0/stable +juju deploy mysql-router --channel dpe/edge +juju deploy mysql-test-app +juju integrate mysql mysql-router +juju integrate mysql-router mysql-test-app:database + +juju status --watch 1s +``` + +The expected result: +```shell +Model Controller Cloud/Region Version SLA Timestamp +mysql lxd localhost/localhost 3.1.6 unsupported 11:57:33+02:00 + +App Version Status Scale Charm Channel Rev Exposed Message +mysql 8.0.34-0ubun... active 1 mysql 8.0/stable 196 no +mysql-router 8.0.34-0ubun... active 1 mysql-router dpe/edge 119 no +mysql-test-app 0.0.2 active 1 mysql-test-app stable 26 no + +Unit Workload Agent Machine Public address Ports Message +mysql-test-app/0* active idle 1 10.3.217.209 + mysql-router/0* active idle 10.3.217.209 +mysql/0* active idle 0 10.3.217.119 3306,33060/tcp Primary + +Machine State Address Inst id Base AZ Message +0 started 10.3.217.119 juju-d458a0-0 ubuntu@22.04 Running +1 started 10.3.217.209 juju-d458a0-1 ubuntu@22.04 Running +``` + +Check the [Testing](/t/12324) 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 new file mode 100644 index 00000000..c7545291 --- /dev/null +++ b/docs/how-to/h-setup/h-enable-encryption.md @@ -0,0 +1,5 @@ +# How to enable encryption + +MySQL Router is a subordinated charm, client applications connects it using local UNIX socket, therefor TLS encryption is not necessary between client application and MySQL Router. + +The TLS encryption is recommended between MySQL Router and MySQL server. To enable it follow the [dedicated manual](https://charmhub.io/mysql/docs/t-enable-security). \ 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 new file mode 100644 index 00000000..46db9ada --- /dev/null +++ b/docs/how-to/h-setup/h-manage-app.md @@ -0,0 +1,35 @@ +# 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 integrate mysql-router application +``` + +To remove a relation: + +```shell +juju remove-relation mysql-router application +``` + +All listed on CharmHub applications are available [here](https://charmhub.io/mysql-router/integrations), e.g. [mysql-test-app](https://charmhub.io/mysql-test-app). + +## Legacy `mysql-shared` interface: + +This charm also supports the legacy relation via the `mysql` interface. Please note that these interface is deprecated. + + ```shell +juju relate mysql-router:shared-db myapplication +``` + +## 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-router mysql + +juju integrate mysql-router mysql +``` \ 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 new file mode 100644 index 00000000..81145df2 --- /dev/null +++ b/docs/how-to/h-setup/h-manage-units.md @@ -0,0 +1,17 @@ +# 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 --channel dpe/edge +``` + +## Scaling + +MySQL Router is a subordinated charm, both scaling-up and scaling-down operations are performed via principal application using `juju add-unit`: +```shell +juju add-unit application -n +``` + +The subordinated application will be scaled automatically, following the principal application. \ 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 new file mode 100644 index 00000000..8a3c1893 --- /dev/null +++ b/docs/how-to/h-upgrade/h-rollback-major.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 00000000..a72d4860 --- /dev/null +++ b/docs/how-to/h-upgrade/h-rollback-minor.md @@ -0,0 +1,43 @@ +# 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 + +The rollback is NOT necessary if `sacrificial unit` is created before the upgrade, just remove it using scale-down the application. Otherwise perform the rollback: + +1. **Rollback**. Perform the charm rollback using `juju refresh`. The unit with the maximal ordinal will be rolled-back first and rollback continues for 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 charm from charmhub: + +``` +juju refresh mysql-router --revision=88 +``` + +Case deploying from local charm file, one need to have the previous revision charm file and the `mysql-image` resource, then run: + +``` +juju refresh mysql-router --path=./mysql-router_ubuntu-22.04-amd64.charm +``` + +Where `mysql-router_ubuntu-22.04-amd64.charm` is the previous revision charm file. + +The biggest ordinal unit will be rolled out and should rejoin the cluster after settling down. After the refresh command, the juju controller revision for the application will be back in sync with the running MySQL Router revision. + +## Step 2: Check + +The future [improvement is planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state on pod/cluster on a low level. At the moment check `juju status` to make sure the cluster [state](/t/12321) is OK. \ 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 new file mode 100644 index 00000000..144c5ce5 --- /dev/null +++ b/docs/how-to/h-upgrade/h-upgrade-intro.md @@ -0,0 +1,17 @@ +# MySQL Router Upgrade + +Please choose the appropriate upgrade/rollback tutorial. + +Migration: + +* [Major upgrade](/t/12343?channel=dpe/edge), e.g. MySQL Router 8.0 -> MySQL Router 9.0. + +* [Major rollback](/t/12344?channel=dpe/edge), e.g. MySQL Router 9.0 -> MySQL Router 8.0. + +In-place minor upgrade: + +* [Minor upgrade](/t/12345?channel=dpe/edge), e.g. MySQL Router 8.0.33 -> MySQL Router 8.0.34
+(including charm revision bump 99 -> 102). + +* [Minor rollback](/t/12346?channel=dpe/edge), 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 new file mode 100644 index 00000000..7ff9ab53 --- /dev/null +++ b/docs/how-to/h-upgrade/h-upgrade-major.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 00000000..3aab8fa2 --- /dev/null +++ b/docs/how-to/h-upgrade/h-upgrade-minor.md @@ -0,0 +1,22 @@ +# 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 cluster and/or MySQL Router, while upgrading. As an examples, these may be (but not limited to) the following: + +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 backups](/t/9896) of your data when running any type of upgrades. + +> **:warning: TIP:** The "MySQL Router" upgrade should follow first, before "Charmed MySQL" upgrade!!! + +## Minor upgrade steps + + +WIP... \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..06f2ce91 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,63 @@ +# MySQL Router Documentation + +The MySQL Router 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 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 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-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/mysql-router-operator/issues/new/choose) +- Explore [Canonical Data Fabric solutions](https://canonical.com/data) +- [Contacts us]() for all further questions + +## In this documentation + +| | | +|--|--| +| [Tutorials]()
Get started - a hands-on introduction to using Charmed MySQL operator for new users
| [How-to guides]()
Step-by-step guides covering key operations and common tasks | +| [Reference](https://charmhub.io/mysql-router/actions)
Technical information - specifications, APIs, architecture | [Explanation]()
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 LXD](how-to/h-setup/h-deploy-lxd.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. [Monitoring](how-to/h-monitoring) + 1. [Monitoring (COS)](how-to/h-monitoring/h-enable-monitoring.md) + 1. [Tracing (COS)](how-to/h-monitoring/h-enable-tracing.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. [Contribute](how-to/h-contribute.md) +1. [Reference](reference) + 1. [Release Notes](reference/r-releases-group) + 1. [All releases](reference/r-releases-group/r-releases.md) + 1. [Revision 197/198](reference/r-releases-group/r-releases-rev197.md) + 1. [Revision 118/119](reference/r-releases-group/r-releases-rev119.md) + 1. [Requirements](reference/r-requirements.md) + 1. [Testing](reference/r-testing.md) + 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 new file mode 100644 index 00000000..a7272b2a --- /dev/null +++ b/docs/reference/r-contacts.md @@ -0,0 +1,17 @@ +# Contact + +Charmed MySQL Router 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-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://canonical.com/data) +* [Charmed MySQL](https://charmhub.io/mysql) +* [MySQL Router](https://charmhub.io/mysql-router) +* [Git sources for MySQL Router](https://github.com/canonical/mysql-router-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-rev119.md b/docs/reference/r-releases-group/r-releases-rev119.md new file mode 100644 index 00000000..a3f28c30 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev119.md @@ -0,0 +1,46 @@ +>Reference > Release Notes > [All revisions](/t/12318) > Revision 118/119 +# Revision 118/119 (`dpe/beta` only) +October 6, 2023 + +Dear community, this is to inform you that new MySQL Router is published in `dpe/candidate` [charmhub](https://charmhub.io/mysql-router?channel=dpe/beta) channel for VMs: + +| |AMD64| +|---:|:---:| +| Revisions: | 119 (`jammy`) / 118 (`focal`) | + +## The features you can start using today: + +* [Add Juju 3 support](/t/12179) (Juju 2 is still supported) +* Charm [minor upgrades](/t/12345) and [minor rollbacks](/t/12346) +* 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/integrations?channel=dpe/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-operator/issues) platforms.
[GitHub Releases](https://github.com/canonical/mysql-router-operator/releases) provide a detailed list of bugfixes/PRs/Git commits for each revision. + +## What is inside the charms: + +* MySQL Router charm 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" +* VM charms based on [Charmed MySQL](https://snapcraft.io/charmed-mysql) SNAP (Ubuntu LTS โ€œ22.04โ€ - ubuntu:22.04-based) +* 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+. +* Use this operator together with a modern operator "[Charmed MySQL](https://charmhub.io/mysql)". + +## 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-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/mysql-router-operator/blob/main/CONTRIBUTING.md) to the project! + +## Footer: + +It is the first stable release of the operator "MySQL Router" by Canonical Data.
Well done, Team! \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev186.md b/docs/reference/r-releases-group/r-releases-rev186.md new file mode 100644 index 00000000..47db643c --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev186.md @@ -0,0 +1,66 @@ +>Reference > Release Notes > [All revisions](/t/12318) > Revision 185/186 +# Revision 185/186 (`dpe/candidate` only) + +TODO: DD, MM, YYYY + +Dear community, + +We'd like to announce that Canonical's newest Charmed MySQL Router operator has been published in the 'dpe/stable' [channel](/t/12318?channel=dpe/candidate) :tada: : + +| |AMD64| +|---:|:---:| +| Revisions: | 186 (`jammy`) / 185 (`focal`) | + +[note] +If you are jumping over several stable revisions, make sure to check [previous release notes](/t/12318?channel=dpe/candidate) 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#113](https://github.com/canonical/mysql-router-operator/pull/113)][[DPE-3717](https://warthogs.atlassian.net/browse/DPE-3717)] +* Exposure of all endpoints via data-integrator + TLS support [[PR#119](https://github.com/canonical/mysql-router-operator/pull/119)][[DPE-3689](https://warthogs.atlassian.net/browse/DPE-3689), [DPE-4179](https://warthogs.atlassian.net/browse/DPE-4179)] +* Support for subordination with `ubuntu-advantage` and `landscape-client` [[PR#115](https://github.com/canonical/mysql-router-operator/pull/115)] +* In-place upgrades [[PR#88](https://github.com/canonical/mysql-router-operator/pull/88)] + Router version in upgrade status [[#128](https://github.com/canonical/mysql-router-operator/pull/128)] +* [Observability with COS](/t/14094) [[#93](https://github.com/canonical/mysql-router-operator/pull/93)][[DPE-1794](https://warthogs.atlassian.net/browse/DPE-1794)] +* Log rotation via cron in [[PR#80](https://github.com/canonical/mysql-router-operator/pull/80)][[DPE-1789](https://warthogs.atlassian.net/browse/DPE-1789)] +* Discourse documentation [[PR#81](https://github.com/canonical/mysql-router-operator/pull/81)][[DPE-2752](https://warthogs.atlassian.net/browse/DPE-2752)] +* All the functionality from [previous revisions](/t/12318) + +## Bugfixes + +* Added integration test for upgrades in [PR#135](https://github.com/canonical/mysql-router-operator/pull/135), [[DPE-4179](https://warthogs.atlassian.net/browse/DPE-4179), [DPE-4219](https://warthogs.atlassian.net/browse/DPE-4219)] +* Updated `charmed-mysql-snap` to the latest edge revision in [PR#144](https://github.com/canonical/mysql-router-operator/pull/144) +* Check if highest unit has upgraded before resuming upgrade in [PR#140](https://github.com/canonical/mysql-router-operator/pull/140) +* No longer returning upgrade app status if upgrade not in progress in [PR#141](https://github.com/canonical/mysql-router-operator/pull/141) +* Removed redundant upgrade check in [PR#137](https://github.com/canonical/mysql-router-operator/pull/137) +* Fixed missing kwargs in some methods in [PR#143](https://github.com/canonical/mysql-router-operator/pull/143), [[DPE-4219](https://warthogs.atlassian.net/browse/DPE-4219)] +* Updated `force-upgrade` action description in [PR#133](https://github.com/canonical/mysql-router-operator/pull/133) +* Recovery from hook errors when creating/deleting MySQL users in [PR#112](https://github.com/canonical/mysql-router-operator/pull/112) +* Fixed retry if MySQL Server is unreachable in [PR#104](https://github.com/canonical/mysql-router-operator/pull/104) +* Bootstrap with force by default in [PR#100](https://github.com/canonical/mysql-router-operator/pull/100) +* Updated the logrotation dateformat to tolerate more than 24hrs of uptime in [PR#94](https://github.com/canonical/mysql-router-operator/pull/94), [[DPE-3063](https://warthogs.atlassian.net/browse/DPE-3063)] +* Made `install` handler idempotent in [PR#92](https://github.com/canonical/mysql-router-operator/pull/92) + +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-operator/issues) platforms. +[GitHub Releases](https://github.com/canonical/mysql-router-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision. + +## Inside the charms + +* MySQL Router charm ships the latest MySQL Router `8.0.36-0ubuntu0.22.04.1` +* CLI mysql-shell updated to `8.0.36+dfsg-0ubuntu0.22.04.1~ppa4` +* The Prometheus mysql-router-exporter is `5.0.1-0ubuntu0.22.04.1~ppa1` +* VM charms based on [Charmed MySQL SNAP](https://github.com/canonical/charmed-mysql-snap) (Ubuntu LTS `22.04.4`) revision `103`. +* Subordinate charms support LTS 22.04 and 20.04 only. + +## Technical notes + +* Upgrade (`juju refresh`) is possible from revision 118/119+ +* Use this operator together with modern operator [Charmed MySQL](https://charmhub.io/mysql) +* Please check restrictions from [previous release notes](https://charmhub.io/mysql-router/docs/r-releases?channel=dpe/edge) + +## Contact us + +Charmed MySQL Router 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-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-rev197.md b/docs/reference/r-releases-group/r-releases-rev197.md new file mode 100644 index 00000000..85a36381 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev197.md @@ -0,0 +1,68 @@ +>Reference > Release Notes > [All revisions](/t/12318) > Revision 197/198 +# Revision 197/198 (`dpe/candidate` only) + +TODO: DD, MM, YYYY + +Dear community, + +We'd like to announce that Canonical's newest Charmed MySQL Router operator has been published in the 'dpe/stable' [channel](/t/12318?channel=dpe/candidate) :tada: : + +| |AMD64| +|---:|:---:| +| Revisions: | 198 (`jammy`) / 197 (`focal`) | + +[note] +If you are jumping over several stable revisions, make sure to check [previous release notes](/t/12318?channel=dpe/candidate) 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#113](https://github.com/canonical/mysql-router-operator/pull/113)][[DPE-3717](https://warthogs.atlassian.net/browse/DPE-3717)] +* Exposure of all endpoints via data-integrator + TLS support [[PR#119](https://github.com/canonical/mysql-router-operator/pull/119)][[DPE-3689](https://warthogs.atlassian.net/browse/DPE-3689), [DPE-4179](https://warthogs.atlassian.net/browse/DPE-4179)] +* Support for subordination with `ubuntu-advantage` and `landscape-client` [[PR#115](https://github.com/canonical/mysql-router-operator/pull/115)] +* In-place upgrades [[PR#88](https://github.com/canonical/mysql-router-operator/pull/88)] + Router version in upgrade status [[#128](https://github.com/canonical/mysql-router-operator/pull/128)] +* [Observability with COS](/t/14094) [[#93](https://github.com/canonical/mysql-router-operator/pull/93)][[DPE-1794](https://warthogs.atlassian.net/browse/DPE-1794)] +* Log rotation via cron in [[PR#80](https://github.com/canonical/mysql-router-operator/pull/80)][[DPE-1789](https://warthogs.atlassian.net/browse/DPE-1789)] +* Discourse documentation [[PR#81](https://github.com/canonical/mysql-router-operator/pull/81)][[DPE-2752](https://warthogs.atlassian.net/browse/DPE-2752)] +* All the functionality from [previous revisions](/t/12318) + +## Bugfixes + +* Added integration test for upgrades in [PR#135](https://github.com/canonical/mysql-router-operator/pull/135), [[DPE-4179](https://warthogs.atlassian.net/browse/DPE-4179), [DPE-4219](https://warthogs.atlassian.net/browse/DPE-4219)] +* Updated `charmed-mysql-snap` to the latest edge revision in [PR#144](https://github.com/canonical/mysql-router-operator/pull/144) +* Check if highest unit has upgraded before resuming upgrade in [PR#140](https://github.com/canonical/mysql-router-operator/pull/140) +* No longer returning upgrade app status if upgrade not in progress in [PR#141](https://github.com/canonical/mysql-router-operator/pull/141) +* Removed redundant upgrade check in [PR#137](https://github.com/canonical/mysql-router-operator/pull/137) +* Fixed missing kwargs in some methods in [PR#143](https://github.com/canonical/mysql-router-operator/pull/143), [[DPE-4219](https://warthogs.atlassian.net/browse/DPE-4219)] +* Updated `force-upgrade` action description in [PR#133](https://github.com/canonical/mysql-router-operator/pull/133) +* Recovery from hook errors when creating/deleting MySQL users in [PR#112](https://github.com/canonical/mysql-router-operator/pull/112) +* Fixed retry if MySQL Server is unreachable in [PR#104](https://github.com/canonical/mysql-router-operator/pull/104) +* Bootstrap with force by default in [PR#100](https://github.com/canonical/mysql-router-operator/pull/100) +* Updated the logrotation dateformat to tolerate more than 24hrs of uptime in [PR#94](https://github.com/canonical/mysql-router-operator/pull/94), [[DPE-3063](https://warthogs.atlassian.net/browse/DPE-3063)] +* Made `install` handler idempotent in [PR#92](https://github.com/canonical/mysql-router-operator/pull/92) +* Stabilize exporter tests + leftover cleanup in [#146](https://github.com/canonical/mysql-router-operator/pull/146) +* Fix TLS configuration immediately deleted after enabling in [#150](https://github.com/canonical/mysql-router-operator/pull/150) + +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-operator/issues) platforms. +[GitHub Releases](https://github.com/canonical/mysql-router-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision. + +## Inside the charms + +* MySQL Router charm ships the latest MySQL Router `8.0.36-0ubuntu0.22.04.1` +* CLI mysql-shell updated to `8.0.36+dfsg-0ubuntu0.22.04.1~ppa4` +* The Prometheus mysql-router-exporter is `5.0.1-0ubuntu0.22.04.1~ppa1` +* VM charms based on [Charmed MySQL SNAP](https://github.com/canonical/charmed-mysql-snap) (Ubuntu LTS `22.04.4`) revision `103`. +* Subordinate charms support LTS 22.04 and 20.04 only. + +## Technical notes + +* Upgrade (`juju refresh`) is possible from revision 118/119+ +* Use this operator together with modern operator [Charmed MySQL](https://charmhub.io/mysql) +* Please check restrictions from [previous release notes](https://charmhub.io/mysql-router/docs/r-releases?channel=dpe/edge) + +## Contact us + +Charmed MySQL Router 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-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-revNEXT.md b/docs/reference/r-releases-group/r-releases-revNEXT.md new file mode 100644 index 00000000..dcbd5702 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-revNEXT.md @@ -0,0 +1,41 @@ +# MySQL Router revision NEXT +WIP + +Dear community, this is to inform you that new MySQL Router is published in `dpe/stable` [charmhub](https://charmhub.io/mysql-router?channel=dpe/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/integrations?channel=dpe/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-operator/issues) platforms.
[GitHub Releases](https://github.com/canonical/mysql-router-operator/releases) provide a detailed list of bugfixes/PRs/Git commits for each revision. + +## What is inside the charms: + +* MySQL Router charm 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" +* VM charms based on [Charmed MySQL](https://snapcraft.io/charmed-mysql) SNAP (Ubuntu LTS โ€œ22.04โ€ - ubuntu:22.04-based) +* 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+. +* Use this operator together with a modern operator "[Charmed MySQL](https://charmhub.io/mysql)". + +## 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-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/mysql-router-operator/blob/main/CONTRIBUTING.md) to the project! + +## Footer: + +It is the first stable release of the operator "MySQL Router" by Canonical Data.
Well done, Team! \ 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 new file mode 100644 index 00000000..4bdb0396 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases.md @@ -0,0 +1,17 @@ +# Release Notes + +Here you will find release notes for the main revisions of this charm that are available in Charmhub [channels](https://juju.is/docs/sdk/channel): + +* **`stable`**: production-ready releases +* **`candidate`, `beta`, `edge`** : [risk channels](https://juju.is/docs/sdk/channel#heading--risk) - new and experimental features. Not recommended for production. + +## Revisions: + +| Channel | amd64 | arm64 | +|:---------|:-----:|:-----:| +| `dpe/candidate` | [198 (`jammy`) / 197 (`focal`)](/t/14073?channel=dpe/candidate) | - | +| `dpe/beta` | [119 (`jammy`) / 118 (`focal`)](/t/12319?channel=dpe/candidate) | - | + +[note] +Due to the [subordinate nature](https://juju.is/docs/sdk/charm-taxonomy#heading--subordinate-charms) of this charm, several [revisions](https://juju.is/docs/sdk/revision) have been released simultaneously to the different [bases/series](https://juju.is/docs/juju/base) using the same charm code. +[/note] \ No newline at end of file diff --git a/docs/reference/r-requirements.md b/docs/reference/r-requirements.md new file mode 100644 index 00000000..62686eed --- /dev/null +++ b/docs/reference/r-requirements.md @@ -0,0 +1,23 @@ +## 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) + +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 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/12323) if you are interested in new architecture! + + +## Charmed MySQL requirements +* Please also keep in mind ["Charmed MySQL" requirements](https://charmhub.io/mysql/docs/r-requirements). \ No newline at end of file diff --git a/docs/reference/r-testing.md b/docs/reference/r-testing.md new file mode 100644 index 00000000..d31a1f5c --- /dev/null +++ b/docs/reference/r-testing.md @@ -0,0 +1,70 @@ +# 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. 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 --channel 8.0/edge --config profile=testing +juju deploy mysql-router --channel dpe/edge +juju relate mysql mysql-router + +juju add-unit mysql -n 2 # (optional) + +juju deploy mysql-test-app +juju relate mysql-test-app mysql-router: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/leader get-password username=root | yq '.. | select(. | has("password")).password') +watch -n1 -x juju ssh --container mysql mysql/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-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-operator/blob/main/CONTRIBUTING.md#testing)" guide and follow `tox run -e integration` examples there. + +## System test + +Please check/deploy the charm [mysql-bundle](https://charmhub.io/mysql-bundle) ([Git](https://github.com/canonical/mysql-bundle)). It deploy and test all the necessary parts at once. + +## Performance test + +Please use the separate [Charmed MySQL performance testing document](https://charmhub.io/mysql/docs/r-testing) but deploy Charmed MySQL behind MySQL Router. \ No newline at end of file diff --git a/docs/tutorial/t-cleanup-environment.md b/docs/tutorial/t-cleanup-environment.md new file mode 100644 index 00000000..9814455f --- /dev/null +++ b/docs/tutorial/t-cleanup-environment.md @@ -0,0 +1,19 @@ +# Cleanup and extra info + +This is part of the [MySQl Router Tutorial](/t/12332). 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 [MySQL Router K8s](https://github.com/canonical/mysql-router-k8s-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-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-operator) \ No newline at end of file diff --git a/docs/tutorial/t-deploy-charm.md b/docs/tutorial/t-deploy-charm.md new file mode 100644 index 00000000..5bc87860 --- /dev/null +++ b/docs/tutorial/t-deploy-charm.md @@ -0,0 +1,119 @@ +# Get a MySQL Router up and running + +This is part of the [MySQL Router Tutorial](/t/12332). 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](https://charmhub.io/mysql)"). + +## Deploy Charmed MySQL + MySQL Router + +To deploy Charmed MySQL + MySQL Router, all you need to do is run the following commands: + +```shell +juju deploy mysql --channel 8.0 +juju deploy mysql-router --channel dpe/edge +``` +Juju will now fetch charms from [Charmhub](https://charmhub.io/) and begin deploying it to the LXD VMs. 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 +TODO +``` +> :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 mysql-router +``` +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 +``` +In couple of seconds, the status will be happy for entire model: +```shell +TODO +``` + +## 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 +TODO +``` + +The hostโ€™s IP address can be found with `juju status` (the application hosting the MySQL Router application): +```shell +... +TODO +... +``` + +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 LXD. + +### 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 data-integrator +``` + +Now try again to connect to the same MySQL Router 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-1.mysql-router-endpoints.tutorial.svc.clust' (using password: YES) +``` +As this user no longer exists. This is expected as `juju remove-relation mysql-router 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 +``` +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 new file mode 100644 index 00000000..1f90e77b --- /dev/null +++ b/docs/tutorial/t-enable-security.md @@ -0,0 +1,95 @@ +> This is part of the [Charmed MySQLRouter Tutorial](https://charmhub.io/mysql-router/docs/t-overview?channel=dpe/edge). 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 MySQLRouter so that configuring TLS requires minimal effort on your end. + +TLS is enabled by integrating Charmed MySQLRouter 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 MySQLRouter 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](https://discourse.charmhub.io/t/security-with-x-509-certificates/11664) for an overview of the TLS certificates charms available. +[/note] + +--- + +## Enable TLS + +Before enabling TLS on Charmed MySQLRouter, we must first deploy the `self-signed-certificates` charm: + +``` +juju deploy self-signed-certificates --config ca-common-name="Tutorial CA" +``` + +Wait until the `self-signed-certificates` is up and active, then use `juju status โ€“watch 1s` to monitor the progress: + +``` +Model Controller Cloud/Region Version SLA Timestamp +database lxd localhost/localhost 3.1.8 unsupported 18:47:51Z + +App Version Status Scale Charm Channel Rev Exposed Message +mysql 8.0.34-0ubun... active 1 mysql 8.0/stable 196 no +mysql-router 8.0.36-0ubun... active 1 mysql-router 103 no +mysql-test-app 0.0.2 active 1 mysql-test-app stable 36 no +self-signed-certificates active 1 self-signed-certificates stable 72 no + +Unit Workload Agent Machine Public address Ports Message +mysql-test-app/0* active idle 1 10.205.193.227 + mysql-router/0* active idle 10.205.193.227 +mysql/0* active idle 0 10.205.193.171 3306,33060/tcp Primary +self-signed-certificates/0* active idle 2 10.205.193.175 + +Machine State Address Inst id Base AZ Message +0 started 10.205.193.171 juju-3c2f36-0 ubuntu@22.04 Running +1 started 10.205.193.227 juju-3c2f36-1 ubuntu@22.04 Running +2 started 10.205.193.175 juju-3c2f36-2 ubuntu@22.04 Running +``` + +To enable TLS on Charmed MySQLRouter, integrate the two applications: + +``` +juju integrate mysql-router self-signed-certificates +``` + +### Check the TLS certificate in use: + +Use `openssl` to connect to MySQLRouter in the juju machine, and check the TLS certificate in use: + +``` +ubuntu@localhost:~$ juju ssh mysql-router/0 "openssl s_client -showcerts -starttls mysql -unix /var/snap/charmed-mysql/common/run/mysqlrouter/mysql.sock < /dev/null | openssl x509 -text | grep Issuer" +... + Issuer: C = US, CN = Tutorial CA +... +``` + +Congratulations! MySQLRouter 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: + +``` +juju remove-relation mysql-router self-signed-certificatese +``` + +### Check the TLS certificate in use: + +``` +ubuntu@localhost:~$ juju ssh mysql-router/0 "openssl s_client -showcerts -starttls mysql -unix /var/snap/charmed-mysql/common/run/mysqlrouter/mysql.sock < /dev/null | openssl x509 -text | grep Issuer" +``` + +The output should be similar to: + +``` +... + Issuer: CN = MySQL_Router_Auto_Generated_CA_Certificate +... + +``` + +The Charmed MySQLRouter application reverted to the placeholder certificate that was created locally during the MySQLRouter installation. \ No newline at end of file diff --git a/docs/tutorial/t-managing-units.md b/docs/tutorial/t-managing-units.md new file mode 100644 index 00000000..77cef04f --- /dev/null +++ b/docs/tutorial/t-managing-units.md @@ -0,0 +1,80 @@ +# Scale your MySQL Router + +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 operator [here](https://charmhub.io/mysql/docs/t-managing-units). + +TODO... + \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md new file mode 100644 index 00000000..f8ad76e9 --- /dev/null +++ b/docs/tutorial/t-overview.md @@ -0,0 +1,20 @@ +# MySQL Router tutorial + +The MySQL Router 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 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 [LXD](https://ubuntu.com/lxd) and [Juju](https://juju.is/). +- Deploy MySQL Router using a single command. +- Configure TLS certificate in one command. + +While this tutorial intends to guide and teach you as you deploy MySQL Router, it will be most beneficial if you already have a familiarity with: +- Basic terminal commands. +- MySQL and MySQL Router concepts. +- [Charmed MySQL operator](https://charmhub.io/mysql) + +## 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/TODO) +* [Deploy MySQL Router](/t/TODO) +* [Managing your units](/t/TODO) +* [Enable security](/t/TODO) +* [Cleanup your environment](/t/TODO) \ No newline at end of file diff --git a/docs/tutorial/t-setup-environment.md b/docs/tutorial/t-setup-environment.md new file mode 100644 index 00000000..92850a9d --- /dev/null +++ b/docs/tutorial/t-setup-environment.md @@ -0,0 +1,47 @@ +# Environment Setup + +This is part of the [MySQL Router Tutorial](/t/12332). 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/TODO). + +## 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 # tune CPU/RAM/HDD accordingly to your needs +``` +*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 LXD and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). Let's bootstrap Juju to use local LXD: +```shell +juju bootstrap localhost overlord +``` + +The controller can work with different models; models host applications such as MySQL Router. Set up a specific model for Charmed MySQL+MySQL Router 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: +``` +Model Controller Cloud/Region Version SLA Timestamp +tutorial overlord localhost/localhost 3.1.6 unsupported 23:20:53+01:00 + +Model "admin/tutorial" is empty. +``` \ No newline at end of file