From 42dafae7bd9eea00279064a59669609e81f7fd55 Mon Sep 17 00:00:00 2001 From: sayedppqq Date: Tue, 5 Dec 2023 11:06:33 +0600 Subject: [PATCH] wip Signed-off-by: sayedppqq --- .../guides/mongodb/backup/kubestash/_index.md | 4 +- .../backup/kubestash/logical/_index.md | 10 + .../kubestash/logical/standalone/_index.md | 511 ++++++++++++++++++ .../examples/backupconfiguration.yaml | 34 ++ .../standalone/examples/backupstorage.yaml | 18 + .../standalone/examples/retentionpolicy.yaml | 12 + .../backup/kubestash/overview/_index.md | 140 ++++- .../overview/images/replicaset_backup.svg | 4 + .../overview/images/replicaset_restore.svg | 4 + .../overview/images/restore_overview.svg | 1 + .../overview/images/sharded_backup.svg | 4 + .../overview/images/sharded_restore.svg | 4 + .../overview/images/standalone_backup.svg | 4 + .../overview/images/standalone_restore.svg | 4 + 14 files changed, 750 insertions(+), 4 deletions(-) create mode 100644 docs/guides/mongodb/backup/kubestash/logical/_index.md create mode 100644 docs/guides/mongodb/backup/kubestash/logical/standalone/_index.md create mode 100644 docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupconfiguration.yaml create mode 100644 docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupstorage.yaml create mode 100644 docs/guides/mongodb/backup/kubestash/logical/standalone/examples/retentionpolicy.yaml create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/replicaset_backup.svg create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/replicaset_restore.svg create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/restore_overview.svg create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/sharded_backup.svg create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/sharded_restore.svg create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/standalone_backup.svg create mode 100644 docs/guides/mongodb/backup/kubestash/overview/images/standalone_restore.svg diff --git a/docs/guides/mongodb/backup/kubestash/_index.md b/docs/guides/mongodb/backup/kubestash/_index.md index 3c326448f2..994241ef4f 100644 --- a/docs/guides/mongodb/backup/kubestash/_index.md +++ b/docs/guides/mongodb/backup/kubestash/_index.md @@ -5,6 +5,6 @@ menu: identifier: guides-mongodb-backup-kubestash name: KubeStash Backup & Restore parent: guides-mongodb-backup - weight: 20 + weight: 50 menu_name: docs_{{ .version }} ---- +--- \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/logical/_index.md b/docs/guides/mongodb/backup/kubestash/logical/_index.md new file mode 100644 index 0000000000..1aeabf00c9 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/logical/_index.md @@ -0,0 +1,10 @@ +--- +title: Logical Backup & Restore of MongoDB | KubeStash +menu: + docs_{{ .version }}: + identifier: guides-mongodb-backup-kubestash-logical + name: Logical Backup & Restore + parent: guides-mongodb-backup-kubestash + weight: 20 +menu_name: docs_{{ .version }} +--- \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/logical/standalone/_index.md b/docs/guides/mongodb/backup/kubestash/logical/standalone/_index.md new file mode 100644 index 0000000000..1adc341583 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/logical/standalone/_index.md @@ -0,0 +1,511 @@ +--- +title: Backup & Restore Standalone MongoDB | KubeStash +description: Backup and restore standalone MongoDB database using KubeStash +menu: + docs_{{ .version }}: + identifier: guides-mongodb-backup-kubestash-logical-standalone + name: Standalone MongoDB + parent: guides-mongodb-backup-kubestash-logical + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +# Backup and Restore MongoDB database using KubeStash + +KubeStash v0.1.0+ supports backup and restoration of MongoDB databases. This guide will show you how you can backup and restore your MongoDB database with KubeStash. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using Minikube. +- Install KubeDB in your cluster following the steps [here](/docs/setup/README.md). +- Install KubeStash Enterprise in your cluster following the steps [here(link needed)](). +- Install KubeStash `kubectl` plugin following the steps [here(link needed)](). +- If you are not familiar with how KubeStash backup and restore MongoDB databases, please check the following guide [here](/docs/guides/mongodb/backup/kubestash/overview/index.md). + +You have to be familiar with following custom resources: + +- [AppBinding](/docs/guides/mongodb/concepts/appbinding.md) +- [Function](https://stash.run/docs/latest/concepts/crds/function/) +- [Task](https://stash.run/docs/latest/concepts/crds/task/) +- [BackupConfiguration](https://stash.run/docs/latest/concepts/crds/backupconfiguration/) +- [RestoreSession](https://stash.run/docs/latest/concepts/crds/restoresession/) + +To keep things isolated, we are going to use a separate namespace called `demo` throughout this tutorial. Create `demo` namespace if you haven't created yet. + +```console +$ kubectl create ns demo +namespace/demo created +``` + +## Backup MongoDB + +This section will demonstrate how to backup MongoDB database. Here, we are going to deploy a MongoDB database using KubeDB. Then, we are going to backup this database into a GCS bucket. Finally, we are going to restore the backed up data into another MongoDB database. + +### Deploy Sample MongoDB Database + +Let's deploy a sample MongoDB database and insert some data into it. + +**Create MongoDB CRD:** + +Below is the YAML of a sample MongoDB crd that we are going to create for this tutorial: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: MongoDB +metadata: + name: sample-mongodb + namespace: demo +spec: + version: "4.2.3" + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + terminationPolicy: WipeOut +``` + +Create the above `MongoDB` crd, + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mongodb/backup/logical/standalone/examples/mongodb.yaml +mongodb.kubedb.com/sample-mongodb created +``` + +KubeDB will deploy a MongoDB database according to the above specification. It will also create the necessary secrets and services to access the database. + +Let's check if the database is ready to use, + +```console +$ kubectl get mg -n demo sample-mongodb +NAME VERSION STATUS AGE +sample-mongodb 4.2.3 Ready 2m9s +``` + +The database is `Ready`. Verify that KubeDB has created a Secret and a Service for this database using the following commands, + +```console +$ kubectl get secret -n demo -l=app.kubernetes.io/instance=sample-mongodb +NAME TYPE DATA AGE +sample-mongodb-auth Opaque 2 2m28s + +$ kubectl get service -n demo -l=app.kubernetes.io/instance=sample-mongodb +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +sample-mongodb ClusterIP 10.107.58.222 27017/TCP 2m48s +sample-mongodb-gvr ClusterIP None 27017/TCP 2m48s +``` + +Here, we have to use service `sample-mongodb` and secret `sample-mongodb-auth` to connect with the database. + +**Insert Sample Data:** + +Now, we are going to exec into the database pod and create some sample data. At first, find out the database pod using the following command, + +```console +$ kubectl get pods -n demo --selector="app.kubernetes.io/instance=sample-mongodb" +NAME READY STATUS RESTARTS AGE +sample-mongodb-0 1/1 Running 0 12m +``` + +Now, let's exec into the pod and create a table, + +```console +$ export USER=$(kubectl get secrets -n demo sample-mongodb-auth -o jsonpath='{.data.\username}' | base64 -d) + +$ export PASSWORD=$(kubectl get secrets -n demo sample-mongodb-auth -o jsonpath='{.data.\password}' | base64 -d) + +$ kubectl exec -it -n demo sample-mongodb-0 -- mongo admin -u $USER -p $PASSWORD + +> show dbs +admin 0.000GB +local 0.000GB +mydb 0.000GB + +> show users +{ + "_id" : "admin.root", + "user" : "root", + "db" : "admin", + "roles" : [ + { + "role" : "root", + "db" : "admin" + } + ] +} + +> use newdb +switched to db newdb + +> db.movie.insert({"name":"batman"}); +WriteResult({ "nInserted" : 1 }) + +> db.movie.find().pretty() +{ "_id" : ObjectId("5d19d1cdc93d828f44e37735"), "name" : "batman" } + +> exit +bye +``` + +Now, we are ready to backup this sample database. + +### Prepare Backend + +We are going to store our backed up data into a S3 bucket. At first, we need to create a secret with S3 credentials then we need to create a `BackupStorage` crd. If you want to use a different backend, please read the respective backend configuration doc from [here](https://stash.run/docs/latest/guides/backends/overview/). + +**Create Storage Secret:** + +Let's create a secret called `s3-secret` with access credentials to our desired S3 bucket, + +```console +$ echo -n '' > AWS_ACCESS_KEY_ID +$ echo -n '' > AWS_SECRET_ACCESS_KEY +$ kubectl create secret generic -n demo s3-secret \ + --from-file=./RESTIC_PASSWORD \ + --from-file=./AWS_ACCESS_KEY_ID \ + --from-file=./AWS_SECRET_ACCESS_KEY +secret/s3-secret created +``` + +**Create BackupStorage:** + +Now, crete a `BackupStorage` using this secret. Below is the YAML of BackupStorage crd we are going to create, + +```yaml +apiVersion: storage.kubestash.com/v1alpha1 +kind: BackupStorage +metadata: + name: s3-storage + namespace: demo +spec: + storage: + provider: s3 + s3: + endpoint: us-east-1.linodeobjects.com + bucket: kubestash-testing + region: us-east-1 + prefix: demo + secret: s3-secret + usagePolicy: + allowedNamespaces: + from: All + deletionPolicy: WipeOut +``` + +Let's create the `BackupStorage` we have shown above, + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupstorage.yaml +storage.kubestash.com/s3-storage created +``` + +Now, we are ready to backup our database to our desired backend. + +### Backup + +We have to create a `BackupConfiguration` targeting respective MongoDB crd of our desired database. Then KubeStash will create a CronJob to periodically backup the database. + +**Create Encryption Secret:** + +EncryptionSecret refers to the Secret containing the encryption key which will be used to encode/decode the backed up data. Let's create a secret called `encry-secret` + +```console +$ kubectl create secret generic encry-secret -n demo \ + --from-literal=RESTIC_PASSWORD='123' -n demo +secret/encry-secret created +``` + +**Create Retention Policy:** + +`RetentionPolicy` specifies how the old Snapshots should be cleaned up. This is a namespaced CRD.However, we can refer it from other namespaces as long as it is permitted via `.spec.usagePolicy`. Below is the YAML of the `RetentionPolicy` called `backup-rp` + +```console +apiVersion: storage.kubestash.com/v1alpha1 +kind: RetentionPolicy +metadata: + name: backup-rp + namespace: demo +spec: + maxRetentionPeriod: 2mo + successfulSnapshots: + last: 10 + usagePolicy: + allowedNamespaces: + from: All +``` + +Let's create the RetentionPolicy we have shown above, + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/retentionpolicy.yaml +retentionpolicy.storage.kubestash.com/backup-rp created +``` + +**Create BackupConfiguration:** + +As we just create our encryption secret and retention policy, we are now ready to apply `BackupConfiguration` crd to take backup out database. + +Below is the YAML for `BackupConfiguration` crd to backup the `sample-mongodb` database we have deployed earlier., + +```yaml +apiVersion: core.kubestash.com/v1alpha1 +kind: BackupConfiguration +metadata: + name: sample-mongodb-backup + namespace: demo +spec: + target: + apiGroup: kubedb.com + kind: MongoDB + namespace: demo + name: sample-mongodb + backends: + - name: s3-backend + storageRef: + namespace: demo + name: s3-storage + retentionPolicy: + name: backup-rp + namespace: demo + sessions: + - name: frequent-backup + scheduler: + schedule: "*/5 * * * *" + repositories: + - name: s3-repo + backend: s3-backend + directory: /mongodb + encryptionSecret: + name: encry-secret + namespace: demo + addon: + name: mongodb-addon + tasks: + - name: LogicalBackup +``` + +Here, + +- `spec.target` specifies our targeted `MongoDB` database. +- `spec.backends` specifies `BackupStorage` information for storing data. +- `spec.sessions` specifies common session configurations for this backup +- `spec.sessions.schedule` specifies that we want to backup the database at 5 minutes interval. +- `spec.sessions.addon` refers to the `Addon` crd for backup task + +Let's create the `BackupConfiguration` crd we have shown above, + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupconfiguration.yaml +backupconfiguration.core.kubestash.com/sample-mongodb-backup created +``` + +**Verify Backup Setup Successful:** + +If everything goes well, the phase of the `BackupConfiguration` should be `Ready`. The `Ready` phase indicates that the backup setup is successful. Let's verify the `Phase` of the BackupConfiguration, + +```console +$ kubectl get backupconfiguration -n demo +NAME TASK PAUSED PHASE AGE +sample-mongodb-backup mongodb-backup-4.2.3 Ready 11s +``` + +**Verify CronJob:** + +KubeStash will create a CronJob with the schedule specified in `spec.schedule` field of `BackupConfiguration` crd. + +Verify that the CronJob has been created using the following command, + +```console +$ kubectl get cronjob -n demo +NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE +sample-mongodb-backup */5 * * * * False 0 61s +``` + +**Wait for BackupSession:** + +The `sample-mongodb-backup` CronJob will trigger a backup on each schedule by creating a `BackpSession` crd. + +Wait for the next schedule. Run the following command to watch `BackupSession` crd, + +```console +$ kubectl get backupsession -n demo -w +NAME INVOKER-TYPE INVOKER-NAME PHASE AGE +sample-mongodb-backup-frequent-backup-1701867722 BackupConfiguration sample-mongodb-backup Running 5m19s +sample-mongodb-backup-1561974001 BackupConfiguration sample-mongodb-backup Succeeded 5m45s +``` + +We can see above that the backup session has succeeded. Now, we are going to verify that the backed up data has been stored in the backend. + +**Verify Backup:** + +Once a backup is complete, KubeStash will update the respective `Snapshot` crd to reflect the backup. It will be created when a backup is triggered. Check that the `Snapshot` Phase to verify backup. + +```console +$ kubectl get snapshot -n demo + +``` + + +Once a backup is complete, KubeStash will update the respective `Repository` crd to reflect the backup. Check that the repository `gcs-repo` has been updated by the following command, + +```console +$ kubectl get repository -n demo gcs-repo +NAME INTEGRITY SIZE SNAPSHOT-COUNT LAST-SUCCESSFUL-BACKUP AGE +gcs-repo true 1.611 KiB 1 33s 33m +``` + +Now, if we navigate to the GCS bucket, we are going to see backed up data has been stored in `demo/mongodb/sample-mongodb` directory as specified by `spec.backend.gcs.prefix` field of Repository crd. + +> Note: KubeStash keeps all the backed up data encrypted. So, data in the backend will not make any sense until they are decrypted. + +## Restore MongoDB +You can restore your data into the same database you have backed up from or into a different database in the same cluster or a different cluster. In this section, we are going to show you how to restore in the same database which may be necessary when you have accidentally deleted any data from the running database. + +#### Stop Taking Backup of the Old Database: + +At first, let's stop taking any further backup of the old database so that no backup is taken during restore process. We are going to pause the `BackupConfiguration` crd that we had created to backup the `sample-mongodb` database. Then, KubeStash will stop taking any further backup for this database. + +Let's pause the `sample-mongodb-backup` BackupConfiguration, +```bash +$ kubectl patch backupconfiguration -n demo sample-mongodb-backup --type="merge" --patch='{"spec": {"paused": true}}' +backupconfiguration.stash.appscode.com/sample-mongodb-backup patched +``` + +Or you can use the KubeStash `kubectl` plugin to pause the `BackupConfiguration`, +```bash +$ kubectl stash pause backup -n demo --backupconfig=sample-mongodb-backup +BackupConfiguration demo/sample-mongodb-backup has been paused successfully. +``` + +Now, wait for a moment. KubeStash will pause the BackupConfiguration. Verify that the BackupConfiguration has been paused, + +```console +$ kubectl get backupconfiguration -n demo sample-mongodb-backup +NAME TASK SCHEDULE PAUSED PHASE AGE +sample-mongodb-backup mongodb-backup-4.2.3 */5 * * * * true Ready 26m +``` + +Notice the `PAUSED` column. Value `true` for this field means that the BackupConfiguration has been paused. + +#### Simulate Disaster: + +Now, let’s simulate an accidental deletion scenario. Here, we are going to exec into the database pod and delete the `newdb` database we had created earlier. +```console +$ kubectl exec -it -n demo sample-mongodb-0 -- mongo admin -u $USER -p $PASSWORD +> use newdb +switched to db newdb + +> db.dropDatabase() +{ "dropped" : "newdb", "ok" : 1 } + +> show dbs +admin 0.000GB +config 0.000GB +local 0.000GB + +> exit +bye +``` +#### Create RestoreSession: + +Now, we need to create a `RestoreSession` crd pointing to the AppBinding of `sample-mongodb` database. +Below is the YAML for the `RestoreSession` crd that we are going to create to restore the backed up data. + +```yaml +apiVersion: stash.appscode.com/v1beta1 +kind: RestoreSession +metadata: + name: sample-mongodb-restore + namespace: demo +spec: + repository: + name: gcs-repo + target: + ref: + apiVersion: appcatalog.appscode.com/v1alpha1 + kind: AppBinding + name: sample-mongodb + rules: + - snapshots: [latest] +``` + +Here, + +- `spec.repository.name` specifies the `Repository` crd that holds the backend information where our backed up data has been stored. +- `spec.target.ref` refers to the AppBinding crd for the `restored-mongodb` database. +- `spec.rules` specifies that we are restoring from the latest backup snapshot of the database. + +Let's create the `RestoreSession` crd we have shown above, + +```console +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mongodb/backup/logical/standalone/examples/restoresession.yaml +restoresession.stash.appscode.com/sample-mongodb-restore created +``` + +Once, you have created the `RestoreSession` crd, KubeStash will create a job to restore. We can watch the `RestoreSession` phase to check if the restore process is succeeded or not. + +Run the following command to watch `RestoreSession` phase, + +```console +$ kubectl get restoresession -n demo sample-mongodb-restore -w +NAME REPOSITORY-NAME PHASE AGE +sample-mongodb-restore gcs-repo Running 5s +sample-mongodb-restore gcs-repo Succeeded 43s +``` + +So, we can see from the output of the above command that the restore process succeeded. + +#### Verify Restored Data: + +In this section, we are going to verify that the desired data has been restored successfully. We are going to connect to the database and check whether the table we had created earlier is restored or not. + +Lets, exec into the database pod and list available tables, + +```console +$ kubectl exec -it -n demo sample-mongodb-0 -- mongo admin -u $USER -p $PASSWORD + +> show dbs +admin 0.000GB +config 0.000GB +local 0.000GB +newdb 0.000GB + +> show users +{ + "_id" : "admin.root", + "user" : "root", + "db" : "admin", + "roles" : [ + { + "role" : "root", + "db" : "admin" + } + ] +} + +> use newdb +switched to db newdb + +> db.movie.find().pretty() +{ "_id" : ObjectId("5d19d1cdc93d828f44e37735"), "name" : "batman" } + +> exit +bye +``` + +So, from the above output, we can see the database `newdb` that we had created earlier is restored. + +## Cleanup + +To cleanup the Kubernetes resources created by this tutorial, run: + +```console +kubectl delete -n demo restoresession sample-mongodb-restore sample-mongo +kubectl delete -n demo backupconfiguration sample-mongodb-backup +kubectl delete -n demo mg sample-mongodb +kubectl delete -n demo repository gcs-repo +``` diff --git a/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupconfiguration.yaml b/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupconfiguration.yaml new file mode 100644 index 0000000000..280461f831 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupconfiguration.yaml @@ -0,0 +1,34 @@ +apiVersion: core.kubestash.com/v1alpha1 +kind: BackupConfiguration +metadata: + name: sample-mongodb-backup + namespace: demo +spec: + target: + apiGroup: kubedb.com + kind: MongoDB + namespace: demo + name: sample-mongodb + backends: + - name: s3-backend + storageRef: + namespace: demo + name: s3-storage + retentionPolicy: + name: backup-rp + namespace: demo + sessions: + - name: frequent-backup + scheduler: + schedule: "*/2 * * * *" + repositories: + - name: s3-repo + backend: s3-backend + directory: /mongodb + encryptionSecret: + name: encry-secret + namespace: demo + addon: + name: mongodb-addon + tasks: + - name: LogicalBackup \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupstorage.yaml b/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupstorage.yaml new file mode 100644 index 0000000000..0eeb7f1ab7 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/backupstorage.yaml @@ -0,0 +1,18 @@ +apiVersion: storage.kubestash.com/v1alpha1 +kind: BackupStorage +metadata: + name: s3-storage + namespace: demo +spec: + storage: + provider: s3 + s3: + endpoint: us-east-1.linodeobjects.com + bucket: kubestash-testing + region: us-east-1 + prefix: demo + secret: s3-secret + usagePolicy: + allowedNamespaces: + from: All + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/retentionpolicy.yaml b/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/retentionpolicy.yaml new file mode 100644 index 0000000000..3d327f9a71 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/logical/standalone/examples/retentionpolicy.yaml @@ -0,0 +1,12 @@ +apiVersion: storage.kubestash.com/v1alpha1 +kind: RetentionPolicy +metadata: + name: backup-rp + namespace: demo +spec: + maxRetentionPeriod: 2mo + successfulSnapshots: + last: 10 + usagePolicy: + allowedNamespaces: + from: All \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/_index.md b/docs/guides/mongodb/backup/kubestash/overview/_index.md index 07c97376d8..19a83ab11f 100644 --- a/docs/guides/mongodb/backup/kubestash/overview/_index.md +++ b/docs/guides/mongodb/backup/kubestash/overview/_index.md @@ -7,7 +7,6 @@ menu: parent: guides-mongodb-backup-kubestash weight: 10 menu_name: docs_{{ .version }} -section_menu_id: guides --- > New to KubeDB? Please start [here](/docs/README.md). @@ -25,4 +24,141 @@ The following diagram shows how KubeStash takes backup of a MongoDB database. Op
MongoDB Backup Overview
Fig: MongoDB Backup Overview
-
\ No newline at end of file + + +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 `BackupStorage` 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 crd of the desired `MongoDB` database. The `BackupConfiguration` object also specifies the `Sessions` to use to backup the database. + +4. KubeStash operator watches for `BackupConfiguration` crd. + +5. Once KubeStash 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. KubeStash operator also watches for `BackupSession` crd. + +8. When it finds a `BackupSession` object, It creates a `Snapshot` for holding backup information. + +9. KubeStash resolves the respective `Addon` and `Function` and prepares a Job definition to backup. + +10. Then, it creates the Job to backup the targeted database. + +11. The backup Job reads necessary information to connect with the database from the `AppBinding` crd of the targated `MongoDB` database. It also reads backend information and access credentials from `BackupStorage` crd and Storage Secret respectively through `Backend` section of `BackupConfiguration` crd + +12. Then, the Job dumps the targeted database and uploads the output to the backend. KubeStash pipes the output of dump command to uploading process. Hence, backup Job does not require a large volume to hold the entire dump output. + +13. Finally, when the backup is complete, the Job sends Prometheus metrics to the Pushgateway running inside KubeStash operator pod. It also updates the `BackupSession` and `Snapshot` status to reflect the backup procedure. + +### Backup Different MongoDB Configurations + +This section will show you how backup works for different MongoDB configurations. + +#### Standalone MongoDB + +For a standalone MongoDB database, the backup job directly dumps the database using `mongodump` and pipe the output to the backup process. + +
+ Standalone MongoDB Backup Overview +
Fig: Standalone MongoDB Backup
+
+ +#### MongoDB ReplicaSet Cluster + +For MongoDB ReplicaSet cluster, KubeStash takes backup from one of the secondary replicas. The backup process consists of the following steps: + +1. Identify a secondary replica. +2. Lock the secondary replica. +3. Backup the secondary replica. +4. Unlock the secondary replica. + +
+ MongoDB ReplicaSet Cluster Backup Overview +
Fig: MongoDB ReplicaSet Cluster Backup
+
+ +#### MongoDB Sharded Cluster + +For MongoDB sharded cluster, KubeStash takes backup of the individual shards as well as the config server. KubeStash takes backup from a secondary replica of the shards and the config server. If there is no secondary replica then KubeStash will take backup from the primary replica. The backup process consists of the following steps: + +1. Disable balancer. +2. Lock config server. +3. Identify a secondary replica for each shard. +4. Lock the secondary replica. +5. Run backup on the secondary replica. +6. Unlock the secondary replica. +7. Unlock config server. +8. Enable balancer. + +
+ MongoDB Sharded Cluster Backup Overview +
Fig: MongoDB Sharded Cluster Backup
+
+ +## How Restore Process Works + +The following diagram shows how KubeStash restores backed up data into a MongoDB database. Open the image in a new tab to see the enlarged version. + +
+ Database Restore Overview +
Fig: MongoDB 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. KubeStash 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. KubeStash 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. + +### Restoring Different MongoDB Configurations + +This section will show you restore process works for different MongoDB configurations. + +#### Standalone MongoDB + +For a standalone MongoDB database, the restore job downloads the backed up data from the backend and pipe the downloaded data to `mongorestore` command which inserts the data into the desired MongoDB database. + +
+ Standalone MongoDB Restore Overview +
Fig: Standalone MongoDB Restore
+
+ +#### MongoDB ReplicaSet Cluster + +For MongoDB ReplicaSet cluster, KubeStash identifies the primary replica and restore into it. + +
+ MongoDB ReplicaSet Cluster Restore Overview +
Fig: MongoDB ReplicaSet Cluster Restore
+
+ +#### MongoDB Sharded Cluster + +For MongoDB sharded cluster, KubeStash identifies the primary replica of each shard as well as the config server and restore respective backed up data into them. + +
+ MongoDB Sharded Cluster Restore +
Fig: MongoDB Sharded Cluster Restore
+
+ +## Next Steps + +- Backup a standalone MongoDB databases using Stash following the guide from [here](/docs/guides/mongodb/backup/logical/standalone/index.md). +- Backup a MongoDB Replicaset cluster using Stash following the guide from [here](/docs/guides/mongodb/backup/logical/replicaset/index.md). +- Backup a sharded MongoDB cluster using Stash following the guide from [here](/docs/guides/mongodb/backup/logical/sharding/index.md). + + diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/replicaset_backup.svg b/docs/guides/mongodb/backup/kubestash/overview/images/replicaset_backup.svg new file mode 100644 index 0000000000..e41cdcc771 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/replicaset_backup.svg @@ -0,0 +1,4 @@ + + + +
KubeStash
Backup Job
KubeStash...
R1
R1
R2
R2
R3
R3
MongoDB
ReplicaSet
Cluster
MongoDB...
Primary
Primary
Secondary
Secondary
Secondary
Secondary
mongodump
mongodumpText is not SVG - cannot display \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/replicaset_restore.svg b/docs/guides/mongodb/backup/kubestash/overview/images/replicaset_restore.svg new file mode 100644 index 0000000000..c6cfa868ba --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/replicaset_restore.svg @@ -0,0 +1,4 @@ + + + +
KubeStash
Backup Job
KubeStash...
R1
R1
R2
R2
R3
R3
MongoDB
ReplicaSet
Cluster
MongoDB...
Primary
Primary
Secondary
Secondary
Secondary
Secondary
mongodump
mongodumpText is not SVG - cannot display \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/restore_overview.svg b/docs/guides/mongodb/backup/kubestash/overview/images/restore_overview.svg new file mode 100644 index 0000000000..2b587b058a --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/restore_overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/sharded_backup.svg b/docs/guides/mongodb/backup/kubestash/overview/images/sharded_backup.svg new file mode 100644 index 0000000000..3e0b4cb461 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/sharded_backup.svg @@ -0,0 +1,4 @@ + + + +
KubeStash
Backup Job
KubeStash...
R1
R1
R2
R2
R3
R3
MongoDB
ReplicaSet
Cluster
MongoDB...
Primary
Primary
Secondary
Secondary
Secondary
Secondary
mongodump
mongodumpText is not SVG - cannot display \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/sharded_restore.svg b/docs/guides/mongodb/backup/kubestash/overview/images/sharded_restore.svg new file mode 100644 index 0000000000..25b7126c02 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/sharded_restore.svg @@ -0,0 +1,4 @@ + + + +
KubeStash
Backup Job
KubeStash...
R1
R1
R2
R2
R3
R3
MongoDB
ReplicaSet
Cluster
MongoDB...
Primary
Primary
Secondary
Secondary
Secondary
Secondary
mongodump
mongodumpText is not SVG - cannot display \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/standalone_backup.svg b/docs/guides/mongodb/backup/kubestash/overview/images/standalone_backup.svg new file mode 100644 index 0000000000..47eb24665c --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/standalone_backup.svg @@ -0,0 +1,4 @@ + + + +
KubeStash
Backup Job
KubeStash...
MongoDB
MongoDB
mongodump
mongodumpText is not SVG - cannot display \ No newline at end of file diff --git a/docs/guides/mongodb/backup/kubestash/overview/images/standalone_restore.svg b/docs/guides/mongodb/backup/kubestash/overview/images/standalone_restore.svg new file mode 100644 index 0000000000..1c72f07bb7 --- /dev/null +++ b/docs/guides/mongodb/backup/kubestash/overview/images/standalone_restore.svg @@ -0,0 +1,4 @@ + + + +
KubeStash
Backup Job
KubeStash...
R1
R1
R2
R2
R3
R3
MongoDB
ReplicaSet
Cluster
MongoDB...
Primary
Primary
Secondary
Secondary
Secondary
Secondary
mongodump
mongodumpText is not SVG - cannot display \ No newline at end of file