Skip to content

Commit 5006746

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

13 files changed

+190
-575
lines changed

‎docs/explanation/e-cryptography.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Cryptography
2+
3+
This document describes the cryptography used by Charmed MySQL K8s.
4+
5+
## Resource checksums
6+
7+
Charmed MySQL K8s and Charmed MySQL Router K8s operators use a pinned version of the [Charmed MySQL rock](https://github.com/orgs/canonical/packages/container/package/charmed-mysql) to provide reproducible and secure environments.
8+
9+
The rock is an OCI image derived from the respective snap. The Charmed MySQL K8s snap packages the MySQL workload along with the necessary dependencies and utilities required for the operators’ lifecycle. For more details, see the snap contents in the [snapcraft.yaml file](https://github.com/canonical/charmed-mysql-snap/blob/8.0/edge/snap/snapcraft.yaml).
10+
11+
Every artifact bundled into the Charmed MySQL snap is verified against its MD5, SHA256, or SHA512 checksum after download. The installation of certified snap into the rock is ensured by snap primitives that verify their squashfs filesystems images GPG signature. For more information on the snap verification process, refer to the [snapcraft.io documentation](https://snapcraft.io/docs/assertions).
12+
13+
## Sources verification
14+
15+
MySQL and its extra components (mysql-shell, xtrabackup, mysqld-exporter, mysqlrouter-exporter, percona-server-plugins, mysql-pitr-helper, etc.) are built by Canonical from upstream source codes into PPAs and stored on [Launchpad](https://launchpad.net/ubuntu/+source/mysql-8.0).
16+
17+
Charmed MySQL K8s charm, snap and rock are published and released programmatically using release pipelines implemented via GitHub Actions in their respective repositories.
18+
19+
All repositories in GitHub are set up with branch protection rules, requiring:
20+
21+
* new commits to be merged to main branches via pull request with at least 2 approvals from repository maintainers
22+
* new commits to be signed (e.g. using GPG keys)
23+
* developers to sign the [Canonical Contributor License Agreement (CLA)](https://ubuntu.com/legal/contributors)
24+
25+
## Encryption
26+
27+
Charmed MySQL K8s can be used to deploy a secure MySQL cluster on K8s that provides encryption-in-transit capabilities out of the box for:
28+
29+
* Cluster communications
30+
* MySQL Router connections
31+
* External client connections
32+
33+
To set up a secure connection Charmed MySQL and Charmed MySQL Router need to be integrated with TLS Certificate Provider charms, e.g. `self-signed-certificates` operator. Certificate Signing Requests (CSRs) are generated for every unit using the `tls_certificates_interface` library that uses the `cryptography` Python library to create X.509 compatible certificates. The CSR is signed by the TLS Certificate Provider, returned to the units, and stored in Juju secret. The relation also provides the CA certificate, which is loaded into Juju secret.
34+
35+
Encryption at rest is currently not supported, although it can be provided by the substrate (cloud or on-premises).
36+
37+
## Authentication
38+
39+
In Charmed MySQL, authentication layers can be enabled for:
40+
41+
1. MySQL Router connections
42+
2. MySQL cluster communication
43+
3. MySQL clients connections
44+
45+
### MySQL Router authentication to MySQL
46+
47+
Authentication to MySQL Router is based on the [caching_sha2_password auth plugin](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html).
48+
49+
Credentials are exchanged via [Juju secrets](https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-secrets/).
50+
51+
### MySQL cluster authentication
52+
53+
Authentication among members of a MySQL cluster is based on the [caching_sha2_password auth plugin](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html).
54+
55+
An internal user is used for this authentication with its hashed password stored in a system metadata database.
56+
57+
### Client authentication to MySQL
58+
59+
Authentication to MySQL Router is based on the [caching_sha2_password auth plugin](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html).
60+
61+
Credentials are exchanged via [Juju secrets](https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-secrets/).

‎docs/explanation/e-security.md

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Security hardening guide
2+
3+
This document provides an overview of security features and guidance for hardening the security of [Charmed MySQL K8s](https://charmhub.io/mysql-k8s) deployments, including setting up and managing a secure environment.
4+
5+
## Environment
6+
7+
The environment where Charmed MySQL K8s operates can be divided into two components:
8+
9+
1. Kubernetes
10+
2. Juju
11+
12+
### Kubernetes
13+
14+
Charmed MySQL K8s can be deployed on top of several Kubernetes distributions. The following table provides references for the security documentation for the main supported cloud platforms.
15+
16+
| Cloud | Security guides |
17+
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
18+
| Charmed Kubernetes | [Security in Charmed Kubernetes](https://ubuntu.com/kubernetes/docs/security) |
19+
| AWS EKS | [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), [Security in EKS](https://docs.aws.amazon.com/eks/latest/userguide/security.html) |
20+
| 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/), [Security in AKS](https://learn.microsoft.com/en-us/azure/aks/concepts-security) |
21+
| GCP GKE | [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) |
22+
23+
### Juju
24+
25+
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
26+
[Juju security page](/t/juju-security/15684) and the [How to harden your deployment](https://juju.is/docs/juju/harden-your-deployment) guide.
27+
28+
#### Cloud credentials
29+
30+
When configuring cloud credentials to be used with Juju, ensure that users have the correct permissions to operate at the required level on the Kubernetes cluster. Juju superusers responsible for bootstrapping and managing controllers require elevated permissions to manage several kinds of resources. For this reason, the K8s user for bootstrapping and managing the deployments should have full permissions, such as:
31+
32+
* create, delete, patch, and list:
33+
* namespaces
34+
* services
35+
* deployments
36+
* stateful sets
37+
* pods
38+
* PVCs
39+
40+
In general, it is common practice to run Juju using the admin role of K8s, to have full permissions on the Kubernetes cluster.
41+
42+
#### Juju users
43+
44+
It is very important that Juju users are set up with minimal permissions depending on the scope of their operations. Please refer to the [User access levels](https://juju.is/docs/juju/user-permissions) documentation for more information on the access levels and corresponding abilities.
45+
46+
Juju user credentials must be stored securely and rotated regularly to limit the chances of unauthorized access due to credentials leakage.
47+
48+
## Applications
49+
50+
In the following sections, we provide guidance on how to harden your deployment using:
51+
52+
1. Base images
53+
2. Charmed operator security upgrades
54+
3. Encryption
55+
4. Authentication
56+
5. Monitoring and auditing
57+
58+
### Base images
59+
60+
Charmed MySQL K8s and Charmed MySQL Router K8s run on top of the same rock (OCI-compliant rockcraft-based image). The rock is based on Ubuntu 22.04 and ships the MySQL distribution binaries built by Canonical. It is stored in a [GitHub registry](https://github.com/canonical/charmed-mysql-rock/pkgs/container/charmed-mysql) and is used as the base image for different pods providing MySQL services.
61+
62+
### Charmed operator security upgrades
63+
64+
[Charmed MySQL K8s operator](https://github.com/canonical/mysql-k8s-operator) and [Charmed MySQL Router K8s operator](https://github.com/canonical/mysql-router-k8s-operator) install pinned versions of the rock to provide reproducible and secure environments. New versions (revisions) of charmed operators can be released to update the operator's code, workloads, or both. It is important to refresh the charm regularly to make sure the workload is as secure as possible.
65+
66+
For more information on upgrading Charmed MySQL K8s, see the [How to upgrade MySQL](https://canonical.com/data/docs/mysql/k8s/h-upgrade) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router-k8s/docs/h-upgrade-intro) guides, as well as the [Release notes](https://canonical.com/data/docs/mysql/k8s/r-releases).
67+
68+
### Encryption
69+
70+
By default, encryption is optional for external connections. Internal communication between cluster members is always encrypted with TLS with self-signed certificates.
71+
72+
To enforce encryption in transit for external connections, integrate Charmed MySQL K8s with a TLS certificate provider. Please refer to the [Charming Security page](https://charmhub.io/topics/security-with-x-509-certificates) for more information on how to select the right certificate provider for your use case.
73+
74+
Encryption in transit for backups is provided by the storage service (Charmed MySQL K8s is a client for an S3-compatible storage).
75+
76+
For more information on encryption, see the [Cryptography](https://discourse.charmhub.io/t/charmed-mysql-k8s-explanations-cryptography/16783) explanation page and [How to enable encryption](https://canonical.com/data/docs/mysql/k8s/h-enable-tls) guide.
77+
78+
### Authentication
79+
80+
Charmed MySQL K8s uses the [caching_sha2_password](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html) plugin for authentication.
81+
82+
### Monitoring and auditing
83+
84+
Charmed MySQL K8s provides native integration with the [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack). To reduce the blast radius of infrastructure disruptions, the general recommendation is to deploy COS and the observed application into separate environments, isolated from one another. Refer to the [COS production deployments best practices](https://charmhub.io/topics/canonical-observability-stack/reference/best-practices) for more information or see the How to guides for MySQL K8s [monitoring](https://canonical.com/data/docs/mysql/k8s/h-enable-monitoring), [alert rules](https://canonical.com/data/docs/mysql/k8s/h-enable-alert-rules), and [tracing](https://canonical.com/data/docs/mysql/k8s/h-enable-tracing) for practical instructions.
85+
86+
The Audit log plugin is enabled by default and produces login/logout logs. See the [Audit Logs](https://charmhub.io/mysql-k8s/docs/e-audit-logs) guide for further configuration. These logs are stored in the /var/log/mysql directory of the MySQL container and are rotated every minute to the /var/log/mysql/archive_audit directory. It’s recommended to integrate the charm with [COS](https://discourse.charmhub.io/t/9900), from where the logs can be easily persisted and queried using [Loki](https://charmhub.io/loki-k8s)/[Grafana](https://charmhub.io/grafana).
87+
88+
## Additional Resources
89+
90+
For details on the cryptography used by Charmed MySQL K8s, see the [Cryptography](https://discourse.charmhub.io/t/charmed-mysql-k8s-explanations-cryptography/16783) explanation page.

‎docs/how-to/h-upgrade-minor.md

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
[note]
1+
22
**Note**: All commands are written for `juju >= v.3.0`
33

44
If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
5-
[/note]
5+
66

77
# Perform a minor upgrade
88

@@ -20,10 +20,9 @@ We strongly recommend to **NOT** perform any other extraordinary operations on a
2020

2121
The concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
2222

23-
[note type=caution]
24-
Make sure to have a backup of your data when running any type of upgrades!
23+
24+
**Note**: Make sure to have a backup of your data when running any type of upgrades!
2525
See: [How to create a backup](/t/9653)
26-
[/note]
2726

2827
It is recommended to deploy your application in conjunction with [Charmed MySQL Router K8s](https://charmhub.io/mysql-router-k8s). This will ensure minimal service disruption, if any.
2928

@@ -40,11 +39,10 @@ It is recommended to deploy your application in conjunction with [Charmed MySQL
4039

4140
## Step 1: Collect
4241

43-
[note]
44-
This step is only valid when deploying from [charmhub](https://charmhub.io/).
42+
43+
**Note**: This step is only valid when deploying from [charmhub](https://charmhub.io/).
4544

4645
If a [local charm](https://juju.is/docs/sdk/deploy-a-charm) is deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the `.charm` file is available BEFORE going further. You might need it for a rollback.
47-
[/note]
4846

4947
The first step is to record the revision of the running application as a safety measure for a rollback action. To accomplish this, run the `juju status` command and look for the deployed Charmed MySQL K8s revision in the command output, e.g:
5048

@@ -104,6 +102,7 @@ Use the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command to trig
104102
Example with channel selection
105103
```shell
106104
juju refresh mysql-k8s --channel 8.0/edge --trust
105+
```
107106

108107
Example with specific revision selection (do not forget the OCI resource)
109108
```shell

‎docs/overview.md

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -83,14 +83,7 @@ Charmed MySQL K8s is an official distribution of MySQL. It’s an open-source pr
8383
| 3 | h-async-removal | [Removal](/t/13468) |
8484
| 2 | h-contribute | [Contribute](/t/14655) |
8585
| 1 | reference | [Reference]() |
86-
| 2 | r-releases | [Release Notes](/t/11878) |
87-
| 3 | r-revision-210-211 | [Revision 210/211](/t/16133) |
88-
| 3 | r-revision-180-181 | [Revision 180/181](/t/15276) |
89-
| 3 | r-revision-153 | [Revision 153](/t/14072) |
90-
| 3 | r-revision-127 | [Revision 127](/t/13522) |
91-
| 3 | r-revision-113 | [Revision 113](/t/12221) |
92-
| 3 | r-revision-99 | [Revision 99](/t/11880) |
93-
| 3 | r-revision-75 | [Revision 75](/t/11879) |
86+
| 2 | r-releases | [Releases](/t/11878) |
9487
| 2 | r-system-requirements | [System requirements](/t/11421) |
9588
| 2 | r-testing | [Testing](/t/11772) |
9689
| 2 | r-profiles | [Profiles](/t/11892) |
@@ -102,6 +95,8 @@ Charmed MySQL K8s is an official distribution of MySQL. It’s an open-source pr
10295
| 2 | e-architecture | [Architecture](/t/11757) |
10396
| 2 | e-interfaces-endpoints | [Interfaces/endpoints](/t/10249) |
10497
| 2 | e-users | [Users](/t/10791) |
98+
| 2 | e-security | [Security](/t/16782) |
99+
| 2 | e-cryptography | [Cryptography](/t/16783) |
105100
| 2 | e-logs | [Logs](/t/12080) |
106101
| 3 | e-audit-logs | [Audit Logs](/t/15423) |
107102
| 2 | e-juju | [Juju](/t/11984) |
@@ -111,8 +106,16 @@ Charmed MySQL K8s is an official distribution of MySQL. It’s an open-source pr
111106

112107
[/details]
113108

114-
<!--
109+
<!--Archived
115110
| 2 | h-development| [Development](/t/11884) |
116111
| 3 | h-upgrade-major | [Perform a major upgrade](/t/11750) |
117112
| 3 | h-rollback-major | [Perform a major rollback](/t/11751) |
118-
--> Charmed MySQL K8s Documentation
113+
114+
| 3 | r-revision-210-211 | [Revision 210/211](/t/16133) |
115+
| 3 | r-revision-180-181 | [Revision 180/181](/t/15276) |
116+
| 3 | r-revision-153 | [Revision 153](/t/14072) |
117+
| 3 | r-revision-127 | [Revision 127](/t/13522) |
118+
| 3 | r-revision-113 | [Revision 113](/t/12221) |
119+
| 3 | r-revision-99 | [Revision 99](/t/11880) |
120+
| 3 | r-revision-75 | [Revision 75](/t/11879) |
121+
-->

‎docs/reference/r-releases.md

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ To see all releases and commits, check the [Charmed MySQL K8s Releases page on G
88

99
| Release | MySQL version | Juju version | [TLS encryption](/t/9655)* | [COS monitoring](/t/9981) | [Minor version upgrades](/t/11752) | [Cross-regional async replication](/t/13458) |
1010
|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
11+
| [240], [241] | 8.0.41 | `3.5.4+` | ![check] | ![check] | ![check] | ![check] |
1112
| [210], [211] | 8.0.39 | `3.5.4+` | ![check] | ![check] | ![check] | ![check] |
1213
| [180], [181] | 8.0.37 | `3.4.3+` | ![check] | ![check] | ![check] | ![check] |
1314
| [153] | 8.0.36 | `3.4.3+` | ![check] | ![check] | ![check] | ![check] |
@@ -30,12 +31,17 @@ Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneous
3031
3132
### Release 210-211
3233

34+
| Revision | amd64 | arm64 | Ubuntu 22.04 LTS
35+
|:--------:|:-----:|:-----:|:-----:|
36+
|[240] |![check] | | ![check] |
37+
|[241] | | ![check]| ![check] |
38+
39+
[details=Older releases]
3340
| Revision | amd64 | arm64 | Ubuntu 22.04 LTS
3441
|:--------:|:-----:|:-----:|:-----:|
3542
|[210] |![check] | | ![check] |
3643
|[211] | | ![check]| ![check] |
3744

38-
[details=Older releases]
3945
### Release 180-181
4046

4147
| Revision | amd64 | arm64 | Ubuntu 22.04 LTS
@@ -75,15 +81,17 @@ Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneous
7581
[/details]
7682

7783
<!-- LINKS -->
78-
[210]: /t/16133
79-
[211]: /t/16133
80-
[180]: /t/15276
81-
[181]: /t/15276
82-
[153]: /t/14072
83-
[127]: /t/13522
84-
[113]: /t/12221
85-
[99]: /t/11880
86-
[75]: /t/11879
84+
[240]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev240
85+
[241]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev240
86+
[210]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev210
87+
[211]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev210
88+
[180]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev180
89+
[181]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev180
90+
[153]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev153
91+
[127]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev127
92+
[113]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev113
93+
[99]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev99
94+
[75]: https://github.com/canonical/mysql-k8s-operator/releases/tag/rev75
8795

8896
<!-- BADGES -->
8997
[check]: https://img.icons8.com/color/20/checkmark--v1.png

0 commit comments

Comments
 (0)