From b6837fbce1a660fb3f97cd3a5854b7723f749547 Mon Sep 17 00:00:00 2001 From: Martin Montes Date: Thu, 29 Feb 2024 12:24:34 +0100 Subject: [PATCH] Storage docs --- docs/BACKUP.md | 4 + docs/GALERA.md | 6 +- docs/HA.md | 6 +- docs/METRICS.md | 4 + docs/STORAGE.md | 100 ++++++++++++++++++ examples/manifests/mariadb_galera_full.yaml | 7 ++ .../manifests/mariadb_replication_full.yaml | 7 ++ 7 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 docs/STORAGE.md diff --git a/docs/BACKUP.md b/docs/BACKUP.md index 2e2e9025..6fe8a333 100644 --- a/docs/BACKUP.md +++ b/docs/BACKUP.md @@ -240,3 +240,7 @@ make cluster make install-minio make net # to access the console via a MetalLB LoadBalancer: https://minio-console:9001 ``` + +## Reference +- [API reference](./API_REFERENCE.md) +- [Example suite](../examples/) diff --git a/docs/GALERA.md b/docs/GALERA.md index a75ebb33..6d6a4cc4 100644 --- a/docs/GALERA.md +++ b/docs/GALERA.md @@ -359,4 +359,8 @@ Increase this timeout if you consider that your Galera cluster may take longer t ### GitHub Issues Here it is a list of GitHub issues reported by `mariadb-operator` users which might shed some light in your investigation: -- https://github.com/mariadb-operator/mariadb-operator/issues?q=is%3Aclosed+label%3Agalera-troubleshoot+ \ No newline at end of file +- https://github.com/mariadb-operator/mariadb-operator/issues?q=is%3Aclosed+label%3Agalera-troubleshoot+ + +## Reference +- [API reference](./API_REFERENCE.md) +- [Example suite](../examples/) diff --git a/docs/HA.md b/docs/HA.md index dc13a59d..01ac0b24 100644 --- a/docs/HA.md +++ b/docs/HA.md @@ -88,4 +88,8 @@ spec: - key: "k8s.mariadb.com/ha" operator: "Exists" effect: "NoSchedule" -``` \ No newline at end of file +``` + +## Reference +- [API reference](./API_REFERENCE.md) +- [Example suite](../examples/) diff --git a/docs/METRICS.md b/docs/METRICS.md index 45106371..a5624988 100644 --- a/docs/METRICS.md +++ b/docs/METRICS.md @@ -96,3 +96,7 @@ To visualize MariaDB metrics, our [Prometheus reference installation](#prometheu ##### [Galera/MariaDB - Overview](https://grafana.com/grafana/dashboards/13106-galera-mariadb-overview/) + +## Reference +- [API reference](./API_REFERENCE.md) +- [Example suite](../examples/) diff --git a/docs/STORAGE.md b/docs/STORAGE.md new file mode 100644 index 00000000..bc4c4be8 --- /dev/null +++ b/docs/STORAGE.md @@ -0,0 +1,100 @@ +# Storage + +> [!WARNING] +> This documentation applies to `mariadb-operator` version >= v0.0.26 + +This operator gives you flexibility to define the storage that will back your `/var/lib/mysql` data directoty mounted by `MariaDB`. + +## Configuration + +The simplest way to configure storage for your `MariaDB` is: + +```yaml +apiVersion: k8s.mariadb.com/v1alpha1 +kind: MariaDB +metadata: + name: mariadb-galera +spec: + ... + storage: + size: 1Gi +``` + +This will make use of the default `StorageClass` available in your cluster, but you can also provide a different one: + +```yaml +apiVersion: k8s.mariadb.com/v1alpha1 +kind: MariaDB +metadata: + name: mariadb-galera +spec: + ... + storage: + size: 1Gi + storageClassName: my-storage-class +``` + +Under the scenes, the operator is configuring the `StatefulSet`'s `volumeClaimTemplate` property, which you are also able to provide yourself: + +```yaml +apiVersion: k8s.mariadb.com/v1alpha1 +kind: MariaDB +metadata: + name: mariadb-galera +spec: + ... + storage: + size: 1Gi + storageClassName: standard + volumeClaimTemplate: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: standard +``` + +## Volume resize + +It is possible to resize your storage after having provisioned a `MariaDB`. We need to distinguish between: +- PVCs already in use. +- `StatefulSet` storage size, which will be used when provisioning new replicas. + +It is important to note that, for the first case, your `StorageClass` must support volume expansion by declaring the `allowVolumeExpansion = true`. In such case, it will be safe to expand the storage by increasing the `size` and setting `resizeInUseVolumes = true`: + +```yaml +apiVersion: k8s.mariadb.com/v1alpha1 +kind: MariaDB +metadata: + name: mariadb-galera +spec: + ... + storage: + size: 2Gi + resizeInUseVolumes: true + waitForVolumeResize: true +``` + +Depending on your storage provider, this operation might take a while, and you can decide to wait for this operation before the `MariaDB` becomes ready by setting `waitForVolumeResize = true`. Operations such as [cluster recovery](./GALERA.md#galera-cluster-recovery) and [primary switchover](./HA.md) will not be performed if the `MariaDB` resource is not ready. + +## Ephemeral storage + +Provisioning standalone `MariaDB` instances is also possible by setting `ephemeral = true`: + +```yaml +apiVersion: k8s.mariadb.com/v1alpha1 +kind: MariaDB +metadata: + name: mariadb-galera +spec: + ... + storage: + ephemeral: true +``` + +This may be useful more multiple use cases, like provisioning ephemeral `MariaDBs` for the integration tests of your CI. + +## Reference +- [API reference](./API_REFERENCE.md) +- [Example suite](../examples/) diff --git a/examples/manifests/mariadb_galera_full.yaml b/examples/manifests/mariadb_galera_full.yaml index f13fda5a..81030a8e 100644 --- a/examples/manifests/mariadb_galera_full.yaml +++ b/examples/manifests/mariadb_galera_full.yaml @@ -14,6 +14,13 @@ spec: storageClassName: standard resizeInUseVolumes: true waitForVolumeResize: true + volumeClaimTemplate: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: standard replicas: 3 diff --git a/examples/manifests/mariadb_replication_full.yaml b/examples/manifests/mariadb_replication_full.yaml index c5d8cf2a..031bcaae 100644 --- a/examples/manifests/mariadb_replication_full.yaml +++ b/examples/manifests/mariadb_replication_full.yaml @@ -14,6 +14,13 @@ spec: storageClassName: standard resizeInUseVolumes: true waitForVolumeResize: true + volumeClaimTemplate: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: standard replicas: 3