From 10f53ff83aef903e1eaa3e2c8dc85439771cd2c1 Mon Sep 17 00:00:00 2001 From: Emruz Hossain Date: Thu, 17 Dec 2020 16:08:34 +0600 Subject: [PATCH] Add MariaDB docs (#117) Signed-off-by: Emruz Hossain --- docs/addons/elasticsearch/README.md | 10 +- docs/addons/elasticsearch/setup/install.md | 16 +- docs/addons/mariadb/README.md | 46 + docs/addons/mariadb/_index.md | 10 + docs/addons/mariadb/guides/_index.md | 11 + docs/addons/mariadb/overview.md | 87 ++ docs/addons/mariadb/setup/_index.md | 11 + docs/addons/mariadb/setup/install.md | 116 ++ docs/addons/mariadb/setup/uninstall.md | 74 ++ docs/addons/mongodb/README.md | 10 +- docs/addons/mongodb/_index.md | 2 +- docs/addons/mongodb/setup/install.md | 16 +- docs/addons/mysql/README.md | 10 +- docs/addons/mysql/_index.md | 2 +- docs/addons/mysql/setup/install.md | 16 +- docs/addons/percona-xtradb/README.md | 10 +- docs/addons/percona-xtradb/setup/install.md | 16 +- docs/addons/postgres/README.md | 10 +- docs/addons/postgres/setup/install.md | 16 +- .../addons/mariadb/mariadb-logical-backup.svg | 987 ++++++++++++++++++ .../mariadb/mariadb-logical-restore.svg | 857 +++++++++++++++ 21 files changed, 2284 insertions(+), 49 deletions(-) create mode 100644 docs/addons/mariadb/README.md create mode 100644 docs/addons/mariadb/_index.md create mode 100644 docs/addons/mariadb/guides/_index.md create mode 100644 docs/addons/mariadb/overview.md create mode 100644 docs/addons/mariadb/setup/_index.md create mode 100644 docs/addons/mariadb/setup/install.md create mode 100644 docs/addons/mariadb/setup/uninstall.md create mode 100644 docs/images/addons/mariadb/mariadb-logical-backup.svg create mode 100644 docs/images/addons/mariadb/mariadb-logical-restore.svg diff --git a/docs/addons/elasticsearch/README.md b/docs/addons/elasticsearch/README.md index 7889367e..813e4c4e 100644 --- a/docs/addons/elasticsearch/README.md +++ b/docs/addons/elasticsearch/README.md @@ -29,7 +29,13 @@ Stash supports backup and restore of the following Elasticsearch versions: {{< versionlist "elasticsearch" "/docs/addons/elasticsearch/guides/%s/elasticsearch.md" >}} ->Version **M.M** actually represents the latest patch of **M.M.P** series. For example, version **7.3** actually represents **7.3.2** as it is the latest supported patch of **7.3** series. Now, if **7.3.3** is released then **7.3** will represents **7.3.3**. +Here, the addon follows `M.M.P-vX` versioning scheme where `M.M.P` (Major.Minor.Patch) represents the respective database version and an optional `-vX` (here, `X` is a monotonically increasing integer) is added if there is any breaking change in the addon image compared to the previous release. + +{{< notice type="warning" message="If you update Stash operator to a newer release and the supported addon versions in the newer release has different `-vX` suffix, you have to update the old addons too. Otherwise, backup may not work. In this case, just uninstall the old addons and install the new addons." >}} + +## Addon Version Compatibility + +Any addon with matching major version with the database version should be able to take backup of that database. For example, Elasticsearch addon with version `7.x.x-vX` should be able take backup of any Elasticsearch of `7.x.x` series. However, this might not be true for some versions. In that case, we will have separate addon for that version. ## Documentation Overview @@ -37,4 +43,4 @@ Stash Elasticsearch documentations are organized as below: - [How does it works?](/docs/addons/elasticsearch/overview.md) gives an overview of how backup and restore process for Elasticsearch database works in Stash. - [Setup](/docs/addons/elasticsearch/setup/install.md) shows how to install and uninstall Elasticsearch addon for Stash. -- [Guides](/docs/addons/elasticsearch/guides/6.5/elasticsearch.md) contains step by step guides to backup and restore different versions of Elasticsearch databases. +- **Guides** contains step by step guides to backup and restore different versions of Elasticsearch databases. diff --git a/docs/addons/elasticsearch/setup/install.md b/docs/addons/elasticsearch/setup/install.md index 0da2ddac..1f89784d 100644 --- a/docs/addons/elasticsearch/setup/install.md +++ b/docs/addons/elasticsearch/setup/install.md @@ -130,11 +130,11 @@ curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/d The flowing flags are available for customizing Elasticsearch addon installation: -| Flag | Usage | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | -| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | -| `--image` | Specify the name of the docker image to use for respective addons. | -| `--image-tag` | Specify the tag of the docker image to use for respective addon. | -| `--es-backup-args` | Specify optional arguments to pass to `multielaticdump` command during backup. These arguments apply to all Elasticsearch instances in this cluster. To set arguments for a specific Elasticsearch database instance, set `esArgs` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | -| `--es-restore-args` | Specify optional arguments to pass to `multielastic` command during restore. These arguments apply to all Elasticsearch instances in this cluster. To set arguments for a specific Elasticsearch database instance, set `esArgs` parameter in `spec.task.params` field of the respective `RestoreSession`. | +| Flag | Usage | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | +| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | +| `--image` | Specify the name of the docker image to use for respective addons. | +| `--image-tag` | Specify the tag of the docker image to use for respective addon. | +| `--backup-args` | Specify optional arguments to pass to `multielaticdump` command during backup. These arguments apply to all Elasticsearch instances in this cluster. To set arguments for a specific Elasticsearch database instance, set `args` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | +| `--restore-args` | Specify optional arguments to pass to `multielastic` command during restore. These arguments apply to all Elasticsearch instances in this cluster. To set arguments for a specific Elasticsearch database instance, set `args` parameter in `spec.task.params` field of the respective `RestoreSession`. | diff --git a/docs/addons/mariadb/README.md b/docs/addons/mariadb/README.md new file mode 100644 index 00000000..0e712cce --- /dev/null +++ b/docs/addons/mariadb/README.md @@ -0,0 +1,46 @@ +--- +title: MariaDB Addon Overview | Stash +description: MariaDB Addon Overview | Stash +menu: + docs_{{ .version }}: + identifier: stash-mariadb-readme + name: Readme + parent: stash-mariadb + weight: -1 +product_name: stash +menu_name: docs_{{ .version }} +section_menu_id: stash-addons +url: /docs/{{ .version }}/addons/mariadb/ +aliases: + - /docs/{{ .version }}/addons/mariadb/README/ +--- + +{{< notice type="warning" message="This is an Enterprise-only feature. Please install [Stash Enterprise Edition](/docs/setup/install/enterprise.md) to try this feature." >}} + +# Stash MariaDB Addon + +Stash 0.9.0+ supports extending its functionality through addons. Stash MariaDB addon enables Stash to backup and restore MariaDB databases. + +This guide will give you an overview of which MariaDB versions are supported and how the docs are organized. + +## Supported MariaDB Versions + +Stash supports backup and restore of the following MariaDB versions: + +{{< versionlist "mariadb" "/docs/addons/mariadb/guides/%s/mariadb.md" >}} + +Here, the addon follows `M.M.P-vX` versioning scheme where `M.M.P` (Major.Minor.Patch) represents the respective database version and an optional `-vX` (here, `X` is a monotonically increasing integer) is added if there is any breaking change in the addon image compared to the previous release. + +{{< notice type="warning" message="If you update Stash operator to a newer release and the supported addon versions in the newer release has different `-vX` suffix, you have to update the old addons too. Otherwise, backup may not work. In this case, just uninstall the old addons and install the new addons." >}} + +## Addon Version Compatibility + +Any addon with matching major version with the database version should be able to take backup of that database. For example, MariaDB addon with version `10.x.x-vX` should be able take backup of any MariaDB of `10.x.x` series. However, this might not be true for some versions. In that case, we will have separate addon for that version. + +## Documentation Overview + +Stash MariaDB documentations are organized as below: + +- [How does it works?](/docs/addons/mariadb/overview.md) gives an overview of how backup and restore process for MariaDB database works in Stash. +- [Setup](/docs/addons/mariadb/setup/install.md) shows how to install and uninstall MariaDB addon for Stash. +- **Guides** contains step by step guides to backup and restore different versions of MariaDB databases. diff --git a/docs/addons/mariadb/_index.md b/docs/addons/mariadb/_index.md new file mode 100644 index 00000000..3cb5330f --- /dev/null +++ b/docs/addons/mariadb/_index.md @@ -0,0 +1,10 @@ +--- +title: Stash MariaDB Addon +menu: + docs_{{ .version }}: + identifier: stash-mariadb + name: MariaDB + parent: stash-addons + weight: 60 +menu_name: docs_{{ .version }} +--- diff --git a/docs/addons/mariadb/guides/_index.md b/docs/addons/mariadb/guides/_index.md new file mode 100644 index 00000000..41853282 --- /dev/null +++ b/docs/addons/mariadb/guides/_index.md @@ -0,0 +1,11 @@ +--- +title: MariaDB Backup & Restore Guides | Stash +menu: + docs_{{ .version }}: + identifier: stash-mariadb-guides + name: Guides + parent: stash-mariadb + weight: 30 +menu_name: docs_{{ .version }} +--- + diff --git a/docs/addons/mariadb/overview.md b/docs/addons/mariadb/overview.md new file mode 100644 index 00000000..3a311daf --- /dev/null +++ b/docs/addons/mariadb/overview.md @@ -0,0 +1,87 @@ +--- +title: MariaDB Backup & Restore Overview | Stash +description: How MariaDB Backup & Restore Works in Stash +menu: + docs_{{ .version }}: + identifier: stash-mariadb-overview + name: How does it works? + parent: stash-mariadb + weight: 10 +product_name: stash +menu_name: docs_{{ .version }} +section_menu_id: stash-addons +--- + +{{< notice type="warning" message="This is an Enterprise-only feature. Please install [Stash Enterprise Edition](/docs/setup/install/enterprise.md) to try this feature." >}} + +# How Stash Backups & Restores MariaDB Database + +Stash 0.9.0+ supports backup and restore operation of many databases. This guide will give you an overview of how MariaDB database backup and restore process works in Stash. + +## Logical Backup + +Stash supports taking [logical backup](https://mariadb.com/kb/en/backup-and-restore-overview/#logical-vs-physical-backups) of MariaDB databases using [mysqldump](https://mariadb.com/kb/en/mysqldump/). It is the most flexible way to perform a backup and restore, and a good choice when the data size is relatively small. + +### How Logical Backup Works + +The following diagram shows how Stash takes logical backup of a MariaDB database. Open the image in a new tab to see the enlarged version. + +
+  MariaDB Backup Overview +
Fig: MariaDB Logical Backup Overview
+
+ +The backup process consists of the following steps: + +1. At first, a user creates a secret with access credentials of the backend where the backed up data will be stored. + +2. Then, she creates a `Repository` crd that specifies the backend information along with the secret that holds the credentials to access the backend. + +3. Then, she creates a `BackupConfiguration` crd targeting the [AppBinding](/docs/concepts/crds/appbinding.md) crd of the desired database. The `BackupConfiguration` object also specifies the `Task` to use to backup the database. + +4. Stash operator watches for `BackupConfiguration` crd. + +5. Once Stash operator finds a `BackupConfiguration` crd, it creates a CronJob with the schedule specified in `BackupConfiguration` object to trigger backup periodically. + +6. On the next scheduled slot, the CronJob triggers a backup by creating a `BackupSession` crd. + +7. Stash operator also watches for `BackupSession` crd. + +8. When it finds a `BackupSession` object, it resolves the respective `Task` and `Function` and prepares a Job definition to backup. + +9. Then, it creates the Job to backup the targeted database. + +10. The backup Job reads necessary information to connect with the database from the `AppBinding` crd. It also reads backend information and access credentials from `Repository` crd and Storage Secret respectively. + +11. Then, the Job dumps the targeted database and uploads the output to the backend. Stash pipes the output of dump command to uploading process. Hence, backup Job does not require a large volume to hold the entire dump output. + +12. Finally, when the backup is complete, the Job sends Prometheus metrics to the Pushgateway running inside Stash operator pod. It also updates the `BackupSession` and `Repository` status to reflect the backup procedure. + +### How Restore from Logical Backup Works + +The following diagram shows how Stash restores a MariaDB database from a logical backup. Open the image in a new tab to see the enlarged version. + +
+  Database Restore Overview +
Fig: MariaDB Logical Restore Process Overview
+
+ +The restore process consists of the following steps: + +1. At first, a user creates a `RestoreSession` crd targeting the `AppBinding` of the desired database where the backed up data will be restored. It also specifies the `Repository` crd which holds the backend information and the `Task` to use to restore the target. + +2. Stash operator watches for `RestoreSession` object. + +3. Once it finds a `RestoreSession` object, it resolves the respective `Task` and `Function` and prepares a Job definition to restore. + +4. Then, it creates the Job to restore the target. + +5. The Job reads necessary information to connect with the database from respective `AppBinding` crd. It also reads backend information and access credentials from `Repository` crd and Storage Secret respectively. + +6. Then, the job downloads the backed up data from the backend and injects into the desired database. Stash pipes the downloaded data to the respective database tool to inject into the database. Hence, restore job does not require a large volume to download entire backup data inside it. + +7. Finally, when the restore process is complete, the Job sends Prometheus metrics to the Pushgateway and update the `RestoreSession` status to reflect restore completion. + +## Next Steps + +- Install MariaDB addon for Stash following the guide from [here](/docs/addons/mariadb/setup/install.md). diff --git a/docs/addons/mariadb/setup/_index.md b/docs/addons/mariadb/setup/_index.md new file mode 100644 index 00000000..4c2289ed --- /dev/null +++ b/docs/addons/mariadb/setup/_index.md @@ -0,0 +1,11 @@ +--- +title: Setup MariaDB Addon | Stash +menu: + docs_{{ .version }}: + identifier: stash-mariadb-setup + name: Setup + parent: stash-mariadb + weight: 20 +menu_name: docs_{{ .version }} +--- + diff --git a/docs/addons/mariadb/setup/install.md b/docs/addons/mariadb/setup/install.md new file mode 100644 index 00000000..c41edd86 --- /dev/null +++ b/docs/addons/mariadb/setup/install.md @@ -0,0 +1,116 @@ +--- +title: Install MariaDB Addon | Stash +description: An guide on how to install MariaDB addon for Stash +menu: + docs_{{ .version }}: + identifier: stash-mariadb-install + name: Install + parent: stash-mariadb-setup + weight: 10 +product_name: stash +menu_name: docs_{{ .version }} +section_menu_id: stash-addons +--- + +{{< notice type="warning" message="This is an Enterprise-only feature. Please install [Stash Enterprise Edition](/docs/setup/install/enterprise.md) to try this feature." >}} + +# Install MariaDB Addon for Stash + +Stash uses `Function-Task` model to backup databases. This `Function-Task` model enables Stash to extend its capability via addons. In order to backup MariaDB databases, you have to install MariaDB addon (`stash-mariadb`) for Stash. This addon creates necessary `Function` and `Task` definitions to backup/restore MariaDB database. + +You can install the addon either as a helm chart or you can create only the YAMLs of the respective resources. + + +
+
+ +## Using Helm 3 + +Run the following script to install `stash-mariadb` addon as a Helm chart using Helm 3. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/helm3.sh | bash -s -- --catalog=stash-mariadb +``` + +
+
+ +## Using Helm 2 + +Run the following script to install `stash-mariadb` addon as a Helm chart using Helm 2. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/helm2.sh | bash -s -- --catalog=stash-mariadb +``` + +
+
+ +## Using YAML + +Run the following script to install `stash-mariadb` addon as Kubernetes YAMLs. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/script.sh | bash -s -- --catalog=stash-mariadb +``` + +>The above script uses Helm 3 for rendering the charts to generate the YAMLs. + +
+
+ +## Verify Installation + +After installation is completed, this addon will create `mariadb-backup-*` and `mariadb-restore-*` Functions and Tasks for all supported MariaDB versions. To verify, run the following command: + +```bash +$ kubectl get functions.stash.appscode.com +NAME AGE +mariadb-backup-10.5.8 25s +mariadb-restore-10.5.8 25s +pvc-backup 3m14s +pvc-restore 3m14s +update-status 3m14s +``` + +Also, verify that the `Task` have been created. + +```bash +$ kubectl get tasks.stash.appscode.com +NAME AGE +mariadb-backup-10.5.8 101s +mariadb-restore-10.5.8 101s +pvc-backup 4m30s +pvc-restore 4m30s +``` + +Now, Stash is ready to backup MariaDB databases. + +## Customizing Installation + +In order to install `Function` and `Task` only for a specific MariaDB version, use `--version` flag to specify the desired database version. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/helm3.sh | bash -s -- --catalog=stash-mariadb --version=10.5.8 +``` + +The flowing flags are available for customizing MariaDB addon installation: + +| Flag | Usage | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | +| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | +| `--image` | Specify the name of the docker image to use for respective addons. | +| `--image-tag` | Specify the tag of the docker image to use for respective addon. | +| `--backup-args` | Specify optional arguments to pass to `mysqldump` command during backup. These arguments apply to all MariaDB instances in this cluster. To set arguments for a specific MariaDB database instance, set `args` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | +| `--restore-args` | Specify optional arguments to pass to `mysql` command during restore. These arguments apply to all MariaDB instances in this cluster. To set arguments for a specific MariaDB database instance, set `args` parameter in `spec.task.params` field of the respective `RestoreSession`. | diff --git a/docs/addons/mariadb/setup/uninstall.md b/docs/addons/mariadb/setup/uninstall.md new file mode 100644 index 00000000..50c954b6 --- /dev/null +++ b/docs/addons/mariadb/setup/uninstall.md @@ -0,0 +1,74 @@ +--- +title: Uninstall MariaDB Addon | Stash +description: An guide on how to uninstall MariaDB addon for Stash +menu: + docs_{{ .version }}: + identifier: stash-mariadb-uninstall + name: Uninstall + parent: stash-mariadb-setup + weight: 20 +product_name: stash +menu_name: docs_{{ .version }} +section_menu_id: stash-addons +--- + +{{< notice type="warning" message="This is an Enterprise-only feature. Please install [Stash Enterprise Edition](/docs/setup/install/enterprise.md) to try this feature." >}} + +# Uninstall MariaDB addon for Stash + +In order to uninstall MariaDB addon, follow the instruction given below. + + +
+
+ +## Using Helm 3 + +Run the following script to uninstall `stash-mariadb` addon that was installed as a Helm chart using Helm 3. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/helm3.sh | bash -s -- --uninstall --catalog=stash-mariadb +``` + +
+
+ +## Using Helm 2 + +Run the following script to uninstall `stash-mariadb` addon that was installed as a Helm chart using Helm 2. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/helm2.sh | bash -s -- --uninstall --catalog=stash-mariadb +``` + +
+
+ +## Using YAML + +Run the following script to uninstall `stash-mariadb` addon that was installed as Kubernetes YAMLs. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/script.sh | bash -s -- --uninstall --catalog=stash-mariadb +``` + +
+
+ +## Customizing Uninstaller + +In order to uninstall MariaDB addon only for a specific database version, use `--version` flag to specify the desired version. + +```bash +curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/deploy/helm3.sh | bash -s -- --uninstall --catalog=stash-mariadb --version=10.5.8 +``` diff --git a/docs/addons/mongodb/README.md b/docs/addons/mongodb/README.md index d397f584..8aa06fe8 100644 --- a/docs/addons/mongodb/README.md +++ b/docs/addons/mongodb/README.md @@ -29,7 +29,13 @@ Stash supports backup and restore of the following MongoDB versions: {{< versionlist "mongodb" "/docs/addons/mongodb/guides/%s/mongodb.md" >}} ->Version **M.M** actually represents the latest patch of **M.M.P** series. For example, version **4.1** actually represents **4.1.13** as it is the latest supported patch of **4.1** series. Now, if **4.1.14** is released then **4.1** will represents **4.1.14**. +Here, the addon follows `M.M.P-vX` versioning scheme where `M.M.P` (Major.Minor.Patch) represents the respective database version and an optional `-vX` (here, `X` is a monotonically increasing integer) is added if there is any breaking change in the addon image compared to the previous release. + +{{< notice type="warning" message="If you update Stash operator to a newer release and the supported addon versions in the newer release has different `-vX` suffix, you have to update the old addons too. Otherwise, backup may not work. In this case, just uninstall the old addons and install the new addons." >}} + +## Addon Version Compatibility + +Any addon with matching major version with the database version should be able to take backup of that database. For example, MongoDB addon with version `4.x.x-vX` should be able take backup of any MongoDB of `4.x.x` series. However, this might not be true for some versions. In that case, we will have separate addon for that version. ## Documentation Overview @@ -37,4 +43,4 @@ Stash MongoDB documentations are organized as below: - [How does it works?](/docs/addons/mongodb/overview.md) gives an overview of how backup and restore process for MongoDB database works in Stash. - [Setup](/docs/addons/mongodb/setup/install.md) shows how to install and uninstall MongoDB addon for Stash. -- [Guides](/docs/addons/mongodb/guides/3.6/mongodb.md) contains step by step guides to backup and restore different versions of MongoDB databases. +- **Guides** contains step by step guides to backup and restore different versions of MongoDB databases. diff --git a/docs/addons/mongodb/_index.md b/docs/addons/mongodb/_index.md index 43aa8a16..708e18e7 100644 --- a/docs/addons/mongodb/_index.md +++ b/docs/addons/mongodb/_index.md @@ -5,7 +5,7 @@ menu: identifier: stash-mongodb name: MongoDB parent: stash-addons - weight: 40 + weight: 30 menu_name: docs_{{ .version }} --- diff --git a/docs/addons/mongodb/setup/install.md b/docs/addons/mongodb/setup/install.md index b22a95c8..f5f99c83 100644 --- a/docs/addons/mongodb/setup/install.md +++ b/docs/addons/mongodb/setup/install.md @@ -118,11 +118,11 @@ curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/d The flowing flags are available for customizing MongoDB addon installation: -| Flag | Usage | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | -| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | -| `--image` | Specify the name of the docker image to use for respective addons. | -| `--image-tag` | Specify the tag of the docker image to use for respective addon. | -| `--mg-backup-args` | Specify optional arguments to pass to `mongodump` command during backup. These arguments apply to all MongoDB instances in this cluster. To set arguments for a specific MongoDB database instance, set `mgArgs` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | -| `--mg-restore-args` | Specify optional arguments to pass to `mongorestore` command during restore. These arguments apply to all MongoDB instances in this cluster. To set arguments for a specific MongoDB database instance, set `mgArgs` parameter in `spec.task.params` field of the respective `RestoreSession`. | +| Flag | Usage | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | +| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | +| `--image` | Specify the name of the docker image to use for respective addons. | +| `--image-tag` | Specify the tag of the docker image to use for respective addon. | +| `--backup-args` | Specify optional arguments to pass to `mongodump` command during backup. These arguments apply to all MongoDB instances in this cluster. To set arguments for a specific MongoDB database instance, set `args` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | +| `--restore-args` | Specify optional arguments to pass to `mongorestore` command during restore. These arguments apply to all MongoDB instances in this cluster. To set arguments for a specific MongoDB database instance, set `args` parameter in `spec.task.params` field of the respective `RestoreSession`. | diff --git a/docs/addons/mysql/README.md b/docs/addons/mysql/README.md index f3581000..3f83497b 100644 --- a/docs/addons/mysql/README.md +++ b/docs/addons/mysql/README.md @@ -29,10 +29,18 @@ Stash supports backup and restore of the following MySQL versions: {{< versionlist "mysql" "/docs/addons/mysql/guides/%s/mysql.md" >}} +Here, the addon follows `M.M.P-vX` versioning scheme where `M.M.P` (Major.Minor.Patch) represents the respective database version and an optional `-vX` (here, `X` is a monotonically increasing integer) is added if there is any breaking change in the addon image compared to the previous release. + +{{< notice type="warning" message="If you update Stash operator to a newer release and the supported addon versions in the newer release has different `-vX` suffix, you have to update the old addons too. Otherwise, backup may not work. In this case, just uninstall the old addons and install the new addons." >}} + +## Addon Version Compatibility + +Any addon with matching major version with the database version should be able to take backup of that database. For example, MySQL addon with version `8.x.x-vX` should be able take backup of any MySQL of `8.x.x` series. However, this might not be true for some versions. In that case, we will have separate addon for that version. + ## Documentation Overview Stash MySQL documentations are organized as below: - [How does it works?](/docs/addons/mysql/overview.md) gives an overview of how backup and restore process for MySQL database works in Stash. - [Setup](/docs/addons/mysql/setup/install.md) shows how to install and uninstall MySQL addon for Stash. -- [Guides](/docs/addons/mysql/guides/8.0.14/mysql.md) contains step by step guides to backup and restore different versions of MySQL databases. +- **Guides** contains step by step guides to backup and restore different versions of MySQL databases. diff --git a/docs/addons/mysql/_index.md b/docs/addons/mysql/_index.md index 952911ab..b9ba01ed 100644 --- a/docs/addons/mysql/_index.md +++ b/docs/addons/mysql/_index.md @@ -5,6 +5,6 @@ menu: identifier: stash-mysql name: MySQL parent: stash-addons - weight: 30 + weight: 40 menu_name: docs_{{ .version }} --- diff --git a/docs/addons/mysql/setup/install.md b/docs/addons/mysql/setup/install.md index f16efc29..2a4b8c5b 100644 --- a/docs/addons/mysql/setup/install.md +++ b/docs/addons/mysql/setup/install.md @@ -110,11 +110,11 @@ curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/d The flowing flags are available for customizing MySQL addon installation: -| Flag | Usage | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | -| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | -| `--image` | Specify the name of the docker image to use for respective addons. | -| `--image-tag` | Specify the tag of the docker image to use for respective addon. | -| `--my-backup-args` | Specify optional arguments to pass to `mysqldump` command during backup. These arguments apply to all MySQL instances in this cluster. To set arguments for a specific MySQL database instance, set `myArgs` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | -| `--my-restore-args` | Specify optional arguments to pass to `mysql` command during restore. These arguments apply to all MySQL instances in this cluster. To set arguments for a specific MySQL database instance, set `myArgs` parameter in `spec.task.params` field of the respective `RestoreSession`. | +| Flag | Usage | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | +| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | +| `--image` | Specify the name of the docker image to use for respective addons. | +| `--image-tag` | Specify the tag of the docker image to use for respective addon. | +| `--backup-args` | Specify optional arguments to pass to `mysqldump` command during backup. These arguments apply to all MySQL instances in this cluster. To set arguments for a specific MySQL database instance, set `args` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | +| `--restore-args` | Specify optional arguments to pass to `mysql` command during restore. These arguments apply to all MySQL instances in this cluster. To set arguments for a specific MySQL database instance, set `args` parameter in `spec.task.params` field of the respective `RestoreSession`. | diff --git a/docs/addons/percona-xtradb/README.md b/docs/addons/percona-xtradb/README.md index 6f6b8cb0..bd2c718d 100644 --- a/docs/addons/percona-xtradb/README.md +++ b/docs/addons/percona-xtradb/README.md @@ -29,10 +29,18 @@ Stash supports backup and restore of the following Percona XtraDB versions: {{< versionlist "percona-xtradb" "/docs/addons/percona-xtradb/guides/%s/clustered.md" >}} +Here, the addon follows `M.M.P-vX` versioning scheme where `M.M.P` (Major.Minor.Patch) represents the respective database version and an optional `-vX` (here, `X` is a monotonically increasing integer) is added if there is any breaking change in the addon image compared to the previous release. + +{{< notice type="warning" message="If you update Stash operator to a newer release and the supported addon versions in the newer release has different `-vX` suffix, you have to update the old addons too. Otherwise, backup may not work. In this case, just uninstall the old addons and install the new addons." >}} + +## Addon Version Compatibility + +Any addon with matching major version with the database version should be able to take backup of that database. For example, PerconaXtraDB addon with version `5.x.x-vX` should be able take backup of any PerconaXtraDB of `5.x.x` series. However, this might not be true for some versions. In that case, we will have separate addon for that version. + ## Documentation Overview Stash Percona XtraDB documentations are organized as below: - [How does it works?](/docs/addons/percona-xtradb/overview.md) gives an overview of how backup and restore process for Percona XtraDB database works in Stash. - [Setup](/docs/addons/percona-xtradb/setup/install.md) shows how to install and uninstall Percona XtraDB addon for Stash. -- [Guides](/docs/addons/percona-xtradb/guides/5.7/clustered.md) contains step by step guides to backup and restore different versions of Percona XtraDB databases. +- **Guides** contains step by step guides to backup and restore different versions of Percona XtraDB databases. diff --git a/docs/addons/percona-xtradb/setup/install.md b/docs/addons/percona-xtradb/setup/install.md index d63b43fc..243f9824 100644 --- a/docs/addons/percona-xtradb/setup/install.md +++ b/docs/addons/percona-xtradb/setup/install.md @@ -106,11 +106,11 @@ curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/d The flowing flags are available for customizing Percona XtraDB addon installation: -| Flag | Usage | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | -| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | -| `--image` | Specify the name of the docker image to use for respective addons. | -| `--image-tag` | Specify the tag of the docker image to use for respective addon. | -| `--xtradb-backup-args` | Specify optional arguments to pass to `xtrabackup` command during backup. These arguments apply to all Percona XtraDB instances in this cluster. To set arguments for a specific Percona XtraDB database instance, set `xtradbArgs` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | -| `--xtradb-restore-args` | Specify optional arguments to pass to `xtrabackup` command during restore. These arguments apply to all Percona XtraDB instances in this cluster. To set arguments for a specific Percona XtraDB database instance, set `xtradbArgs` parameter in `spec.task.params` field of the respective `RestoreSession`. | +| Flag | Usage | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | +| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | +| `--image` | Specify the name of the docker image to use for respective addons. | +| `--image-tag` | Specify the tag of the docker image to use for respective addon. | +| `--backup-args` | Specify optional arguments to pass to `xtrabackup` command during backup. These arguments apply to all Percona XtraDB instances in this cluster. To set arguments for a specific Percona XtraDB database instance, set `args` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | +| `--restore-args` | Specify optional arguments to pass to `xtrabackup` command during restore. These arguments apply to all Percona XtraDB instances in this cluster. To set arguments for a specific Percona XtraDB database instance, set `args` parameter in `spec.task.params` field of the respective `RestoreSession`. | diff --git a/docs/addons/postgres/README.md b/docs/addons/postgres/README.md index 1729c3bd..a69a2cf7 100644 --- a/docs/addons/postgres/README.md +++ b/docs/addons/postgres/README.md @@ -29,10 +29,18 @@ Stash supports backup and restore of the following PostgreSQL versions: {{< versionlist "postgres" "/docs/addons/postgres/guides/%s/standalone.md" >}} +Here, the addon follows `M.M.P-vX` versioning scheme where `M.M.P` (Major.Minor.Patch) represents the respective database version and an optional `-vX` (here, `X` is a monotonically increasing integer) is added if there is any breaking change in the addon image compared to the previous release. + +{{< notice type="warning" message="If you update Stash operator to a newer release and the supported addon versions in the newer release has different `-vX` suffix, you have to update the old addons too. Otherwise, backup may not work. In this case, just uninstall the old addons and install the new addons." >}} + +## Addon Version Compatibility + +Any addon with matching major version with the database version should be able to take backup of that database. For example, PostgreSQL addon with version `12.x.x-vX` should be able take backup of any PostgreSQL of `12.x.x` series. However, this might not be true for some versions. In that case, we will have separate addon for that version. + ## Documentation Overview Stash PostgreSQL documentations are organized as below: - [How does it works?](/docs/addons/postgres/overview.md) gives an overview of how backup and restore process for PostgreSQL database works in Stash. - [Setup](/docs/addons/postgres/setup/install.md) shows how to install and uninstall PostgreSQL addon for Stash. -- [Guides](/docs/addons/postgres/guides/11.2/standalone.md) contains step by step guides to backup and restore different versions of PostgreSQL databases. +- **Guides** step by step guides to backup and restore different versions of PostgreSQL databases. diff --git a/docs/addons/postgres/setup/install.md b/docs/addons/postgres/setup/install.md index 0c2e0161..204be1e2 100644 --- a/docs/addons/postgres/setup/install.md +++ b/docs/addons/postgres/setup/install.md @@ -122,11 +122,11 @@ curl -fsSL https://github.com/stashed/catalog/raw/{{< param "info.catalog" >}}/d The flowing flags are available for customizing PostgreSQL addon installation: -| Flag | Usage | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | -| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | -| `--image` | Specify the name of the docker image to use for respective addons. | -| `--image-tag` | Specify the tag of the docker image to use for respective addon. | -| `--pg-backup-args` | Specify optional arguments to pass to `pgdump` command during backup. These arguments apply to all PostgreSQL instances in this cluster. To set arguments for a specific PostgreSQL database instance, set `pgArgs` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | -| `--pg-restore-args` | Specify optional arguments to pass to `psql` command during restore. These arguments apply to all PostgreSQL instances in this cluster. To set arguments for a specific PostgreSQL database instance, set `pgArgs` parameter in `spec.task.params` field of the respective `RestoreSession`. | +| Flag | Usage | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `--version` | Specify a specific version of a specific addon to install. Use it along with `--catalog` flag. | +| `--docker-registry` | Specify the docker registry to use to pull respective addon images. Default Value: `stashed`. | +| `--image` | Specify the name of the docker image to use for respective addons. | +| `--image-tag` | Specify the tag of the docker image to use for respective addon. | +| `--backup-args` | Specify optional arguments to pass to `pgdump` command during backup. These arguments apply to all PostgreSQL instances in this cluster. To set arguments for a specific PostgreSQL database instance, set `args` parameter in `spec.task.params` field of the respective `BackupConfiguration`. | +| `--restore-args` | Specify optional arguments to pass to `psql` command during restore. These arguments apply to all PostgreSQL instances in this cluster. To set arguments for a specific PostgreSQL database instance, set `args` parameter in `spec.task.params` field of the respective `RestoreSession`. | diff --git a/docs/images/addons/mariadb/mariadb-logical-backup.svg b/docs/images/addons/mariadb/mariadb-logical-backup.svg new file mode 100644 index 00000000..04faf0ae --- /dev/null +++ b/docs/images/addons/mariadb/mariadb-logical-backup.svg @@ -0,0 +1,987 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/addons/mariadb/mariadb-logical-restore.svg b/docs/images/addons/mariadb/mariadb-logical-restore.svg new file mode 100644 index 00000000..c930c864 --- /dev/null +++ b/docs/images/addons/mariadb/mariadb-logical-restore.svg @@ -0,0 +1,857 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +