Skip to content

Commit 9c019c2

Browse files
github-actions[bot]github-actions[bot]
authored
Sync docs from Discourse (#637)
Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
1 parent ed70aa0 commit 9c019c2

File tree

6 files changed

+293
-18
lines changed

6 files changed

+293
-18
lines changed

‎docs/explanation.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Explanation
2+
3+
Additional context about key concepts behind the MySQL charm.
4+
5+
## Core concepts and design
6+
* [Architecture]
7+
* [Interfaces and endpoints]
8+
* [Juju]
9+
* [Legacy charm]
10+
11+
## Operational concepts
12+
* [Users]
13+
* [Logs]
14+
* [Audit logs]
15+
16+
## Security and hardening
17+
* [Security hardening guide][Security]
18+
* [Cryptography]
19+
20+
<!-- Links -->
21+
22+
[Architecture]: /t/11756
23+
[Interfaces and endpoints]: /t/10250
24+
[Juju]: /t/11959
25+
[Legacy charm]: /t/10788
26+
27+
[Users]: /t/10789
28+
[Logs]: /t/11993
29+
[Audit logs]: /t/15424
30+
31+
[Security]: /t/16784
32+
[Cryptography]: /t/16785

‎docs/how-to.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# How-to guides
2+
3+
Key processes and common tasks for managing and using Charmed MySQL on machines.
4+
5+
## Deployment and setup
6+
7+
Guidance for different cloud services:
8+
* [Sunbeam]
9+
* [LXD]
10+
* [MAAS]
11+
* [AWS EC2]
12+
* [GCE]
13+
* [Azure]
14+
* [Multi-AZ]
15+
16+
Specific deployment scenarios and architectures:
17+
18+
* [Terraform]
19+
* [Air-gapped]
20+
21+
## Usage and maintenance
22+
* [Integrate with another application]
23+
* [External network access]
24+
* [Scale replicas]
25+
* [Enable TLS]
26+
27+
## Back up and restore
28+
* [Configure S3 AWS]
29+
* [Configure S3 RadosGW]
30+
* [Create a backup]
31+
* [Restore a backup]
32+
* [Migrate a cluster]
33+
34+
## Monitoring (COS)
35+
* [Enable monitoring]
36+
* [Enable alert rules]
37+
* [Enable tracing]
38+
39+
## Upgrades
40+
See the [Upgrades landing page] for more details.
41+
* [Upgrade Juju]
42+
* [Perform a minor upgrade]
43+
* [Perform a minor rollback]
44+
45+
## Cross-regional (cluster-cluster) async replication
46+
* [Deploy]
47+
* [Clients]
48+
* [Switchover / Failover]
49+
* [Recovery]
50+
* [Removal]
51+
52+
## Development
53+
* [Integrate with your charm]
54+
* [Migrate data via mysqldump]
55+
* [Migrate data via mydumper]
56+
* [Migrate data via backup/restore]
57+
* [Troubleshooting]
58+
59+
60+
<!--Links-->
61+
62+
[Sunbeam]: /t/15986
63+
[LXD]: /t/11870
64+
[MAAS]: /t/13900
65+
[AWS EC2]: /t/15718
66+
[GCE]: /t/15723
67+
[Azure]: /t/15859
68+
[Multi-AZ]: /t/15823
69+
[Terraform]: /t/14925
70+
[Air-gapped]: /t/15747
71+
72+
[Integrate with another application]: /t/9902
73+
[External network access]: /t/15801
74+
[Scale replicas]: /t/9904
75+
[Enable TLS]: /t/9898
76+
77+
[Configure S3 AWS]: /t/9894
78+
[Configure S3 RadosGW]: /t/10318
79+
[Create a backup]: /t/9896
80+
[Restore a backup]: /t/9908
81+
[Migrate a cluster]: /t/9906
82+
83+
[Enable monitoring]: /t/9900
84+
[Enable alert rules]: /t/15486
85+
[Enable tracing]: /t/14350
86+
87+
[Upgrades landing page]: /t/11745
88+
[Upgrade Juju]: /t/14325
89+
[Perform a minor upgrade]: /t/11748
90+
[Perform a minor rollback]: /t/11749
91+
92+
[Integrate with your charm]: /t/11890
93+
[Migrate data via mysqldump]: /t/11958
94+
[Migrate data via mydumper]: /t/11988
95+
[Migrate data via backup/restore]: /t/12008
96+
[Troubleshooting]: /t/11891
97+
98+
[Deploy]: /t/14169
99+
[Clients]: /t/14170
100+
[Switchover / Failover]: /t/14171
101+
[Recovery]: /t/14172
102+
[Removal]: /t/14174

‎docs/overview.md

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -34,16 +34,15 @@ Charmed MySQL is an official distribution of MySQL. It’s an open-source projec
3434

3535
| Level | Path | Navlink |
3636
|---------|---------|-------------|
37-
| 1 | tutorial | [Tutorial]() |
38-
| 2 | t-overview | [Overview](/t/9922) |
37+
| 1 | tutorial | [Tutorial](/t/9922) |
3938
| 2 | t-set-up | [1. Set up the environment](/t/9924) |
4039
| 2 | t-deploy | [2. Deploy MySQL](/t/9912) |
4140
| 2 | t-scale | [3. Scale replicas](/t/9920) |
4241
| 2 | t-manage-passwords | [4. Manage passwords](/t/9918) |
4342
| 2 | t-integrate | [5. Integrate applications](/t/9916) |
4443
| 2 | t-enable-tls | [6. Enable TLS encryption](/t/9914) |
4544
| 2 | t-clean-up | [7. Clean up the environment](/t/9910) |
46-
| 1 | how-to | [How To]() |
45+
| 1 | how-to | [How-to guides](/t/17233) |
4746
| 2 | h-setup | [Deploy]() |
4847
| 3 | h-deploy-sunbeam | [Sunbeam](/t/15986) |
4948
| 3 | h-deploy-lxd | [LXD](/t/11870) |
@@ -55,7 +54,7 @@ Charmed MySQL is an official distribution of MySQL. It’s an open-source projec
5554
| 3 | h-deploy-terraform | [Terraform](/t/14925) |
5655
| 3 | h-deploy-airgapped | [Air-gapped](/t/15747) |
5756
| 2 | h-integrate| [Integrate with another application](/t/9902) |
58-
| 2 | h-external-access | [External access](/t/15801) |
57+
| 2 | h-external-access | [External network access](/t/15801) |
5958
| 2 | h-scale | [Scale replicas](/t/9904) |
6059
| 2 | h-enable-tls | [Enable TLS](/t/9898) |
6160
| 2 | h-backups | [Back up and restore]() |
@@ -72,38 +71,39 @@ Charmed MySQL is an official distribution of MySQL. It’s an open-source projec
7271
| 3 | h-upgrade-juju | [Upgrade Juju](/t/14325) |
7372
| 3 | h-upgrade-minor | [Perform a minor upgrade](/t/11748) |
7473
| 3 | h-rollback-minor | [Perform a minor rollback](/t/11749) |
75-
| 2 | h-development| [Development]() |
76-
| 3 | h-development-integrate | [Integrate awith your charm](/t/11890) |
77-
| 3 | h-migrate-mysqldump | [Migrate data via mysqldump](/t/11958) |
78-
| 3 | h-migrate-mydumper | [Migrate data via mydumper](/t/11988) |
79-
| 3 | h-migrate-backup-restore | [Migrate data via backup/restore](/t/12008) |
80-
| 3 | h-troubleshooting | [Troubleshooting](/t/11891) |
8174
| 2 | h-async | [Cross-regional async replication]() |
8275
| 3 | h-async-deployment | [Deploy](/t/14169) |
8376
| 3 | h-async-clients | [Clients](/t/14170) |
8477
| 3 | h-async-failover | [Switchover / Failover](/t/14171) |
8578
| 3 | h-async-recovery | [Recovery](/t/14172) |
8679
| 3 | h-async-removal | [Removal](/t/14174) |
80+
| 2 | h-development| [Development]() |
81+
| 3 | h-development-integrate | [Integrate with your charm](/t/11890) |
82+
| 3 | h-migrate-mysqldump | [Migrate data via mysqldump](/t/11958) |
83+
| 3 | h-migrate-mydumper | [Migrate data via mydumper](/t/11988) |
84+
| 3 | h-migrate-backup-restore | [Migrate data via backup/restore](/t/12008) |
85+
| 3 | h-troubleshooting | [Troubleshooting](/t/11891) |
86+
| 4 | r-sos-report | [SOS report](/t/17245) |
8787
| 2 | h-contribute | [Contribute](/t/14654) |
88-
| 1 | reference | [Reference]() |
88+
| 1 | reference | [Reference](/t/17235) |
8989
| 2 | r-releases | [Releases](/t/11881) |
9090
| 2 | r-system-requirements | [System requirements](/t/11742) |
91-
| 2 | r-testing | [Testing](/t/11770) |
91+
| 2 | r-testing | [Software testing](/t/11770) |
9292
| 2 | r-profiles | [Profiles](/t/11973) |
9393
| 2 | r-plugins-extensions | [Plugins/extensions](/t/15481) |
9494
| 2 | r-alert-rules | [Alert rules](/t/15839) |
95-
| 2 | r-statuses | [Statuses](/t/10624) |
95+
| 2 | r-statuses | [Charm statuses](/t/10624) |
9696
| 2 | r-contacts | [Contacts](/t/11867) |
97-
| 1 | explanation | [Explanation]() |
97+
| 1 | explanation | [Explanation](/t/17237) |
9898
| 2 | e-architecture | [Architecture](/t/11756) |
9999
| 2 | e-interfaces-endpoints | [Interfaces and endpoints](/t/10250) |
100+
| 2 | e-juju | [Juju](/t/11959) |
101+
| 2 | e-legacy-charm | [Legacy charm](/t/10788) |
100102
| 2 | e-users | [Users](/t/10789) |
101-
| 2 | e-security | [Security](/t/16784) |
102-
| 2 | e-cryptography | [Cryptography](/t/16785) |
103103
| 2 | e-logs | [Logs](/t/11993) |
104104
| 3 | e-audit-logs | [Audit Logs](/t/15424) |
105-
| 2 | e-juju | [Juju](/t/11959) |
106-
| 2 | e-legacy-charm | [Legacy charm](/t/10788) |
105+
| 2 | e-security | [Security](/t/16784) |
106+
| 3 | e-cryptography | [Cryptography](/t/16785) |
107107
| 1 | search | [Search](https://canonical.com/data/docs/mysql/iaas) |
108108

109109
[/details]

‎docs/reference.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Reference
2+
3+
Technical specifications, APIs, release notes, and other reference material for fast lookup.
4+
5+
| Page | Description |
6+
|-------------------------|-------------------------------------------------|
7+
| [Releases](/t/11881) | Overview of all Charmed MySQL releases |
8+
| [System requirements](/t/11742) | Software and hardware requirements |
9+
| [Software testing](/t/11770) | Software tests performed on this charm |
10+
| [Profiles](/t/11973) | Configurations related to performance |
11+
| [Plugins/extensions](/t/15481) | Supported plugins/extensions |
12+
| [Alert rules](/t/15839) | Pre-configured Prometheus alert rules |
13+
| [Charm statuses](/t/10624) | Juju application statuses |
14+
| [Contacts](/t/11867) | Contact information |
15+
16+
17+
In the tabs at the top of this charm's [CharmHub page](https://charmhub.io/mysql/), you will find the following automatically generated references:
18+
19+
| Page | Description |
20+
|----------|-------------------|
21+
| [Integrations](https://charmhub.io/mysql/integrations) | Integration/relation interfaces supported by this charm |
22+
| [Configuration](https://charmhub.io/mysql/configuration) | Configuration parameters specific to this charm |
23+
| [Actions](https://charmhub.io/mysql/actions) | Juju actions supported by this charm |

‎docs/reference/r-sos-report.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# SoS report
2+
3+
SoS is an extensible, portable, support data collection tool primarily aimed at Linux distributions and other UNIX-like operating systems.
4+
5+
You can use the [built-in version of SoS](#use-built-in-sos-recommended), or [retrieve the latest version from GitHub](#use-the-latest-sos-plugins-from-git).
6+
7+
[note type=caution]
8+
Always review the collected data before sharing it!
9+
10+
The generated archive may contain sensitive data. Its content should be reviewed by the originating organization before being passed to any third party.
11+
[/note]
12+
13+
## Use built-in SoS (recommended)
14+
15+
[note type=caution]
16+
The newly created SOS plugin [charmed_mysql](https://github.com/sosreport/sos/blob/main/sos/report/plugins/charmed_mysql.py) might still be missing on your installation, consider to update [sosreport](http://packages.ubuntu.com/sosreport) apt package to version 4.10+ or use the latest sos plugins from Git (described below).
17+
[/note]
18+
19+
Charmed MySQL shipped with built-in [SoS](https://github.com/sosreport/sos) reporting tool. You can use it to collect logs on a specific unit or multiple units at once.
20+
21+
### Collect logs on one unit
22+
23+
To generate the troubleshooting report archiving all logs simply call `sos report` inside the relevant Juju unit:
24+
```shell
25+
juju ssh mysql/0
26+
> sudo sos report -o system,systemd,snap,charmed_mysql --low-priority
27+
```
28+
As a result, the archive will all logs will be generated and can be shared with your support representative:
29+
```shell
30+
...
31+
Your sos report has been generated and saved in:
32+
/tmp/sosreport-juju-d4c067-1-2025-04-07-chdmwlz.tar.xz
33+
34+
Size 216.36KiB
35+
Owner root
36+
sha256 b3bf2c54bb3d934ca61ab2a17c19e98b2abeafd45589f268b62bd02f6b2a4c5f
37+
...
38+
```
39+
40+
Use `juju scp` to copy logs from Juju unit to localhost:
41+
```shell
42+
juju scp mysql/0:/tmp/sosreport-juju-d4c067-1-2025-04-07-chdmwlz.tar.xz .
43+
```
44+
45+
[details="Example output"]
46+
```shell
47+
juju ssh mysql/0
48+
49+
ubuntu@juju-d4c067-1:~$ sudo sos report -o system,systemd,snap,charmed_mysql --low-priority
50+
51+
sos report (version 4.8.2)
52+
53+
This command will collect system configuration and diagnostic
54+
information from this Ubuntu system.
55+
56+
For more information on Canonical visit:
57+
58+
Community Website : https://www.ubuntu.com/
59+
Commercial Support : https://www.canonical.com
60+
61+
The generated archive may contain data considered sensitive and its
62+
content should be reviewed by the originating organization before being
63+
passed to any third party.
64+
65+
No changes will be made to system configuration.
66+
67+
68+
Press ENTER to continue, or CTRL-C to quit.
69+
70+
Optionally, please enter the case id that you are generating this report for []:
71+
72+
Setting up archive ...
73+
Setting up plugins ...
74+
Running plugins. Please wait ...
75+
76+
Starting 4/4 systemd [Running: charmed_mysql system snap systemd]
77+
Finishing plugins [Running: charmed_mysql]
78+
Finished running plugins
79+
Creating compressed archive...
80+
81+
Your sos report has been generated and saved in:
82+
/tmp/sosreport-juju-d4c067-1-2025-04-07-qntyqpz.tar.xz
83+
84+
Size 285.60KiB
85+
Owner root
86+
sha256 d318d7de7595ebae1bce093a375129fafbd397c297317de3006fbfe45e93d43d
87+
88+
Please send this file to your support representative.
89+
90+
ubuntu@juju-d4c067-1:~$ exit
91+
92+
juju scp mysql/0:/tmp/sosreport-juju-d4c067-1-2025-04-07-qntyqpz.tar.xz .
93+
```
94+
[/details]
95+
96+
### Collect logs from several units
97+
98+
The sos tool allows you to collect logs from several Juju units (replace <UNIT_A/B/...> labels with proper Juju unit like `mysql/0`).
99+
100+
Run the following command from outside the Juju units:
101+
```shell
102+
sos collect --cluster-type juju --no-local -c "juju.units=<UNIT_A>,<UNIT_B>,<...>" --batch -o system,systemd,snap,charmed_mysql --low-priority
103+
```
104+
105+
## Use the latest sos plugins from Git
106+
107+
The latest version of [sos plugins](https://github.com/sosreport/sos/tree/main/sos/report/plugins) can be retrieved from Git easily:
108+
```shell
109+
git clone https://github.com/sosreport/sos.git
110+
cd sos
111+
sudo ./bin/sos report -­a
112+
```
113+
114+
The output will be the same to the example above providing archive with all logs as above:
115+
```shell
116+
Your sos report has been generated and saved in:
117+
/tmp/sosreport-juju-d4c067-1-2025-04-07-egosqmi.tar.xz
118+
```

‎docs/tutorial/t-overview.md renamed to ‎docs/tutorial.md

File renamed without changes.

0 commit comments

Comments
 (0)