diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml new file mode 100644 index 0000000000..479ebcbdc8 --- /dev/null +++ b/.github/workflows/automatic-doc-checks.yml @@ -0,0 +1,24 @@ +# +name: Automatic doc checks + +on: + push: + branches: [ main ] + pull_request: + paths: + - 'docs/**' # Only run on changes to the docs directory + + workflow_dispatch: + # Manual trigger + + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + documentation-checks: + uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main + with: + working-directory: "docs" + fetch-depth: 0 diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index c099155948..50a6100232 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,33 +1,60 @@ # Leave a blank line at the end of this file to support concatenation +airgap +async backend backends +backport Charmcraft cjk cryptographically +databag dvipng fonts freefont +Furo github +GitHub GPG gyre -https html -io +https +InnoDB Intersphinx +io +ip +Jira +landscape lang +lastmod LaTeX latexmk +MinIO Multipass +mydumper +mysql +MyST +nameserver +nameservers +Open Graph otf +PDF +Percona plantuml PNG +PR Pygments pymarkdown QEMU -Rockcraft +Read the Docs readthedocs +reStructuredText +Rockcraft rst sitemapindex +snap_daemon +Sphinx +Spread +spread_test_example subproject subprojects SVG @@ -37,29 +64,17 @@ TOC toctree txt uncommenting +URL utils VMs WCAG whitespace whitespaces wordlist +xbstream xetex xindy xml -ip -spread_test_example -Furo -PDF -Open Graph -MyST -YouTube -reStructuredText -GitHub -Sphinx -URL -PR -Read the Docs -Spread -landscape -lastmod +xtrabackup yaml +YouTube diff --git a/docs/.sphinx/update_sp.py b/docs/.sphinx/update_sp.py deleted file mode 100755 index c5834df7f8..0000000000 --- a/docs/.sphinx/update_sp.py +++ /dev/null @@ -1,269 +0,0 @@ -#! /usr/bin/env python - -# Initial update script for the starter pack. -# -# Requires some manual intervention, but makes identifying updates and differences easier. -# -# For debugging, please run this script with DEBUGGING=1 -# e.g. user@device:~/git/Canonical/sphinx-docs-starter-pack/docs$ DEBUGGING=1 python .sphinx/update_sp.py - - -import glob -import logging -import os -import requests -import re -import subprocess -import sys -from requests.exceptions import RequestException -from packaging.version import parse as parse_version - -SPHINX_DIR = os.path.join(os.getcwd(), ".sphinx") -SPHINX_UPDATE_DIR = os.path.join(SPHINX_DIR, "update") -GITHUB_REPO = "canonical/sphinx-docs-starter-pack" -GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}" -GITHUB_API_SPHINX_DIR = f"{GITHUB_API_BASE}/contents/docs/.sphinx" -GITHUB_RAW_BASE = f"https://raw.githubusercontent.com/{GITHUB_REPO}/main" - -TIMEOUT = 10 # seconds - -# Check if debugging -if os.getenv("DEBUGGING"): - logging.basicConfig(level=logging.DEBUG) - - -def main(): - # Check local version - logging.debug("Checking local version") - try: - with open(os.path.join(SPHINX_DIR, "version")) as f: - local_version = f.read().strip() - except FileNotFoundError: - print("WARNING\nWARNING\nWARNING") - print( - "You need to update to at least version 1.0.0 of the starter pack to start using the update function." - ) - print("You may experience issues using this functionality.") - logging.debug("No local version found. Setting version to None") - local_version = "None" - except Exception as e: - logging.debug(e) - raise Exception("ERROR executing check local version") - logging.debug(f"Local version = {local_version}") - - # Check release version - latest_release = query_api(GITHUB_API_BASE + "/releases/latest").json()["tag_name"] - logging.debug(f"Latest release = {latest_release}") - - # Perform actions only if local version is older than release version - logging.debug("Comparing versions") - if parse_version(local_version) < parse_version(latest_release): - logging.debug("Local version is older than the release version.") - print("Starter pack is out of date.\n") - - # Identify and download '.sphinx' dir files to '.sphinx/update' - files_updated, new_files = update_static_files() - - # Write new version to file to '.sphinx/update' - - download_file( - GITHUB_RAW_BASE + "/docs/.sphinx/version", - os.path.join(SPHINX_UPDATE_DIR, "version"), - ) - - # Provide changelog to identify other significant changes - changelog = query_api(GITHUB_RAW_BASE + "/CHANGELOG.md") - logging.debug("Changelog obtained") - version_regex = re.compile(r"#+ +" + re.escape(local_version) + r" *\n") - print("SEE CURRENT CHANGELOG:") - print(re.split(version_regex, changelog.text)[0]) - - # Provide information on any files identified for updates - if files_updated: - logging.debug("Updated files found and downloaded") - print("Differences have been identified in static files.") - print("Updated files have been downloaded to '.sphinx/update'.") - print("Validate and move these files into your '.sphinx/' directory.") - else: - logging.debug("No files found to update") - # Provide information on NEW files - if new_files: - logging.debug("New files found and downloaded") - print( - "NOTE: New files have been downloaded\n", - "See 'NEWFILES.txt' for all downloaded files\n", - "Validate and merge these files into your '.sphinx/' directory", - ) - else: - logging.debug("No new files found to download") - else: - logging.debug("Local version and release version are the same") - print("This version is up to date.") - - # Check requirements are the same - new_requirements = [] - try: - with open("requirements.txt", "r") as file: - logging.debug("Checking requirements") - - local_reqs = set(file.read().splitlines()) - {""} - requirements = set( - query_api(GITHUB_RAW_BASE + "/docs/requirements.txt").text.splitlines() - ) - - new_requirements = requirements - local_reqs - - for req in new_requirements: - logging.debug(f"{req} not found in local requirements.txt") - - for req in requirements & local_reqs: - logging.debug(f"{req} already exists in local requirements.txt") - - if new_requirements != set(): - print( - "You may need to add the following pacakges to your requirements.txt file:" - ) - for r in new_requirements: - print(f"{r}\n") - except FileNotFoundError: - print("requirements.txt not found") - print( - "The updated starter pack has moved requirements.txt out of the '.sphinx' dir" - ) - print("requirements.txt not checked, please update your requirements manually") - - -def update_static_files(): - """Checks local files against remote for new and different files, downloads to '.sphinx/updates'""" - files, paths = get_local_files_and_paths() - new_file_list = [] - - for item in query_api(GITHUB_API_SPHINX_DIR).json(): - logging.debug(f"Checking {item['name']}") - # Checks existing files in '.sphinx' starter pack static root for changed SHA - if item["name"] in files and item["type"] == "file": - index = files.index(item["name"]) - if item["sha"] != get_git_revision_hash(paths[index]): - logging.debug(f"Local {item['name']} is different to remote") - download_file( - item["download_url"], os.path.join(SPHINX_UPDATE_DIR, item["name"]) - ) - if item["name"] == "update_sp.py": - # Indicate update script needs to be updated and re-run - print("WARNING") - print( - "THIS UPDATE SCRIPT IS OUT OF DATE. YOU MAY NEED TO RUN ANOTHER UPDATE AFTER UPDATING TO THE FILE IN '.sphinx/updates'." - ) - print("WARNING\n") - else: - logging.debug("File hashes are equal") - # Checks nested files '.sphinx/**/**.*' for changed SHA (single level of depth) - elif item["type"] == "dir": - logging.debug(item["name"] + " is a directory") - for nested_item in query_api( - f"{GITHUB_API_SPHINX_DIR}/{item['name']}" - ).json(): - logging.debug(f"Checking {nested_item['name']}") - if nested_item["name"] in files: - index = files.index(nested_item["name"]) - if nested_item["sha"] != get_git_revision_hash(paths[index]): - logging.debug( - f"Local {nested_item['name']} is different to remote" - ) - download_file( - nested_item["download_url"], - os.path.join( - SPHINX_UPDATE_DIR, item["name"], nested_item["name"] - ), - ) - # Downloads NEW nested files - else: - logging.debug(f"No local version found of {nested_item['name']}") - if nested_item["type"] == "file": - new_file_list.append(nested_item["name"]) - download_file( - nested_item["download_url"], - os.path.join( - SPHINX_UPDATE_DIR, item["name"], nested_item["name"] - ), - ) - # Downloads NEW files in '.sphinx' starter pack static root - else: - if item["type"] == "file": - logging.debug(f"No local version found of {item['name']}") - download_file( - item["download_url"], os.path.join(SPHINX_UPDATE_DIR, item["name"]) - ) - if item["name"] != "version": - new_file_list.append(item["name"]) - # Writes return value for parent function - if os.path.exists(os.path.join(SPHINX_UPDATE_DIR)): - logging.debug("Files have been downloaded") - files_updated = True - else: - logging.debug("No downloads found") - files_updated = False - # Writes return value for parent function - if new_file_list != []: - # Provides more information on new files - with open("NEWFILES.txt", "w") as f: - for entry in new_file_list: - f.write(f"{entry}\n") - logging.debug("Some downloaded files are new") - return files_updated, True - return files_updated, False - - -# Checks git hash of a file -def get_git_revision_hash(file) -> str: - """Get SHA of local files""" - logging.debug(f"Getting hash of {os.path.basename(file)}") - return subprocess.check_output(["git", "hash-object", file]).decode("ascii").strip() - - -# Examines local files -def get_local_files_and_paths(): - """Identify '.sphinx' local files and paths""" - logging.debug("Checking local files and paths") - try: - files = [] - paths = [] - patterns = [".*", "**.*", "metrics/**.*"] - files, paths = [], [] - - for pattern in patterns: - for file in glob.iglob(os.path.join(SPHINX_DIR, pattern), recursive=True): - files.append(os.path.basename(file)) - paths.append(file) - return files, paths - except Exception as e: - logging.debug(e) - raise RuntimeError("get_local_files_and_paths()") from e - - -# General API query with timeout and RequestException -def query_api(url): - """Query an API with a globally set timeout""" - logging.debug(f"Querying {url}") - try: - r = requests.get(url, timeout=TIMEOUT) - return r - except RequestException as e: - raise RuntimeError(f"Failed query_api(): {url}") from e - - -# General file download function -def download_file(url, output_path): - """Download a file to a specified path""" - logging.debug(f"Downloading {os.path.basename(output_path)}") - try: - os.makedirs(os.path.dirname(output_path), exist_ok=True) - with open(output_path, "wb") as file: - file.write(query_api(url).content) - except Exception as e: - logging.debug(e) - raise RuntimeError(f"Failed download_file(): {url}") from e - - -if __name__ == "__main__": - sys.exit(main()) # Keep return code diff --git a/docs/conf.py b/docs/conf.py index 1e2b903b0f..93b40ee9ff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -228,7 +228,11 @@ linkcheck_ignore = [ "http://127.0.0.1:8000", - "https://github.com/canonical/ACME/*" + "https://github.com/canonical/ACME/*", + "https://matrix.to/*", + "https://portal.azure.com/*", + "https://dev.mysql.com/*", + "https://www.mysql.com/*" ] diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index dc4a3f10ec..7b273f2acd 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md @@ -41,9 +41,9 @@ The `mysql-router` snap service used in [Charmed MySQL Router](https://charmhub. All `exporter` services are activated after the relation with [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) only. -> **:information_source: Note:** it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!! +> **Note:** it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!! -> **:warning: Important:** all snap resources must be executed under the special user `snapd_daemon` only! +> **Important:** all snap resources must be executed under the special user `snapd_daemon` only! The snap "charmed-mysql" also ships list of tools used by charm: * `charmed-mysql.mysql` (alias `mysql`) - mysql client to connect `mysqld`. diff --git a/docs/explanation/index.md b/docs/explanation/index.md index b0321effb6..0bff3ed82c 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -3,41 +3,32 @@ Additional context about key concepts behind the MySQL charm. ## Core concepts and design -* [Architecture] -* [Interfaces and endpoints] -* [Juju] -* [Legacy charm] -## Operational concepts -* [Users] -* [Logs] - * [Audit logs] - -## Security and hardening -* [Security hardening guide][Security] - * [Cryptography] +```{toctree} +:titlesonly: +:maxdepth: 2 - +Architecture +Interfaces and endpoints +Juju +Legacy charm +``` -[Architecture]: /explanation/architecture -[Interfaces and endpoints]: /explanation/interfaces-and-endpoints -[Juju]: /explanation/juju -[Legacy charm]: /explanation/legacy-charm +## Operational concepts -[Users]: /explanation/users -[Logs]: /explanation/logs/index -[Audit logs]: /explanation/logs/audit-logs +```{toctree} +:titlesonly: +:maxdepth: 2 -[Security]: /explanation/security/index -[Cryptography]: /explanation/security/cryptography +Users +Logs +``` +## Security and hardening ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* -*/index +Security ``` diff --git a/docs/explanation/interfaces-and-endpoints.md b/docs/explanation/interfaces-and-endpoints.md index 864380b8e6..8af0c03143 100644 --- a/docs/explanation/interfaces-and-endpoints.md +++ b/docs/explanation/interfaces-and-endpoints.md @@ -1,6 +1,4 @@ - # Interfaces/endpoints -> **:information_source: Hint**: Use [Juju 3](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). Otherwise replace `juju integrate` with `juju relate` for Juju 2.9. Charmed MySQL VM supports modern `mysql_client` and legacy `mysql`, `mysql-shared`, `mysql-router` interfaces (in a backward compatible mode). @@ -12,7 +10,7 @@ This charm provides modern [‘mysql_client’ ](https://github.com/canonical/ch ### Modern `mysql_client` interface (`database` endpoint): -Adding a relation is accomplished with `juju integrate` via endpoint `database`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example: +Adding a relation is accomplished with `juju integrate` via endpoint `database`. Read more about [Juju relations (integrations)](https://documentation.ubuntu.com/juju/3.6/reference/relation/). Example: ```shell # Deploy Charmed MySQL cluster with 3 nodes @@ -40,11 +38,11 @@ Find all details about default and extra DB user roles in “[Charm Users explan **Note:** Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided. Check the legacy interface implementation limitations in the "[Legacy charm](/explanation/legacy-charm)" document. -This charm supports several legacy interfaces, e.g. `mysql`, `mysql-shared`, `mysql-router`. They were used in some legacy charms in [cross-model relations](https://juju.is/docs/olm/cross-model-integration). +This charm supports several legacy interfaces, e.g. `mysql`, `mysql-shared`, `mysql-router`. They were used in some legacy charms in [cross-model relations](https://documentation.ubuntu.com/juju/3.6/reference/relation/#cross-model). ### `mysql` interface (`mysql` endpoint) -It was a popular interface used by some legacy charms (e.g. "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)"), often in [cross-model relations](https://juju.is/docs/olm/cross-model-integration): +It was a popular interface used by some legacy charms (e.g. "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)"), often in [cross-model relations](https://documentation.ubuntu.com/juju/3.6/reference/relation/#cross-model): ```shell juju deploy mysql --channel 8.0 @@ -65,7 +63,7 @@ juju integrate mysql-router keystone juju integrate mysql:db-router mysql-router:db-router ``` -**Note:** pay attention to deploy identical [series](https://juju.is/docs/olm/deploy-an-application-with-a-specific-series) for `keystone` and `mysql-router` applications (due to the [subordinate](https://juju.is/docs/sdk/charm-types#subordinate-charms) charm nature of `mysql-router`). +**Note:** pay attention to deploy identical [series/base](https://documentation.ubuntu.com/juju/3.6/reference/machine/#machine-base) for `keystone` and `mysql-router` applications (due to the [subordinate](https://documentation.ubuntu.com/juju/3.6/reference/charm/#subordinate) charm nature of `mysql-router`). ### `mysql-shared` interface (`shared-db` endpoint) diff --git a/docs/explanation/juju.md b/docs/explanation/juju.md index ce1afd97ec..16c0f50773 100644 --- a/docs/explanation/juju.md +++ b/docs/explanation/juju.md @@ -26,7 +26,7 @@ In the context of this guide, the pertinent changes are shown here: |`run`|`exec`| |`run-action --wait`|`run`| -See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022) for the comprehensive list of changes. +See the [Juju 3.0 release notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#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: diff --git a/docs/explanation/legacy-charm.md b/docs/explanation/legacy-charm.md index fc7573e05f..2b27aa9441 100644 --- a/docs/explanation/legacy-charm.md +++ b/docs/explanation/legacy-charm.md @@ -3,11 +3,11 @@ ## Charm types "legacy" vs "modern" -Historically, there were [several](https://juju.is/docs/sdk/charm-taxonomy#charm-types-by-generation) operators/charms to provide MySQL/MariaDB functionality: "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)". All of them are named "legacy" charms. +Historically, there were [several](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) operators/charms to provide MySQL/MariaDB functionality: "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)". All of them are named "legacy" charms. This "Charmed MySQL" operator is a modern "[Charmed Operator SDK](https://juju.is/docs/sdk)"-based charm to replace all legacy operators providing all [interfaces/endpoints](/explanation/interfaces-and-endpoints) of legacy charms. -The legacy charm provided endpoints `mysql` and `mysql-root` (for the interface `mysql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `mysql_client`). Read more detail about the available endpoints/interfaces for [VM](https://charmhub.io/mysql/docs/e-interfaces) and [K8s](https://charmhub.io/mysql-k8s/docs/e-interfaces) charms. +The legacy charm provided endpoints `mysql` and `mysql-root` (for the interface `mysql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `mysql_client`). Read more detail about the available endpoints/interfaces for [VM](https://charmhub.io/mysql/integrations) and [K8s](https://charmhub.io/mysql-k8s/integrations) charms. **Note**: Please choose one endpoint to use. No need to relate all of them simultaneously! @@ -28,9 +28,14 @@ The "modern" charm provides temporary support for the legacy interfaces: trust: true ``` -* **proper migration**: migrate the application to the new interface "[mysql_client](https://github.com/canonical/charm-relation-interfaces)". The application will 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/)" via endpoint `database`. +* **proper migration**: migrate the application to the new interface "[`mysql_client`](https://github.com/canonical/charm-relation-interfaces)". The application will 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/)" via endpoint `database`. -**Warning**: NO in-place upgrades possible! Legacy charm cannot be upgraded to Operator-framework-based one. To move DB data, the second/modern DB application must be launched nearby and data should be copied from "legacy" application to the "modern" one. Canonical Data Platform team will prepare the copy&paste guide. Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need migration instructions. +```{caution} +In-place upgrades from the legacy charm to the modern, Ops-based charm are **not supported**. + + +To migrate database data, the legacy and modern MySQL charms must both be running simultaneously. The data can then be copied from the legacy application to the modern one. Please [contact us](/reference/contacts) if you need help with data migration. +``` ## How to deploy old "legacy" mysql charm @@ -49,7 +54,7 @@ Deploy the charm using the proper charm/channel `latest/stable`: ## Supported MySQL versions by modern charm At the moment, both K8s and VM modern charms support MySQL 8.0 (based on Jammy/22.04 series) only. -Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need different versions/series. +Please [contact us](/reference/contacts) if you need different versions/series. ## Supported architectures: amd64, arm64, ... @@ -59,5 +64,5 @@ Currently, the charm supports architecture `amd64` only. See the technical detai The "modern charm" (from `8.0/stable`) is stored on [GitHub](https://github.com/canonical/mysql-operator), here is the link to report [modern charm issues](https://github.com/canonical/mysql-operator/issues/new/choose). -Do you have questions? [Contact us](https://chat.charmhub.io/charmhub/channels/data-platform)! +Do you have questions? [Contact us](/reference/contacts)! diff --git a/docs/explanation/logs/index.md b/docs/explanation/logs/index.md index be337084e4..434c25b73f 100644 --- a/docs/explanation/logs/index.md +++ b/docs/explanation/logs/index.md @@ -172,8 +172,6 @@ for the duration of the event handler. ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* +Audit logs ``` diff --git a/docs/explanation/security/index.md b/docs/explanation/security/index.md index 26fd4d5c03..1e10e0741a 100644 --- a/docs/explanation/security/index.md +++ b/docs/explanation/security/index.md @@ -17,14 +17,14 @@ Charmed MySQL can be deployed on top of several clouds and virtualisation layers | Cloud | Security guides | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OpenStack | [OpenStack Security Guide](https://docs.openstack.org/security-guide/) | -| AWS | [Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html#access-keys-and-secret-access-keys) | +| AWS | [Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) | | Azure | [Azure security best practices and patterns](https://learn.microsoft.com/en-us/azure/security/fundamentals/best-practices-and-patterns), [Managed identities for Azure resource](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/) | | GCP | [Google security overview](https://cloud.google.com/kubernetes-engine/docs/concepts/security-overview), [Harden your cluster's security](https://cloud.google.com/kubernetes-engine/docs/concepts/security-overview) | ### Juju Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the -[Juju security page](https://discourse.charmhub.io/t/juju-security/15684) and the [How to harden your deployment](https://juju.is/docs/juju/harden-your-deployment) guide. +[Juju security page](https://documentation.ubuntu.com/juju/latest/explanation/juju-security/index.html) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/#harden-your-deployment) guide. #### Cloud credentials @@ -63,7 +63,7 @@ Charmed MySQL operator and Charmed MySQL Router operator install a pinned revisi New versions (revisions) of charmed operators can be released to upgrade workloads, the operator's code, or both. It is important to refresh the charm regularly to make sure the workload is as secure as possible. -For more information on upgrading the charm, see the [How to upgrade MySQL](https://canonical.com/data/docs/mysql/iaas/h-upgrade) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router/docs/h-upgrade-intro?channel=dpe/edge) guides, as well as the [Release notes](https://canonical.com/data/docs/mysql/iaas/r-releases). +For more information on upgrading the charm, see the [How to upgrade MySQL](https://canonical.com/data/docs/mysql/iaas/h-upgrade) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router/docs/h-upgrade?channel=dpe/edge) guides, as well as the [Release notes](https://canonical.com/data/docs/mysql/iaas/r-releases). ### Encryption @@ -93,8 +93,7 @@ For details on the cryptography used by Charmed MySQL, see the [Cryptography](ht ```{toctree} :titlesonly: :maxdepth: 2 -:glob: :hidden: -* +cryptography ``` diff --git a/docs/explanation/users.md b/docs/explanation/users.md index 4c29de6620..2132ebd758 100644 --- a/docs/explanation/users.md +++ b/docs/explanation/users.md @@ -1,4 +1,3 @@ - # Users There are two types of users in MySQL: @@ -10,11 +9,11 @@ There are two types of users in MySQL: The operator uses the following internal DB users: -* `root` - the [initial/default](https://charmhub.io/mysql/docs/t-manage-passwords) MySQL user. Used for very initial bootstrap and restricted to local access. +* `root` - the [initial/default](/tutorial/4-manage-passwords) MySQL user. Used for very initial bootstrap and restricted to local access. * `clusteradmin` - the user to manage replication in the MySQL InnoDB ClusterSet. * `serverconfig` - the user that operates MySQL instances. -* `monitoring` - the user for [COS integration](https://charmhub.io/mysql/docs/h-enable-monitoring). -* `backups` - the user to [perform/list/restore backups](https://charmhub.io/mysql/docs/h-create-and-list-backups). +* `monitoring` - the user for [COS integration](/how-to/monitoring-cos/enable-monitoring). +* `backups` - the user to [perform/list/restore backups](/how-to/back-up-and-restore/create-a-backup). * `mysql_innodb_cluster_#######` - the [internal recovery users](https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-cluster-user-accounts.html#mysql-innodb-cluster-users-created) which enable connections between the servers in the cluster. Dedicated user created for each Juju unit/InnoDB Cluster member. * `mysql_innodb_cs_#######` - the internal recovery user which enable connections between MySQl InnoDB Clusters in ClusterSet. One user is created for entire MySQL ClusterSet. @@ -41,7 +40,7 @@ mysql> select Host,User,account_locked from mysql.user; 10 rows in set (0.00 sec) ``` **Note**: it is forbidden to use/manage described above users! They are dedicated to the operators logic! -Please use [data-integrator](https://charmhub.io/mysql/docs/t-integrations) charm to generate/manage/remove an external credentials. +Please use the [data-integrator](https://charmhub.io/data-integrator) charm to generate/manage/remove an external credentials. It is allowed to rotate passwords for *internal* users using action `set-password` diff --git a/docs/how-to/back-up-and-restore/configure-s3-aws.md b/docs/how-to/back-up-and-restore/configure-s3-aws.md index 61e3302059..181b3b547e 100644 --- a/docs/how-to/back-up-and-restore/configure-s3-aws.md +++ b/docs/how-to/back-up-and-restore/configure-s3-aws.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` Charmed MySQL backup can be stored on any S3 compatible storage. The S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). Deploy and configure the s3-integrator charm for **[AWS S3](https://aws.amazon.com/s3/)** (click [here](/how-to/back-up-and-restore/configure-s3-radosgw) to backup on Ceph via RadosGW): diff --git a/docs/how-to/back-up-and-restore/configure-s3-radosgw.md b/docs/how-to/back-up-and-restore/configure-s3-radosgw.md index b283523702..bef96d03c8 100644 --- a/docs/how-to/back-up-and-restore/configure-s3-radosgw.md +++ b/docs/how-to/back-up-and-restore/configure-s3-radosgw.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` A MySQL backup can be stored on any S3-compatible storage. S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). diff --git a/docs/how-to/back-up-and-restore/create-a-backup.md b/docs/how-to/back-up-and-restore/create-a-backup.md index 1e00452269..32a42fada6 100644 --- a/docs/how-to/back-up-and-restore/create-a-backup.md +++ b/docs/how-to/back-up-and-restore/create-a-backup.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` # How to create and list backups diff --git a/docs/how-to/back-up-and-restore/index.md b/docs/how-to/back-up-and-restore/index.md index 47aad65549..8e9cb81d1c 100644 --- a/docs/how-to/back-up-and-restore/index.md +++ b/docs/how-to/back-up-and-restore/index.md @@ -1,11 +1,12 @@ - -# Back-Up-And-Restore +# Back up and restore ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* +Configure S3 AWS +Configure S3 RadosGW +Create a backup +Restore a backup +Migrate a cluster ``` diff --git a/docs/how-to/back-up-and-restore/migrate-a-cluster.md b/docs/how-to/back-up-and-restore/migrate-a-cluster.md index 38f7ee334a..52d95e9db2 100644 --- a/docs/how-to/back-up-and-restore/migrate-a-cluster.md +++ b/docs/how-to/back-up-and-restore/migrate-a-cluster.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` # How to migrate a cluster diff --git a/docs/how-to/back-up-and-restore/restore-a-backup.md b/docs/how-to/back-up-and-restore/restore-a-backup.md index 9c94554d08..13d66140ef 100644 --- a/docs/how-to/back-up-and-restore/restore-a-backup.md +++ b/docs/how-to/back-up-and-restore/restore-a-backup.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` # How to restore a local backup diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md index 3761da92a8..a58933f105 100644 --- a/docs/how-to/contribute.md +++ b/docs/how-to/contribute.md @@ -1,4 +1,3 @@ - # How to contribute ```{caution} @@ -11,7 +10,7 @@ This page explains the processes and practices recommended for contributing to t ## Submit a bug or issue * Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-operator/issues) -* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File) +* Report security issues through [**Launchpad**](https://launchpad.net/mysql) ## Contribute to the code @@ -21,7 +20,7 @@ If you would like to chat with us about your use-cases or proposed implementatio ### Tips for a good contribution -* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library. +* Familiarize 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 diff --git a/docs/how-to/cross-regional-async-replication/clients.md b/docs/how-to/cross-regional-async-replication/clients.md index 230fbddb25..fecab47f3c 100644 --- a/docs/how-to/cross-regional-async-replication/clients.md +++ b/docs/how-to/cross-regional-async-replication/clients.md @@ -1,8 +1,5 @@ - # Clients -# Clients for Async replication - ## Pre-requisites Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)! diff --git a/docs/how-to/cross-regional-async-replication/deploy.md b/docs/how-to/cross-regional-async-replication/deploy.md index b81247250c..efb8b3723f 100644 --- a/docs/how-to/cross-regional-async-replication/deploy.md +++ b/docs/how-to/cross-regional-async-replication/deploy.md @@ -1,5 +1,4 @@ - -# Deploy Async replication +# Deploy async replication The following table shows the source and target controller/model combinations that are currently supported: diff --git a/docs/how-to/cross-regional-async-replication/index.md b/docs/how-to/cross-regional-async-replication/index.md index a4d5ac855c..8048c4905f 100644 --- a/docs/how-to/cross-regional-async-replication/index.md +++ b/docs/how-to/cross-regional-async-replication/index.md @@ -1,11 +1,12 @@ - -# Cross-Regional-Async-Replication +# Cross-regional asynchronous replication ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* +Deploy +Clients +Switchover/failover +Recovery +Removal ``` diff --git a/docs/how-to/cross-regional-async-replication/recovery.md b/docs/how-to/cross-regional-async-replication/recovery.md index a4a9c33101..ead25741ea 100644 --- a/docs/how-to/cross-regional-async-replication/recovery.md +++ b/docs/how-to/cross-regional-async-replication/recovery.md @@ -1,8 +1,5 @@ - # Recovery -# Recovery of Async replication - ## Pre-requisites Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)! diff --git a/docs/how-to/cross-regional-async-replication/removal.md b/docs/how-to/cross-regional-async-replication/removal.md index 5ab8d05e88..f160479225 100644 --- a/docs/how-to/cross-regional-async-replication/removal.md +++ b/docs/how-to/cross-regional-async-replication/removal.md @@ -1,8 +1,5 @@ - # Removal -# Removal of Async replication - ## Pre-requisites Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)! diff --git a/docs/how-to/cross-regional-async-replication/switchover-failover.md b/docs/how-to/cross-regional-async-replication/switchover-failover.md index 03efdb2b3b..4c67d65d63 100644 --- a/docs/how-to/cross-regional-async-replication/switchover-failover.md +++ b/docs/how-to/cross-regional-async-replication/switchover-failover.md @@ -1,8 +1,5 @@ - # Switchover / Failover -# Switchover / Failover of Async replication - ## Pre-requisites Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)! diff --git a/docs/how-to/deploy/air-gapped.md b/docs/how-to/deploy/air-gapped.md index fc92d5933e..19f8ccab4d 100644 --- a/docs/how-to/deploy/air-gapped.md +++ b/docs/how-to/deploy/air-gapped.md @@ -10,9 +10,9 @@ Canonical does not prescribe how you should set up your specific air-gapped envi * A VM/hardware resources available for Juju. * DNS is configured to the local nameservers. -* [Juju is configured](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#configure-juju) to use local air-gapped services. +* [Juju is configured](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#configure-juju) to use local air-gapped services. * The [`store-admin`](https://snapcraft.io/store-admin) tool is installed and configured. -* [Air-gapped CharmHub](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/) is installed and running. +* [Air-gapped CharmHub](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub) is installed and running. * [Air-gapped Snap Store Proxy](https://documentation.ubuntu.com/snap-store-proxy/) is installed and running. * Local APT and LXD Images caches are reachable. @@ -33,8 +33,8 @@ Future improvements are planned to the `store-admin` tool so that it could poten #### Charms The necessary charm(s) can be exported as bundle or independently (charm-by-charm). See the Snap Proxy documentation: -* [Offline Charmhub configuration > Export charm bundle](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charm-bundles) -* [Offline Charmhub configuration > Export charms](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charms) +* [Offline Charmhub configuration > Export charm bundle](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-charm-bundles) +* [Offline Charmhub configuration > Export charms](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-charms) The bundle export example: @@ -69,7 +69,7 @@ Successfully exported charm bundle mysql-bundle: /home/ubuntu/snap/store-admin/c #### SNAPs -Usually charms require SNAPs (and some manually pin them). For the manual SNAP exports, follow the official Snap Store Proxy documentation: [Offline Charmhub configuration > Export SNAP](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-snap-resources). Data team is shipping the mapping [snap.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/) to the published [bundle.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/): +Usually charms require SNAPs (and some manually pin them). For the manual SNAP exports, follow the official Snap Store Proxy documentation: [Offline Charmhub configuration > Export SNAP](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-snap-resources). Data team is shipping the mapping [snap.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/) to the published [bundle.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/): > **Warning**: always use snap.yaml and bundle.yaml from the same Git commit (to match each other)! @@ -110,7 +110,7 @@ cp /media/usb/*.tar.gz /var/snap/snap-store-proxy/common/charms-to-push/ (3-import-snaps-and-charms)= ### 3. Import snaps and charms - Import the [snap](https://documentation.ubuntu.com/snap-store-proxy/en/airgap/#importing-pushing-snaps) and [charm](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) blobs into local air-gapped CharmHub: + Import the [snap](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap/#importing-pushing-snaps) and [charm](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#import-packages) blobs into local air-gapped CharmHub: > **Note**: when importing machine charms that depend on a snap for functionality, you must first manually import the required snap. ```shell @@ -118,7 +118,7 @@ sudo snap-store-proxy push-snap /var/snap/snap-store-proxy/common/snaps-to-push/ sudo snap-store-proxy push-charm-bundle /var/snap/snap-store-proxy/common/charms-to-push/mysql-bundle-20241003T104903.tar.gz ``` -> **Note**: when [re-importing](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) charms or importing other revisions, make sure to provide the `--push-channel-map`. +> **Note**: when [re-importing](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#import-packages) charms or importing other revisions, make sure to provide the `--push-channel-map`. (4-deploy-mysql)= ### 4. Deploy MySQL @@ -137,8 +137,8 @@ Use [the official release notes](/reference/releases) as a reference. * https://docs.ubuntu.com/snap-store-proxy/en/airgap * https://documentation.ubuntu.com/snap-store-proxy/ -* https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/ +* https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub * https://ubuntu.com/kubernetes/docs/install-offline -* [Charmed Kubeflow > Install in an airgapped environment](https://charmed-kubeflow.io/docs/install-in-airgapped-environment) +* [Charmed Kubeflow > Install in an air-gapped environment](https://documentation.ubuntu.com/charmed-kubeflow/how-to/install/install-air-gapped/) * [Wikipedia > Air gap (networking)](https://en.wikipedia.org/wiki/Air_gap_(networking)) diff --git a/docs/how-to/deploy/aws-ec2.md b/docs/how-to/deploy/aws-ec2.md index e3ec6cee6f..07245d858c 100644 --- a/docs/how-to/deploy/aws-ec2.md +++ b/docs/how-to/deploy/aws-ec2.md @@ -1,4 +1,3 @@ - # How to deploy on AWS EC2 [Amazon Web Services](https://aws.amazon.com/) is a popular subsidiary of Amazon that provides on-demand cloud computing platforms on a metered pay-as-you-go basis. Access the AWS web console at [console.aws.amazon.com](https://console.aws.amazon.com/). @@ -11,7 +10,7 @@ sudo snap install juju ``` Follow the installation guides for: -* [AWs CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - the Amazon Web Services CLI +* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - the Amazon Web Services CLI To check they are all correctly installed, you can run the commands demonstrated below with sample outputs: @@ -71,7 +70,7 @@ to create a new model to deploy workloads. ``` [/details] -You can check the [AWS EC2 instance availability](https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1#Instances:instanceState=running) (ensure the right AWS region chosen!): +You can check the [AWS EC2 instance availability](https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1) (ensure the right AWS region chosen!): ![image|690x118](upload://putAO5NyHdaeWE6jXI8X1hZHTYv.png) Create a new Juju model: @@ -166,7 +165,7 @@ From here you can [use/scale/backup/restore/refresh](/tutorial/index) your newly ## Expose database (optional) -If necessary to access DB from outside of AWS (warning: [opening ports to public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications)) open the AWS firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: +If necessary to access DB from outside of AWS (warning:opening ports to public is risky) open the AWS firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: ```shell juju expose mysql ``` diff --git a/docs/how-to/deploy/azure.md b/docs/how-to/deploy/azure.md index dbc9f5c002..2e743f322b 100644 --- a/docs/how-to/deploy/azure.md +++ b/docs/how-to/deploy/azure.md @@ -140,7 +140,7 @@ Now you can run to create a new model to deploy workloads. ``` -You can check the [Azure instances availability](https://portal.azure.com/#browse/Microsoft.Compute%2FVirtualMachines): +You can check the [Azure instances availability](https://portal.azure.com/#browse/Microsoft.Compute/VirtualMachines): ![image|689x313](upload://bB5lCMIHtL1KToftKQVv7z86aoi.png) @@ -213,7 +213,7 @@ If it is necessary to access the database from outside of Azure, open the Azure ```shell juju expose mysql ``` -> Be wary that [opening ports to the public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications). +> Be wary that opening ports to the public is risky. Once exposed, you can connect your database using the same credentials as above. This time use the Azure VM public IP assigned to the MySQL instance. You can see this with `juju status`: ```shell diff --git a/docs/how-to/deploy/gce.md b/docs/how-to/deploy/gce.md index 87807645c6..0d284b28c4 100644 --- a/docs/how-to/deploy/gce.md +++ b/docs/how-to/deploy/gce.md @@ -196,7 +196,7 @@ From here you can [use/scale/backup/restore/refresh](/tutorial/index) your newly ## Expose database (optional) -To access the database from outside of GCloud (warning: [opening ports to public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications)) open the GCloud firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: +To access the database from outside of GCloud (warning: opening ports to public is risky) open the GCloud firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: ```shell juju expose mysql ``` diff --git a/docs/how-to/deploy/index.md b/docs/how-to/deploy/index.md index f259d535c4..957b3e087c 100644 --- a/docs/how-to/deploy/index.md +++ b/docs/how-to/deploy/index.md @@ -1,11 +1,17 @@ - # Deploy ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* +Sunbeam +LXD +MAAS +AWS EC2 +GCE +Azure +Multi-AZ +Air-gapped +Terraform +Juju spaces ``` diff --git a/docs/how-to/deploy/maas.md b/docs/how-to/deploy/maas.md index dd6d472677..8957d7b3a5 100644 --- a/docs/how-to/deploy/maas.md +++ b/docs/how-to/deploy/maas.md @@ -1,4 +1,3 @@ - # How to deploy on MAAS This guide aims to provide a quick start to deploying Charmed MySQL on MAAS. It summarizes the instructions from the [Build a MAAS and LXD environment with Multipass Tutorial](https://discourse.maas.io/t/5360) to set up and tear down a **playground environment**. @@ -108,7 +107,7 @@ Add the flags `--credential` if you registered several MAAS credentials, and `-- juju bootstrap --constraints tags=juju maas-cloud maas-controller ``` -# Deploy Charmed MySQL on MAAS +## Deploy Charmed MySQL on MAAS ```shell juju add-model mysql maas-cloud juju deploy mysql --channel 8.0/candidate # MAAS supported since charm revision 234+ @@ -128,7 +127,7 @@ Machine State Address Inst id Base AZ Message 1 started 10.10.10.7 pumped-racer ubuntu@22.04 default Deployed ``` -# Test your Charmed MySQL deployment +## Test your Charmed MySQL deployment Check the [Testing](/reference/software-testing) reference to test your deployment. diff --git a/docs/how-to/deploy/sunbeam.md b/docs/how-to/deploy/sunbeam.md index 7259365369..4a07a212db 100644 --- a/docs/how-to/deploy/sunbeam.md +++ b/docs/how-to/deploy/sunbeam.md @@ -75,7 +75,7 @@ The image below is an example of the OpenStack dashboard view (bastion + juju co [Tutorial]: /tutorial/index [Single-node guided]: https://microstack.run/docs/single-node-guided -[Accessing the OpenStack dashboard]: https://microstack.run/docs/dashboard -[Images Sync]: https://microstack.run/docs/images -[Manage workloads with Juju]: https://microstack.run/docs/juju-workloads +[Accessing the OpenStack dashboard]: https://canonical-openstack.readthedocs-hosted.com/en/latest/how-to/misc/using-the-openstack-dashboard/ +[Images Sync]: https://canonical-openstack.readthedocs-hosted.com/en/latest/how-to/features/images-sync/ +[Manage workloads with Juju]: https://canonical-openstack.readthedocs-hosted.com/en/latest/how-to/misc/manage-workloads-with-juju/ diff --git a/docs/how-to/development/index.md b/docs/how-to/development/index.md index e9328522a1..c13d3eceb0 100644 --- a/docs/how-to/development/index.md +++ b/docs/how-to/development/index.md @@ -1,12 +1,11 @@ - # Development ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* -*/index +Integrate with your charm +Migrate data via mysqldump +Migrate data via mydumper +Migrate data via backup/restore ``` diff --git a/docs/how-to/development/integrate-with-your-charm.md b/docs/how-to/development/integrate-with-your-charm.md index 70b7534dca..327b8ec25b 100644 --- a/docs/how-to/development/integrate-with-your-charm.md +++ b/docs/how-to/development/integrate-with-your-charm.md @@ -1,6 +1,3 @@ - -# Integrate with your charm - # How to integrate a database with your charm Charmed MySQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with MySQL. @@ -17,14 +14,14 @@ Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ ## Integrate your charm with MySQL > See also: -> * [Juju documentation | Integration](https://juju.is/docs/juju/integration) +> * [Juju documentation | Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/) > * [Juju documentation | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql) Refer to [mysql-test-app](https://github.com/canonical/mysql-test-app) as a practical example of implementing data-platform-libs interfaces to integrate a charm with Charmed MySQL. ## Troubleshooting and testing * To learn the basics of charm debugging, start with [Juju | How to debug a charm](https://juju.is/docs/sdk/debug-a-charm) -* To troubleshoot Charmed MySQL, see the [Troubleshooting](/how-to/development/troubleshooting/index) page. +* To troubleshoot Charmed MySQL, see the [Troubleshooting](/reference/troubleshooting/index) page. * To test the charm, check the [Testing](/reference/software-testing) reference ## FAQ diff --git a/docs/how-to/development/migrate-data-via-backup-restore.md b/docs/how-to/development/migrate-data-via-backup-restore.md index 88db84830e..311bd9f942 100644 --- a/docs/how-to/development/migrate-data-via-backup-restore.md +++ b/docs/how-to/development/migrate-data-via-backup-restore.md @@ -1,13 +1,14 @@ - # Migrate data via backup/restore -# DB data migration using ‘backup/restore’ - -> :information_source: **Tip**: use ['mysqldump' manual](/how-to/development/migrate-data-via-mysqldump) to migrate [legacy charms](/explanation/legacy-charm) data. +```{note} +Use ['mysqldump' manual](/how-to/development/migrate-data-via-mysqldump) to migrate [legacy charms](/explanation/legacy-charm) data. +``` This Charmed MySQL operator is able to restore [it's own backups](/how-to/back-up-and-restore/restore-a-backup) stored on [S3-compatible storage](/how-to/back-up-and-restore/configure-s3-aws). The same restore approach is applicable to restore [foreign backups](/how-to/back-up-and-restore/migrate-a-cluster) made by different Charmed MySQL installation or even another MySQL charms. The backup have to be created manually using Percona XtraBackup! -> :warning: Canonical Data team describes here the general approach and does NOT support nor guaranties the restoration results. Always test migration in LAB before performing it in Production! +```{warning} +Canonical Data team describes here the general approach and does NOT support nor guarantees the restoration results. Always test migration in a test environment before performing it in Production! +``` Before the data migration check all [limitations of the modern Charmed MySQL](/reference/system-requirements) charm! Please check [your application compatibility](/explanation/legacy-charm) with Charmed MySQL before migrating production data from legacy charm! @@ -22,5 +23,5 @@ The approach: * perform all the necessary tests to make sure your application accepted new DB. * schedule and perform the final production migration re-using the last steps above. -Do you have questions? [Contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in such a data migration! +Do you have questions? [Contact us](/reference/contacts) if you are interested in such a data migration! diff --git a/docs/how-to/development/migrate-data-via-mydumper.md b/docs/how-to/development/migrate-data-via-mydumper.md index 9ae758652d..d873170019 100644 --- a/docs/how-to/development/migrate-data-via-mydumper.md +++ b/docs/how-to/development/migrate-data-via-mydumper.md @@ -1,9 +1,8 @@ - # Migrate data via mydumper -# DB data migration using 'mydumper' - -> :information_source: **Tip**: use ['mysqldump' manual](/how-to/development/migrate-data-via-mysqldump) to migrate [legacy charms](/explanation/legacy-charm) data. +```{note} +Use ['mysqldump' manual](/how-to/development/migrate-data-via-mysqldump) to migrate [legacy charms](/explanation/legacy-charm) data. +``` The [mydumper](https://github.com/mydumper/mydumper) tool is a powerful MySQL logical data-migration tool, including: diff --git a/docs/how-to/development/migrate-data-via-mysqldump.md b/docs/how-to/development/migrate-data-via-mysqldump.md index 29f491dbc1..25659c078c 100644 --- a/docs/how-to/development/migrate-data-via-mysqldump.md +++ b/docs/how-to/development/migrate-data-via-mysqldump.md @@ -1,12 +1,3 @@ - -# Migrate data via mysqldump - -```{note} -**Note**: All commands are written for `juju >= v.3.0` - -For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). -``` - # Migrate database data via `mysqldump` This document describes database **data** migration only! @@ -36,8 +27,8 @@ The list of MariaDB/MySQL **legacy VM charms**: * [MariaDB](https://charmhub.io/mariadb) * [Percona Cluster](https://charmhub.io/percona-cluster) -* [MySQL Innodb Cluster](https://charmhub.io/mysql-innodb-cluster) -* [OSM MariaDB K8s](https://charmhub.io/charmed-osm-mariadb-k8s) (K8s flavour, use [separate manual](https://charmhub.io/mysql-k8s/docs/h-develop-mysqldump)) +* [MySQL InnoDB Cluster](https://charmhub.io/mysql-innodb-cluster) +* [OSM MariaDB K8s](https://charmhub.io/charmed-osm-mariadb-k8s) (K8s flavour, use [separate manual](https://charmhub.io/mysql-k8s/docs/h-migrate-mysqldump)) There is a minor difference in commands for each of the legacy charms, but the general logic is common: @@ -51,7 +42,9 @@ There is a minor difference in commands for each of the legacy charms, but the g Before the data migration check all [limitations of the modern Charmed MySQL](/reference/system-requirements) charm!
Please check [your application compatibility](/explanation/legacy-charm) with Charmed MySQL before migrating production data from legacy charm! -> :warning: Always perform the migration in a test environment before performing it in production! +```{warning} +Always perform the migration in a test environment before performing it in production! +``` ## Prerequisites @@ -61,7 +54,7 @@ Before the data migration check all [limitations of the modern Charmed MySQL](/r - `mysql-client` on client machine (install by running `sudo apt install mysql-client`). ```{caution} -Most legacy database charms support old Ubuntu series only, while Juju 3.x does [NOT support](https://discourse.charmhub.io/t/roadmap-releases/5064#juju-3-0-0---22-oct-2022) Ubuntu Bionic. +Most legacy database charms support old Ubuntu series only, while Juju 3.x does [NOT support](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022) Ubuntu Bionic. It is recommended to use the latest stable revision of the charm on Ubuntu Jammy and Juju 3.x ``` @@ -219,5 +212,3 @@ juju remove-application --destroy-storage < mariadb | percona-cluster | mysql-in Database data migration is also possible using [`mydumper`](/how-to/development/migrate-data-via-mydumper). -> :tipping_hand_man: This manual based on [Kubeflow DB migration guide](https://github.com/canonical/bundle-kubeflow/blob/main/docs/db-migration-guide.md). - diff --git a/docs/how-to/enable-tls.md b/docs/how-to/enable-tls.md index 609b3b0255..4ab92bc018 100644 --- a/docs/how-to/enable-tls.md +++ b/docs/how-to/enable-tls.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.1` -If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` This guide will show how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example. diff --git a/docs/how-to/external-network-access.md b/docs/how-to/external-network-access.md index ab24c1f1e2..388a73ff53 100644 --- a/docs/how-to/external-network-access.md +++ b/docs/how-to/external-network-access.md @@ -3,13 +3,13 @@ ## External application (non-Juju) -[u]Use case[/u]: the client application is a non-Juju application outside of Juju / DB LAN. +Use case: the client application is a non-Juju application outside of Juju / DB LAN. There are many possible ways to connect the Charmed MySQL database from outside of the LAN the DB cluster is located. The available options are heavily depend on the cloud/hardware/virtualization in use. One of the possible options is to use [virtual IP addresses (VIP)](https://en.wikipedia.org/wiki/Virtual_IP_address) which the charm MySQL Router provides with assist of the charm/interface `hacluster`. Please follow the [MySQL Router documentation](https://charmhub.io/mysql-router/docs/h-external-access?channel=dpe/candidate) for such configuration. ## External relation (Juju) -[u]Use case[/u]: the client application is a Juju application outside of DB deployment (e.g. hybrid Juju deployment with different VM clouds/controllers). +Use case: the client application is a Juju application outside of DB deployment (e.g. hybrid Juju deployment with different VM clouds/controllers). In this case the the cross-controllers-relation is necessary. Please [contact](/reference/contacts) Data team to discuss the possible option for your use case. diff --git a/docs/how-to/index.md b/docs/how-to/index.md index f06018e448..b9a157f448 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -4,110 +4,78 @@ Key processes and common tasks for managing and using Charmed MySQL on machines. ## Deployment and setup -Guidance for different cloud services: -* [Sunbeam] -* [LXD] -* [MAAS] -* [AWS EC2] -* [GCE] -* [Azure] -* [Multi-AZ] +Guidance for different cloud services and special deployments. -Specific deployment scenarios and architectures: +```{toctree} +:titlesonly: +:maxdepth: 2 -* [Terraform] -* [Air-gapped] +Deploy +``` ## Usage and maintenance -* [Integrate with another application] -* [External network access] -* [Scale replicas] -* [Enable TLS] + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Integrate with another application +Scale replicas +Enable TLS +External network access +``` ## Back up and restore -* [Configure S3 AWS] -* [Configure S3 RadosGW] -* [Create a backup] -* [Restore a backup] -* [Migrate a cluster] + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Back up and restore +``` ## Monitoring (COS) -* [Enable monitoring] -* [Enable alert rules] -* [Enable tracing] + +Integrate with observability services like Grafana, Prometheus, and Tempo. + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Monitoring (COS) +``` ## Upgrades -See the [Upgrades landing page] for more details. -* [Upgrade Juju] -* [Perform a minor upgrade] -* [Perform a minor rollback] + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Upgrade +``` ## Cross-regional (cluster-cluster) async replication -* [Deploy] -* [Clients] -* [Switchover / Failover] -* [Recovery] -* [Removal] + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Cross-regional async replication +``` ## Development -* [Integrate with your charm] -* [Migrate data via mysqldump] -* [Migrate data via mydumper] -* [Migrate data via backup/restore] -* [Troubleshooting] - - - - -[Sunbeam]: /how-to/deploy/sunbeam -[LXD]: /how-to/deploy/lxd -[MAAS]: /how-to/deploy/maas -[AWS EC2]: /how-to/deploy/aws-ec2 -[GCE]: /how-to/deploy/gce -[Azure]: /how-to/deploy/azure -[Multi-AZ]: /how-to/deploy/multi-az -[Terraform]: /how-to/deploy/terraform -[Air-gapped]: /how-to/deploy/air-gapped - -[Integrate with another application]: /how-to/integrate-with-another-application -[External network access]: /how-to/external-network-access -[Scale replicas]: /how-to/scale-replicas -[Enable TLS]: /how-to/enable-tls - -[Configure S3 AWS]: /how-to/back-up-and-restore/configure-s3-aws -[Configure S3 RadosGW]: /how-to/back-up-and-restore/configure-s3-radosgw -[Create a backup]: /how-to/back-up-and-restore/create-a-backup -[Restore a backup]: /how-to/back-up-and-restore/restore-a-backup -[Migrate a cluster]: /how-to/back-up-and-restore/migrate-a-cluster - -[Enable monitoring]: /how-to/monitoring-cos/enable-monitoring -[Enable alert rules]: /how-to/monitoring-cos/enable-alert-rules -[Enable tracing]: /how-to/monitoring-cos/enable-tracing - -[Upgrades landing page]: /how-to/upgrade/index -[Upgrade Juju]: /how-to/upgrade/upgrade-juju -[Perform a minor upgrade]: /how-to/upgrade/perform-a-minor-upgrade -[Perform a minor rollback]: /how-to/upgrade/perform-a-minor-rollback - -[Integrate with your charm]: /how-to/development/integrate-with-your-charm -[Migrate data via mysqldump]: /how-to/development/migrate-data-via-mysqldump -[Migrate data via mydumper]: /how-to/development/migrate-data-via-mydumper -[Migrate data via backup/restore]: /how-to/development/migrate-data-via-backup-restore -[Troubleshooting]: /how-to/development/troubleshooting/index - -[Deploy]: /how-to/cross-regional-async-replication/deploy -[Clients]: /how-to/cross-regional-async-replication/clients -[Switchover / Failover]: /how-to/cross-regional-async-replication/switchover-failover -[Recovery]: /how-to/cross-regional-async-replication/recovery -[Removal]: /how-to/cross-regional-async-replication/removal +```{toctree} +:titlesonly: +:maxdepth: 2 + +Development +``` ```{toctree} :titlesonly: :maxdepth: 2 -:glob: :hidden: -* -*/index -``` +Contribute +``` \ No newline at end of file diff --git a/docs/how-to/integrate-with-another-application.md b/docs/how-to/integrate-with-another-application.md index 4255a2d6c6..1c0ee59ee9 100644 --- a/docs/how-to/integrate-with-another-application.md +++ b/docs/how-to/integrate-with-another-application.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` # How to integrate with another application diff --git a/docs/how-to/monitoring-cos/enable-alert-rules.md b/docs/how-to/monitoring-cos/enable-alert-rules.md index 78669c6183..cfc573fbf0 100644 --- a/docs/how-to/monitoring-cos/enable-alert-rules.md +++ b/docs/how-to/monitoring-cos/enable-alert-rules.md @@ -1,7 +1,4 @@ - -# Enable alert rules - -# How to enable COS Alert Rules +# How to enable Alert Rules This guide will show how to set up [Pushover](https://pushover.net/) to receive alert notifications from the COS Alert Manager with [Awesome Alert Rules](https://samber.github.io/awesome-prometheus-alerts/). diff --git a/docs/how-to/monitoring-cos/enable-monitoring.md b/docs/how-to/monitoring-cos/enable-monitoring.md index 688d4769d9..26a39a3f3c 100644 --- a/docs/how-to/monitoring-cos/enable-monitoring.md +++ b/docs/how-to/monitoring-cos/enable-monitoring.md @@ -1,12 +1,3 @@ - -# Enable monitoring - -```{note} -**Note**: All commands are written for `juju >= v.3.0` - -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). -``` - # How to enable monitoring (COS) This guide will show you how to deploy and configure the [COS Lite bundle](https://charmhub.io/cos-lite) to monitor your deployment with Grafana. diff --git a/docs/how-to/monitoring-cos/enable-tracing.md b/docs/how-to/monitoring-cos/enable-tracing.md index 9ac0840448..c9d4c0e1ef 100644 --- a/docs/how-to/monitoring-cos/enable-tracing.md +++ b/docs/how-to/monitoring-cos/enable-tracing.md @@ -1,14 +1,7 @@ - # Enable tracing -```{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#juju-3-0-0---22-oct-2022). -``` This guide contains the steps to enable tracing with [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for your MySQL application. - ```{caution} **Warning:** This is feature is in development. It is **not recommended** for production environments. @@ -33,12 +26,12 @@ juju switch : ``` Then, deploy the dependencies of Tempo following [this tutorial](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). In particular, we would want to: -- Deploy the minio charm +- Deploy the MinIO charm - Deploy the s3 integrator charm -- Add a bucket in minio using a python script -- Configure s3 integrator with the minio credentials +- Add a bucket in MinIO using a python script +- Configure s3 integrator with the MinIO credentials -Finally, deploy and integrate with Tempo HA in [a monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489#deploy-monolithic-setup). +Finally, deploy and integrate with Tempo HA in [a monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). ## Offer interfaces diff --git a/docs/how-to/monitoring-cos/index.md b/docs/how-to/monitoring-cos/index.md index 497bfe940f..6e8747775e 100644 --- a/docs/how-to/monitoring-cos/index.md +++ b/docs/how-to/monitoring-cos/index.md @@ -1,11 +1,10 @@ - -# Monitoring-Cos +# Monitoring (COS) ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* +Enable monitoring +Enable alert rules +Enable tracing ``` diff --git a/docs/how-to/scale-replicas.md b/docs/how-to/scale-replicas.md index 464ae5f15e..07766de1cb 100644 --- a/docs/how-to/scale-replicas.md +++ b/docs/how-to/scale-replicas.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` Replication in MySQL is the process of creating copies of the stored data. This provides redundancy, which means the application can provide self-healing capabilities in case one replica fails. In this context, each replica is equivalent to one juju unit. @@ -33,7 +33,7 @@ juju run mysql/leader get-primary Similarly, the primary replica is displayed as a status message in `juju status`. However, one should note that this hook gets called on regular time intervals and the primary may be outdated if the status hook has not been called recently. ```{note} -**We highly suggest configuring the `update-status` hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the [status hook](https://juju.is/docs/sdk/update-status-event) performs self-healing in the case of a network cut. +**We highly suggest configuring the `update-status` hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the [status hook](https://documentation.ubuntu.com/juju/3.6/reference/hook/#update-status) performs self-healing in the case of a network cut. To change the frequency of the `update-status` hook, run ```shell diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md index cf3560e574..fdda0f1b04 100644 --- a/docs/how-to/upgrade/index.md +++ b/docs/how-to/upgrade/index.md @@ -25,12 +25,12 @@ New revisions of the charm may require that you do a major or minor Juju upgrade See the guide: [How to upgrade Juju](/how-to/upgrade/upgrade-juju) - ```{toctree} :titlesonly: :maxdepth: 2 -:glob: :hidden: -* +Upgrade Juju +Perform a minor rollback +Perform a minor upgrade ``` diff --git a/docs/how-to/upgrade/perform-a-minor-rollback.md b/docs/how-to/upgrade/perform-a-minor-rollback.md index cbafc9fc45..0da5c1a624 100644 --- a/docs/how-to/upgrade/perform-a-minor-rollback.md +++ b/docs/how-to/upgrade/perform-a-minor-rollback.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` **Example**: MySQL 8.0.34 -> MySQL 8.0.33
(including charm revision bump: e.g Revision 43 -> Revision 42) diff --git a/docs/how-to/upgrade/perform-a-minor-upgrade.md b/docs/how-to/upgrade/perform-a-minor-upgrade.md index b8a1d35179..0bab7be98b 100644 --- a/docs/how-to/upgrade/perform-a-minor-upgrade.md +++ b/docs/how-to/upgrade/perform-a-minor-upgrade.md @@ -4,7 +4,7 @@ ```{note} **Note**: All commands are written for `juju >= v.3.0` -If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022). +If you are using an earlier version, check the [Juju 3.0 Release Notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). ``` # Perform a minor upgrade diff --git a/docs/index.md b/docs/index.md index 97e642ddbc..9454ae6ab6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ This is a **IAAS/VM** operator. To deploy on Kubernetes, see [Charmed MySQL K8s] Charmed MySQL is an official distribution of MySQL. 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://charmhub.io/tag/mysql) +- [Join the Discourse forum](https://discourse.charmhub.io/tag/mysql) - [Contribute](https://github.com/canonical/mysql-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/mysql-operator/issues/new/choose) - Explore [Canonical Data Fabric solutions](https://canonical.com/data) - [Contacts us](/reference/contacts) for all further questions diff --git a/docs/reference/alert-rules.md b/docs/reference/alert-rules.md index 6300dca07a..f64154135d 100644 --- a/docs/reference/alert-rules.md +++ b/docs/reference/alert-rules.md @@ -14,7 +14,7 @@ This page contains a markdown version of the alert rules described in the `mysql | MySQLHighThreadsRunning | ![warning] | MySQL instance is actively using > 80% of `max_connections`.
Consider reviewing the value of the `max-connections` config parameter or allocate more resources to your database server. | | MySQLHighPreparedStatementsUtilization(>80%) | ![warning] | MySQL instance is using > 80% of `max_prepared_stmt_count`.
Too many prepared statements might consume a lot of memory. | | MySQLSlowQueries | ![info] | MySQL instance has a slow query.
Consider optimizing the query by reviewing its execution plan, then rewrite the query and add any relevant indexes. | -| MySQLInnoDBLogWaits | ![warning] | MySQL instance has long InnoDB log waits.
MySQL InnoDB log writes might be stalling. Check I/O activity on your nodes to find the responsible process or query. Consider using iotop and the performance_schema. | +| MySQLInnoDBLogWaits | ![warning] | MySQL instance has long InnoDB log waits.
MySQL InnoDB log writes might be stalling. Check I/O activity on your nodes to find the responsible process or query. Consider using `iotop` and the `performance_schema`. | | MySQLRestarted | ![info] | MySQL instance restarted.
MySQL restarted less than one minute ago. If the restart was unplanned or frequent, check Loki logs (e.g. `error.log`). | diff --git a/docs/reference/charm-statuses.md b/docs/reference/charm-statuses.md index ced0e6df3c..fff40863fe 100644 --- a/docs/reference/charm-statuses.md +++ b/docs/reference/charm-statuses.md @@ -1,10 +1,10 @@ # Charm statuses ```{caution} -This 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. +This is an work-in-progress article. Do **not** use it in production! Contact [Canonical Data Platform team](/reference/contacts) if you are interested in the topic. ``` -The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#application-status). Here you can find the expected end-users reaction on different statuses: +The charm follows [standard Juju applications statuses](https://documentation.ubuntu.com/juju/3.6/reference/status/#application-status). Here you can find the expected end-users reaction on different statuses: | Juju Status | Message | Expectations | Actions | |-------|-------|-------|-------| @@ -13,18 +13,18 @@ The charm follows [standard Juju applications statuses](https://juju.is/docs/olm | **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration) | No actions required | | **blocked** | any | The manual user activity is required! | Follow the message hints (see below) | | **blocked** | Failed to set up relation | The relation between two applications failed to be created. Most probably it is a regression of the recent changes in applications | Check Juju [debug-log](https://juju.is/docs/olm/juju-debug-log). Increase debug level and reproduce the issue. Report as an issue with debug logs attached (if reproducible). Consider to try previous revision for both applications | -| **blocked** | Failed to initialize mysql relation | The same as "Failed to set up relation" | See "Failed to set up relation" | +| **blocked** | Failed to initialize MySQL relation | The same as "Failed to set up relation" | See "Failed to set up relation" | | **blocked** | Failed to remove relation user | TODO: clean manually? How to unblock? | | | **blocked** | Failed to install and configure MySQL | TODO | | | **blocked** | Failed to initialize MySQL users | TODO | | | **blocked** | Failed to configure instance for InnoDB | TODO | | -| **blocked** | Failed to create custom mysqld config | TODO | | +| **blocked** | Failed to create custom `mysqld` config | TODO | | | **blocked** | Failed to connect to MySQL exporter | TODO | | | **blocked** | Failed to create the InnoDB cluster | TODO | | | **blocked** | Failed to initialize juju units operations table | TODO | | | **blocked** | failed to recover cluster. | TODO | | | **blocked** | Failed to remove relation user | TODO | | -| **blocked** | Failed to initialize shared_db relation | Try to remove and add relations. Report as an issue (with debug logs) if reproducible | | +| **blocked** | Failed to initialize `shared_db` relation | Try to remove and add relations. Report as an issue (with debug logs) if reproducible | | | **blocked** | Failed to create app user or scoped database | TODO | | | **blocked** | Failed to delete users for departing unit | TODO | | | **blocked** | Failed to set TLS configuration | Problems with TLS certifications generation| Remove and add relations with TLS operator. Report as an issue (with debug logs) if reproducible | @@ -35,7 +35,7 @@ The charm follows [standard Juju applications statuses](https://juju.is/docs/olm | **blocked** | Failed to re-configure instance for InnoDB | TODO | | | **blocked** | Failed to purge data dir | TODO | | | **blocked** | Failed to reset root password | TODO | | -| **blocked** | Failed to create custom mysqld config | TODO | | +| **blocked** | Failed to create custom `mysqld` config | TODO | | | **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: K8s charm termination in progress. | Manual investigation required if status is permanent | diff --git a/docs/reference/contacts.md b/docs/reference/contacts.md index 1143c03852..aa41c1039f 100644 --- a/docs/reference/contacts.md +++ b/docs/reference/contacts.md @@ -2,14 +2,11 @@ Charmed MySQL 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-operator/issues/new/choose) -* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File) +* Report security issues through [**Launchpad**](https://launchpad.net/mysql) * 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. -``` - ## Useful links + * [Canonical Data Fabric](https://ubuntu.com/data/) * [Charmed MySQL](https://charmhub.io/mysql) * [Git sources for Charmed MySQL](https://github.com/canonical/mysql-operator) diff --git a/docs/reference/index.md b/docs/reference/index.md index a3c585f928..b840675ac2 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -3,17 +3,20 @@ Technical specifications, APIs, release notes, and other reference material for fast lookup. -| Page | Description | -|-------------------------|-------------------------------------------------| -| [Releases](/reference/releases) | Overview of all Charmed MySQL releases | -| [System requirements](/reference/system-requirements) | Software and hardware requirements | -| [Software testing](/reference/software-testing) | Software tests performed on this charm | -| [Profiles](/reference/profiles) | Configurations related to performance | -| [Plugins/extensions](/reference/plugins-extensions) | Supported plugins/extensions | -| [Alert rules](/reference/alert-rules) | Pre-configured Prometheus alert rules | -| [Charm statuses](/reference/charm-statuses) | Juju application statuses | -| [Contacts](/reference/contacts) | Contact information | +```{toctree} +:titlesonly: +:maxdepth: 2 +Releases +System requirements +Profiles +Plugins/extensions +Alert rules +Charm statuses +Software testing +Troubleshooting +Contacts +``` In the tabs at the top of this charm's [CharmHub page](https://charmhub.io/mysql/), you will find the following automatically generated references: @@ -24,11 +27,3 @@ In the tabs at the top of this charm's [CharmHub page](https://charmhub.io/mysql | [Actions](https://charmhub.io/mysql/actions) | Juju actions supported by this charm | -```{toctree} -:titlesonly: -:maxdepth: 2 -:glob: -:hidden: - -* -``` diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md index a0a962f12c..9b1a9a773d 100644 --- a/docs/reference/profiles.md +++ b/docs/reference/profiles.md @@ -12,12 +12,12 @@ juju deploy mysql --config profile=testing |Value|Description|Tech details| | --- | --- | ----- | -|`production`
(default)|[Maximum performance](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L766-L775)| ~75% of [unit memory](https://juju.is/docs/juju/unit) granted for MySQL
max_connections=[RAM/12MiB](https://github.com/canonical/mysql-operator/blob/53e54745f47b6d2184c54386ee984792cb939152/lib/charms/mysql/v0/mysql.py#L2092) (max safe value)| -|`testing`|[Minimal resource usage](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L759-L764)| innodb_buffer_pool_size = 20MB
innodb_buffer_pool_chunk_size=1MB
group_replication_message_cache_size=128MB
max_connections=100
performance-schema-instrument='memory/%=OFF' | +|`production`
(default)|[Maximum performance]| ~75% of [unit] memory granted for MySQL
`max_connections`= [RAM / 12MiB] (max safe value)| +|`testing`|[Minimal resource usage]| `innodb_buffer_pool_size` = 20MB
`innodb_buffer_pool_chunk_size`=1MB
`group_replication_message_cache_size`=128MB
`max_connections`=100
`performance-schema-instrument`='memory/%=OFF' | ## Config change -> :warning: **Note**: Pre-deployed application profile change is [planned](https://warthogs.atlassian.net/browse/DPE-2404) but currently is NOT supported. +> **Note**: Pre-deployed application profile change is [planned](https://warthogs.atlassian.net/browse/DPE-2404) but currently is NOT supported. To change the profile, use `juju config` ([see all charm configs](https://charmhub.io/mysql/configure#profile)): ```shell @@ -39,3 +39,12 @@ Juju constraints can be used together with charm profile: juju deploy mysql --constraints cores=8 mem=16G --config profile=testing ``` + + +[Maximum performance]: https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L766-L775 + +[unit]: https://juju.is/docs/juju/unit + +[RAM / 12MiB]: https://github.com/canonical/mysql-operator/blob/53e54745f47b6d2184c54386ee984792cb939152/lib/charms/mysql/v0/mysql.py#L2092 + +[Minimal resource usage]: https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L759-L764 diff --git a/docs/reference/releases.md b/docs/reference/releases.md index 64cd0bb684..d1e676789d 100644 --- a/docs/reference/releases.md +++ b/docs/reference/releases.md @@ -2,7 +2,7 @@ This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release. -To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://juju.is/docs/juju/channel#risk). +To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk). To see all releases and commits, check the [Charmed MySQL Releases page on GitHub](https://github.com/canonical/mysql-operator/releases). @@ -28,7 +28,7 @@ For a given release, this table shows: For more details about each feature/interface, refer to the documentation linked in the column headers. ## Architecture and base -Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions. +Several [revisions](https://documentation.ubuntu.com/juju/3.6/reference/charm/#charm-revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions. > If you do not specify a revision on deploy time, Juju will automatically choose the revision that matches your base and architecture. diff --git a/docs/reference/software-testing.md b/docs/reference/software-testing.md index 597eecd398..2c06ffdde1 100644 --- a/docs/reference/software-testing.md +++ b/docs/reference/software-testing.md @@ -1,7 +1,5 @@ # Charm testing reference -> **:information_source: Hint**: Use [Juju 3](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022). Otherwise replace `juju run ...` with `juju run-action --wait ...` for Juju 2.9. - There are [a lot of test types](https://en.wikipedia.org/wiki/Software_testing) available and most of them are well applicable for Charmed MySQL. Here is a list prepared by Canonical: * Smoke test @@ -12,9 +10,9 @@ There are [a lot of test types](https://en.wikipedia.org/wiki/Software_testing) ## Smoke test -[u]Complexity[/u]: trivial
-[u]Speed[/u]: fast
-[u]Goal[/u]: ensure basic functionality works over short amount of time. +Complexity: trivial +Speed: fast +Goal: ensure basic functionality works over short amount of time. [Setup an Juju 3.x environment](/tutorial/1-set-up-the-environment), deploy DB with test application and start "continuous write" test: ```shell @@ -36,12 +34,12 @@ watch -n1 -x juju ssh mysql/leader "mysql -h 127.0.0.1 -uroot -p${password} -e \ # Watch the counter is growing! ``` -[u]Expected results[/u]: +Expected results: * 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]: +Hints: ```shell # Stop "continuous write" test juju run mysql-test-app/leader stop-continuous-writes diff --git a/docs/how-to/development/troubleshooting/index.md b/docs/reference/troubleshooting/index.md similarity index 90% rename from docs/how-to/development/troubleshooting/index.md rename to docs/reference/troubleshooting/index.md index 7b93a22b97..d000c6e689 100644 --- a/docs/how-to/development/troubleshooting/index.md +++ b/docs/reference/troubleshooting/index.md @@ -1,11 +1,10 @@ - -# Troubleshooting - # Troubleshooting -> :warning: **WARNING**: at the moment, there is NO ability to [pause operator](https://warthogs.atlassian.net/browse/DPE-2545)!
Make sure your activity will not interfere with the operator itself! +```{warning} +At the moment, there is NO ability to [pause operator](https://warthogs.atlassian.net/browse/DPE-2545)!
Make sure your activity will not interfere with the operator itself! +``` -Ensure you went into the real issue which requires the manual activity. Run `juju status` and check the [list of charm statuses](/reference/charm-statuses) and recommended activities there. +Ensure you went into the real issue, which requires manual activity. Run `juju status` and check the [list of charm statuses](/reference/charm-statuses) and recommended activities there. ## Logs @@ -129,7 +128,9 @@ username: root ``` Continue troubleshooting your DB/SQL related issues from here. -> :warning: **WARNING**: please do NOT manage users, credentials, databases, schema directly to avoid a split bran situation with the operator and/or related (integrated) applications. +```{warning} +Please do NOT manage users, credentials, databases, schema directly to avoid a split bran situation with the operator and/or related (integrated) applications. +``` It is NOT recommended to restart services directly as it might create a split brain situation with operator internal state. If you see the problem with a unit, consider to [remove failing unit and add-new-unit](/tutorial/3-scale-replicas) to recover the cluster state. @@ -138,7 +139,9 @@ Also, feel free to improve this document! ## Installing extra software: -> :warning: **WARNING**: please do NOT install any additionally software as it may affect the stability and produce anomalies which is hard to troubleshoot and fix! Otherwise always remove manually installed components at the end of troubleshooting. Keep the house clean! +```{warning} +Please do NOT install any additionally software as it may affect the stability and produce anomalies which is hard to troubleshoot and fix! Otherwise always remove manually installed components at the end of troubleshooting. Keep the house clean! +``` Sometimes it is necessary to install some extra troubleshooting software. Use the common approach: ```shell @@ -152,8 +155,6 @@ ubuntu@juju-6692b6-0:~$ ```{toctree} :titlesonly: :maxdepth: 2 -:glob: -:hidden: -* +SoS report ``` diff --git a/docs/how-to/development/troubleshooting/sos-report.md b/docs/reference/troubleshooting/sos-report.md similarity index 100% rename from docs/how-to/development/troubleshooting/sos-report.md rename to docs/reference/troubleshooting/sos-report.md diff --git a/docs/tutorial/2-deploy-mysql.md b/docs/tutorial/2-deploy-mysql.md index 3d6e9f6f60..646d3ddfc6 100644 --- a/docs/tutorial/2-deploy-mysql.md +++ b/docs/tutorial/2-deploy-mysql.md @@ -29,7 +29,7 @@ Machine State Address Inst id Base AZ Message > To exit the screen with `juju status --watch 1s`, enter `Ctrl+C`. -You can also watch juju logs with the [`juju debug-log`](https://juju.is/docs/juju/juju-debug-log) command. More info on logging in the [juju logs documentation](https://juju.is/docs/olm/juju-logs). +You can also watch juju logs with the [`juju debug-log`](https://juju.is/docs/juju/juju-debug-log) command. More info on logging in the [juju logs documentation](https://documentation.ubuntu.com/juju/3.6/reference/log/#log). ## Access MySQL ```{caution} diff --git a/docs/tutorial/5-integrate-applications.md b/docs/tutorial/5-integrate-applications.md index bf92814403..be8754af4a 100644 --- a/docs/tutorial/5-integrate-applications.md +++ b/docs/tutorial/5-integrate-applications.md @@ -1,6 +1,6 @@ # Integrate with other applications -[Integrations](https://juju.is/docs/sdk/integration), known as "relations" in Juju 2.9, are the easiest way to create a user for a Charmed MySQL application. +[Integrations](https://documentation.ubuntu.com/juju/3.6/reference/relation/), known as "relations" in Juju 2.9, are the easiest way to create a user for a Charmed MySQL application. Integrations automatically create a username, password, and database for the desired user/application. As mentioned in the [earlier section about accessing MySQL](/tutorial/2-deploy-mysql), it is better practice to connect to MySQL via a specific user instead of the `root` user. diff --git a/docs/tutorial/7-clean-up-the-environment.md b/docs/tutorial/7-clean-up-the-environment.md index f8e0dc1e5e..5bc77a85df 100644 --- a/docs/tutorial/7-clean-up-the-environment.md +++ b/docs/tutorial/7-clean-up-the-environment.md @@ -30,6 +30,6 @@ multipass delete --purge my-vm - Check out our Charmed offerings of [PostgreSQL](https://charmhub.io/postgresql?channel=14) and [Kafka](https://charmhub.io/kafka?channel=edge). - Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability) - [Report](https://github.com/canonical/mysql-operator/issues) any problems you encountered. -- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform). +- [Give us your feedback](/reference/contacts). - [Contribute to the code base](https://github.com/canonical/mysql-operator)