diff --git a/docs/guides/postgres/README.md b/docs/guides/postgres/README.md index 08ef9fe1b..7cc813080 100644 --- a/docs/guides/postgres/README.md +++ b/docs/guides/postgres/README.md @@ -46,7 +46,7 @@ aliases: ## User Guide - [Quickstart PostgreSQL](/docs/guides/postgres/quickstart/quickstart.md) with KubeDB Operator. -- How to [Backup & Restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- How to [Backup & Restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Initialize [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - [PostgreSQL Clustering](/docs/guides/postgres/clustering/ha_cluster.md) supported by KubeDB Postgres. - [Streaming Replication](/docs/guides/postgres/clustering/streaming_replication.md) for PostgreSQL clustering. diff --git a/docs/guides/postgres/backup/kubestash/_index.md b/docs/guides/postgres/backup/kubestash/_index.md new file mode 100644 index 000000000..caac7f4da --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/_index.md @@ -0,0 +1,10 @@ +--- +title: Backup & Restore PostgreSQL | KubeStash +menu: + docs_{{ .version }}: + identifier: guides-pg-backup-stashv2 + name: KubeStash (aka Stash 2.0) + parent: guides-pg-backup + weight: 40 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/postgres/backup/kubestash/logical/examples/backupconfiguration.yaml b/docs/guides/postgres/backup/kubestash/logical/examples/backupconfiguration.yaml new file mode 100644 index 000000000..ddc74e3a7 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/examples/backupconfiguration.yaml @@ -0,0 +1,36 @@ +apiVersion: core.kubestash.com/v1alpha1 +kind: BackupConfiguration +metadata: + name: sample-postgres-backup + namespace: demo +spec: + target: + apiGroup: kubedb.com + kind: Postgres + namespace: demo + name: sample-postgres + backends: + - name: gcs-backend + storageRef: + namespace: demo + name: gcs-storage + retentionPolicy: + name: demo-retention + namespace: demo + sessions: + - name: frequent-backup + scheduler: + schedule: "*/5 * * * *" + jobTemplate: + backoffLimit: 1 + repositories: + - name: gcs-postgres-repo + backend: gcs-backend + directory: /postgres + encryptionSecret: + name: encrypt-secret + namespace: demo + addon: + name: postgres-addon + tasks: + - name: logical-backup \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/logical/examples/backupstorage.yaml b/docs/guides/postgres/backup/kubestash/logical/examples/backupstorage.yaml new file mode 100644 index 000000000..0461b2676 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/examples/backupstorage.yaml @@ -0,0 +1,17 @@ +apiVersion: storage.kubestash.com/v1alpha1 +kind: BackupStorage +metadata: + name: gcs-storage + namespace: demo +spec: + storage: + provider: gcs + gcs: + bucket: kubestash-qa + prefix: demo + secretName: gcs-secret + usagePolicy: + allowedNamespaces: + from: All + default: true + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/logical/examples/restored-postgres.yaml b/docs/guides/postgres/backup/kubestash/logical/examples/restored-postgres.yaml new file mode 100644 index 000000000..d1581f520 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/examples/restored-postgres.yaml @@ -0,0 +1,20 @@ +apiVersion: kubedb.com/v1 +kind: Postgres +metadata: + name: restored-postgres + namespace: demo +spec: + init: + waitForInitialRestore: true + version: "16.4" + replicas: 3 + standbyMode: Hot + streamingMode: Synchronous + storageType: Durable + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/logical/examples/restoresession.yaml b/docs/guides/postgres/backup/kubestash/logical/examples/restoresession.yaml new file mode 100644 index 000000000..1bcb3e5a8 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/examples/restoresession.yaml @@ -0,0 +1,21 @@ +apiVersion: core.kubestash.com/v1alpha1 +kind: RestoreSession +metadata: + name: sample-postgres-restore + namespace: demo +spec: + target: + apiGroup: kubedb.com + kind: Postgres + namespace: demo + name: restored-postgres + dataSource: + repository: gcs-postgres-repo + snapshot: latest + encryptionSecret: + name: encrypt-secret + namespace: demo + addon: + name: postgres-addon + tasks: + - name: logical-backup-restore \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/logical/examples/retentionpolicy.yaml b/docs/guides/postgres/backup/kubestash/logical/examples/retentionpolicy.yaml new file mode 100644 index 000000000..459156286 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/examples/retentionpolicy.yaml @@ -0,0 +1,15 @@ +apiVersion: storage.kubestash.com/v1alpha1 +kind: RetentionPolicy +metadata: + name: demo-retention + namespace: demo +spec: + default: true + failedSnapshots: + last: 2 + maxRetentionPeriod: 2mo + successfulSnapshots: + last: 5 + usagePolicy: + allowedNamespaces: + from: All \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/logical/examples/sample-postgres.yaml b/docs/guides/postgres/backup/kubestash/logical/examples/sample-postgres.yaml new file mode 100644 index 000000000..0ec4e3628 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/examples/sample-postgres.yaml @@ -0,0 +1,18 @@ +apiVersion: kubedb.com/v1 +kind: Postgres +metadata: + name: sample-postgres + namespace: demo +spec: + version: "16.4" + replicas: 3 + standbyMode: Hot + streamingMode: Synchronous + storageType: Durable + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/logical/index.md b/docs/guides/postgres/backup/kubestash/logical/index.md new file mode 100644 index 000000000..785a9931a --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/logical/index.md @@ -0,0 +1,759 @@ +--- +title: Backup & Restore PostgreSQL | KubeStash +description: Backup ans Restore PostgreSQL database using KubeStash +menu: + docs_{{ .version }}: + identifier: guides-pg-logical-backup-stashv2 + name: Logical Backup + parent: guides-pg-backup-stashv2 + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +# Backup and Restore PostgreSQL database using KubeStash + +KubeStash allows you to backup and restore `PostgreSQL` databases. It supports backups for `PostgreSQL` instances running in Standalone, Group Replication, and InnoDB cluster configurations. KubeStash makes managing your `PostgreSQL` backups and restorations more straightforward and efficient. + +This guide will give you how you can take backup and restore your `PostgreSQL` databases using `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` or `Kind`. +- Install `KubeDB` in your cluster following the steps [here](/docs/setup/README.md). +- Install `KubeStash` in your cluster following the steps [here](https://kubestash.com/docs/latest/setup/install/kubestash). +- Install KubeStash `kubectl` plugin following the steps [here](https://kubestash.com/docs/latest/setup/install/kubectl-plugin/). +- If you are not familiar with how KubeStash backup and restore PostgreSQL databases, please check the following guide [here](/docs/guides/postgres/backup/kubestash/overview/index.md). + +You should be familiar with the following `KubeStash` concepts: + +- [BackupStorage](https://kubestash.com/docs/latest/concepts/crds/backupstorage/) +- [BackupConfiguration](https://kubestash.com/docs/latest/concepts/crds/backupconfiguration/) +- [BackupSession](https://kubestash.com/docs/latest/concepts/crds/backupsession/) +- [RestoreSession](https://kubestash.com/docs/latest/concepts/crds/restoresession/) +- [Addon](https://kubestash.com/docs/latest/concepts/crds/addon/) +- [Function](https://kubestash.com/docs/latest/concepts/crds/function/) +- [Task](https://kubestash.com/docs/latest/concepts/crds/addon/#task-specification) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/guides/postgres/backup/kubestash/logical/examples](docs/guides/postgres/backup/kubestash/logical/examples) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +## Backup PostgreSQL +KubeStash supports backups for `PostgreSQL` instances across different configurations, including Standalone and HA Cluster setups. In this demonstration, we'll focus on a `PostgreSQL` database using HA cluster configuration. The backup and restore process is similar for Standalone configurations. + + +This section will demonstrate how to backup a `PostgreSQL` database. Here, we are going to deploy a `PostgreSQL` database using KubeDB. Then, we are going to backup this database into a `GCS` bucket. Finally, we are going to restore the backup up data into another `PostgreSQL` database. + + +### Deploy Sample PostgreSQL Database + +Let's deploy a sample `PostgreSQL` database and insert some data into it. + +**Create PostgreSQL CR:** + +Below is the YAML of a sample `PostgreSQL` CR that we are going to create for this tutorial: + +```yaml +apiVersion: kubedb.com/v1 +kind: Postgres +metadata: + name: sample-postgres + namespace: demo +spec: + version: "16.4" + replicas: 3 + standbyMode: Hot + streamingMode: Synchronous + storageType: Durable + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Create the above `PostgreSQL` CR, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/kubestash/logical/examples/sample-postgres.yaml +postgres.kubedb.com/sample-postgres created +``` + +KubeDB will deploy a `PostgreSQL` 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, + +```bash +$ kubectl get pg -n demo sample-postgres +NAME VERSION STATUS AGE +sample-postgres 16.4 Ready 5m1s +``` + +The database is `Ready`. Verify that KubeDB has created a `Secret` and a `Service` for this database using the following commands, + +```bash +$ kubectl get secret -n demo +NAME TYPE DATA AGE +sample-postgres-auth kubernetes.io/basic-auth 2 5m20s + +$ kubectl get service -n demo -l=app.kubernetes.io/instance=sample-postgres +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +sample-postgres ClusterIP 10.96.23.177 5432/TCP,2379/TCP 5m55s +sample-postgres-pods ClusterIP None 5432/TCP,2380/TCP,2379/TCP 5m55s +sample-postgres-standby ClusterIP 10.96.26.118 5432/TCP 5m55s +``` + +Here, we have to use services `sample-postgres` and secret `sample-postgres-auth` to connect with the database. `KubeDB` creates an [AppBinding](/docs/guides/postgres/concepts/appbinding.md) CR that holds the necessary information to connect with the database. + + +**Verify AppBinding:** + +Verify that the `AppBinding` has been created successfully using the following command, + +```bash +$ kubectl get appbindings -n demo +NAME TYPE VERSION AGE +sample-postgres kubedb.com/postgres 16.4 9m30s +``` + +Let's check the YAML of the above `AppBinding`, + +```bash +$ kubectl get appbindings -n demo sample-postgres -o yaml +``` + +```yaml +apiVersion: appcatalog.appscode.com/v1alpha1 +kind: AppBinding +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: | + {"apiVersion":"kubedb.com/v1","kind":"Postgres","metadata":{"annotations":{},"name":"sample-postgres","namespace":"demo"},"spec":{"deletionPolicy":"DoNotTerminate","replicas":3,"standbyMode":"Hot","storage":{"accessModes":["ReadWriteOnce"],"resources":{"requests":{"storage":"1Gi"}}},"storageType":"Durable","streamingMode":"Synchronous","version":"16.4"}} + creationTimestamp: "2024-09-04T10:07:04Z" + generation: 1 + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: sample-postgres + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: postgreses.kubedb.com + name: sample-postgres + namespace: demo + ownerReferences: + - apiVersion: kubedb.com/v1 + blockOwnerDeletion: true + controller: true + kind: Postgres + name: sample-postgres + uid: 0810a96c-a2b6-4e8a-a70a-51753660450c + resourceVersion: "245972" + uid: 73bdba85-c932-464b-93a8-7f1ba8dfff1b +spec: + appRef: + apiGroup: kubedb.com + kind: Postgres + name: sample-postgres + namespace: demo + clientConfig: + service: + name: sample-postgres + path: / + port: 5432 + query: sslmode=disable + scheme: postgresql + parameters: + apiVersion: appcatalog.appscode.com/v1alpha1 + kind: StashAddon + stash: + addon: + backupTask: + name: postgres-backup-16.1 + restoreTask: + name: postgres-restore-16.1 + secret: + name: sample-postgres-auth + type: kubedb.com/postgres + version: "16.4" +``` + +KubeStash uses the `AppBinding` CR to connect with the target database. It requires the following two fields to set in AppBinding's `.spec` section. + +Here, + +- `.spec.clientConfig.service.name` specifies the name of the Service that connects to the database. +- `.spec.secret` specifies the name of the Secret that holds necessary credentials to access the database. +- `spec.type` specifies the types of the app that this AppBinding is pointing to. KubeDB generated AppBinding follows the following format: `/`. + + +**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, + +```bash +$ kubectl get pods -n demo --selector="app.kubernetes.io/instance=sample-postgres" +NAME READY STATUS RESTARTS AGE +sample-postgres-0 2/2 Running 0 16m +sample-postgres-1 2/2 Running 0 13m +sample-postgres-2 2/2 Running 0 13m +``` + +Now, let’s exec into the pod and create a table, + +```bash +$ kubectl exec -it -n demo sample-postgres-0 -- sh + +# login as "postgres" superuser. +/ $ psql -U postgres +psql (16.4) +Type "help" for help. + +# list available databases +postgres=# \l + List of databases + Name | Owner | Encoding | Locale Provider | Collate | Ctype | ICU Locale | ICU Rules | Access privileges +---------------+----------+----------+-----------------+------------+------------+------------+-----------+----------------------- + kubedb_system | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + postgres | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + template0 | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | =c/postgres + + | | | | | | | | postgres=CTc/postgres + template1 | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | =c/postgres + + | | | | | | | | postgres=CTc/postgres +(4 rows) + +# create a database named "demo" +postgres=# create database demo; +CREATE DATABASE + +# verify that the "demo" database has been created +postgres=# \l + List of databases + Name | Owner | Encoding | Locale Provider | Collate | Ctype | ICU Locale | ICU Rules | Access privileges +---------------+----------+----------+-----------------+------------+------------+------------+-----------+----------------------- + demo | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + kubedb_system | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + postgres | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + template0 | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | =c/postgres + + | | | | | | | | postgres=CTc/postgres + template1 | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | =c/postgres + + | | | | | | | | postgres=CTc/postgres +(5 rows) + +# connect to the "demo" database +postgres=# \c demo +You are now connected to database "demo" as user "postgres". + +# create a sample table +demo=# CREATE TABLE COMPANY( NAME TEXT NOT NULL, EMPLOYEE INT NOT NULL); +CREATE TABLE + +# verify that the table has been created +demo=# \d + List of relations + Schema | Name | Type | Owner +--------+---------+-------+---------- + public | company | table | postgres +(1 row) + +# quit from the database +demo=# \q + +# exit from the pod +/ $ exit +``` + +Now, we are ready to backup the database. + +### Prepare Backend + +We are going to store our backed up data into a GCS bucket. We have to create a Secret with necessary credentials and a `BackupStorage` CR to use this backend. If you want to use a different backend, please read the respective backend configuration doc from [here](https://kubestash.com/docs/latest/guides/backends/overview/). + +**Create Secret:** + +Let's create a secret called `gcs-secret` with access credentials to our desired GCS bucket, + +```bash +$ echo -n '' > GOOGLE_PROJECT_ID +$ cat /path/to/downloaded-sa-key.json > GOOGLE_SERVICE_ACCOUNT_JSON_KEY +$ kubectl create secret generic -n demo gcs-secret \ + --from-file=./GOOGLE_PROJECT_ID \ + --from-file=./GOOGLE_SERVICE_ACCOUNT_JSON_KEY +secret/gcs-secret created +``` + +**Create BackupStorage:** + +Now, create a `BackupStorage` using this secret. Below is the YAML of `BackupStorage` CR we are going to create, + +```yaml +apiVersion: storage.kubestash.com/v1alpha1 +kind: BackupStorage +metadata: + name: gcs-storage + namespace: demo +spec: + storage: + provider: gcs + gcs: + bucket: kubestash-qa + prefix: demo + secretName: gcs-secret + usagePolicy: + allowedNamespaces: + from: All + default: true + deletionPolicy: WipeOut +``` + +Let's create the BackupStorage we have shown above, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/kubestash/logical/examples/backupstorage.yaml +backupstorage.storage.kubestash.com/gcs-storage created +``` + +Now, we are ready to backup our database to our desired backend. + +**Create RetentionPolicy:** + +Now, let's create a `RetentionPolicy` to specify how the old Snapshots should be cleaned up. + +Below is the YAML of the `RetentionPolicy` object that we are going to create, + +```yaml +apiVersion: storage.kubestash.com/v1alpha1 +kind: RetentionPolicy +metadata: + name: demo-retention + namespace: demo +spec: + default: true + failedSnapshots: + last: 2 + maxRetentionPeriod: 2mo + successfulSnapshots: + last: 5 + usagePolicy: + allowedNamespaces: + from: All +``` + +Let’s create the above `RetentionPolicy`, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/kubestash/logical/examples/retentionpolicy.yaml +retentionpolicy.storage.kubestash.com/demo-retention created +``` + +### Backup + +We have to create a `BackupConfiguration` targeting respective `sample-postgres` PostgreSQL database. Then, KubeStash will create a `CronJob` for each session to take periodic backup of that database. + +At first, we need to create a secret with a Restic password for backup data encryption. + +**Create Secret:** + +Let's create a secret called `encrypt-secret` with the Restic password, + +```bash +$ echo -n 'changeit' > RESTIC_PASSWORD +$ kubectl create secret generic -n demo encrypt-secret \ + --from-file=./RESTIC_PASSWORD \ +secret "encrypt-secret" created +``` + +Below is the YAML for `BackupConfiguration` CR to backup the `sample-postgres` database that we have deployed earlier, + +```yaml +apiVersion: core.kubestash.com/v1alpha1 +kind: BackupConfiguration +metadata: + name: sample-postgres-backup + namespace: demo +spec: + target: + apiGroup: kubedb.com + kind: Postgres + namespace: demo + name: sample-postgres + backends: + - name: gcs-backend + storageRef: + namespace: demo + name: gcs-storage + retentionPolicy: + name: demo-retention + namespace: demo + sessions: + - name: frequent-backup + scheduler: + schedule: "*/5 * * * *" + jobTemplate: + backoffLimit: 1 + repositories: + - name: gcs-postgres-repo + backend: gcs-backend + directory: /postgres + encryptionSecret: + name: encrypt-secret + namespace: demo + addon: + name: postgres-addon + tasks: + - name: logical-backup +``` + +- `.spec.sessions[*].schedule` specifies that we want to backup the database at `5 minutes` interval. +- `.spec.target` refers to the targeted `sample-postgres` PostgreSQL database that we created earlier. + +Let's create the `BackupConfiguration` CR that we have shown above, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/kubestash/logical/examples/backupconfiguration.yaml +backupconfiguration.core.kubestash.com/sample-postgres-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, + +```bash +$ kubectl get backupconfiguration -n demo +NAME PHASE PAUSED AGE +sample-postgres-backup Ready 2m50s +``` + +Additionally, we can verify that the `Repository` specified in the `BackupConfiguration` has been created using the following command, + +```bash +$ kubectl get repo -n demo +NAME INTEGRITY SNAPSHOT-COUNT SIZE PHASE LAST-SUCCESSFUL-BACKUP AGE +gcs-postgres-repo 0 0 B Ready 3m +``` + +KubeStash keeps the backup for `Repository` YAMLs. If we navigate to the GCS bucket, we will see the `Repository` YAML stored in the `demo/postgres` directory. + +**Verify CronJob:** + +It will also create a `CronJob` with the schedule specified in `spec.sessions[*].scheduler.schedule` field of `BackupConfiguration` CR. + +Verify that the `CronJob` has been created using the following command, + +```bash +$ kubectl get cronjob -n demo +NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE +trigger-sample-postgres-backup-frequent-backup */5 * * * * 0 2m45s 3m25s +``` + +**Verify BackupSession:** + +KubeStash triggers an instant backup as soon as the `BackupConfiguration` is ready. After that, backups are scheduled according to the specified schedule. + +```bash +$ kubectl get backupsession -n demo -w +NAME INVOKER-TYPE INVOKER-NAME PHASE DURATION AGE +sample-postgres-backup-frequent-backup-1725449400 BackupConfiguration sample-postgres-backup Succeeded 7m22s +``` + +We can see from the above output that the backup session has succeeded. Now, we are going to verify whether the backed up data has been stored in the backend. + +**Verify Backup:** + +Once a backup is complete, KubeStash will update the respective `Repository` CR to reflect the backup. Check that the repository `sample-postgres-backup` has been updated by the following command, + +```bash +$ kubectl get repository -n demo sample-postgres-backup +NAME INTEGRITY SNAPSHOT-COUNT SIZE PHASE LAST-SUCCESSFUL-BACKUP AGE +sample-postgres-backup true 1 806 B Ready 8m27s 9m18s +``` + +At this moment we have one `Snapshot`. Run the following command to check the respective `Snapshot` which represents the state of a backup run for an application. + +```bash +$ kubectl get snapshots -n demo -l=kubestash.com/repo-name=gcs-postgres-repo +NAME REPOSITORY SESSION SNAPSHOT-TIME DELETION-POLICY PHASE AGE +gcs-postgres-repo-sample-postgres-backup-frequent-backup-1725449400 gcs-postgres-repo frequent-backup 2024-01-23T13:10:54Z Delete Succeeded 16h +``` + +> Note: KubeStash creates a `Snapshot` with the following labels: +> - 'kubedb.com/db-version: ' +> - `kubestash.com/app-ref-kind: ` +> - `kubestash.com/app-ref-name: ` +> - `kubestash.com/app-ref-namespace: ` +> - `kubestash.com/repo-name: ` +> +> These labels can be used to watch only the `Snapshot`s related to our target Database or `Repository`. + +If we check the YAML of the `Snapshot`, we can find the information about the backed up components of the Database. + +```bash +$ kubectl get snapshots -n demo gcs-postgres-repo-sample-postgres-backup-frequent-backup-1725449400 -oyaml +``` + +```yaml +apiVersion: storage.kubestash.com/v1alpha1 +kind: Snapshot +metadata: + creationTimestamp: "2024-09-04T11:30:00Z" + finalizers: + - kubestash.com/cleanup + generation: 1 + labels: + kubedb.com/db-version: "16.4" + kubestash.com/app-ref-kind: Postgres + kubestash.com/app-ref-name: sample-postgres + kubestash.com/app-ref-namespace: demo + kubestash.com/repo-name: gcs-postgres-repo + name: gcs-postgres-repo-sample-postgreckup-frequent-backup-1725449400 + namespace: demo + ownerReferences: + - apiVersion: storage.kubestash.com/v1alpha1 + blockOwnerDeletion: true + controller: true + kind: Repository + name: gcs-postgres-repo + uid: 1009bd4a-b211-49f1-a64c-3c979c699a81 + resourceVersion: "253523" + uid: c6757c49-e13b-4a36-9f7d-64eae350423f +spec: + appRef: + apiGroup: kubedb.com + kind: Postgres + name: sample-postgres + namespace: demo + backupSession: sample-postgres-backup-frequent-backup-1725449400 + deletionPolicy: Delete + repository: gcs-postgres-repo + session: frequent-backup + snapshotID: 01J6YCRWEWAKACMGZYR2R7YJ5C + type: FullBackup + version: v1 +status: + components: + dump: + driver: Restic + duration: 11.526138009s + integrity: true + path: repository/v1/frequent-backup/dump + phase: Succeeded + resticStats: + - hostPath: dumpfile.sql + id: 008eb87193e7db112e9ad8f42c9302c851a1fbacb7165a5cb3aa2d27dd210764 + size: 3.345 KiB + uploaded: 299 B + size: 2.202 KiB + conditions: + - lastTransitionTime: "2024-09-04T11:30:00Z" + message: Recent snapshot list updated successfully + reason: SuccessfullyUpdatedRecentSnapshotList + status: "True" + type: RecentSnapshotListUpdated + - lastTransitionTime: "2024-09-04T11:30:32Z" + message: Metadata uploaded to backend successfully + reason: SuccessfullyUploadedSnapshotMetadata + status: "True" + type: SnapshotMetadataUploaded + integrity: true + phase: Succeeded + size: 2.201 KiB + snapshotTime: "2024-09-04T11:30:00Z" + totalComponents: 1 +``` + +> KubeStash uses the `pg_dump` command to take backups of target PostgreSQL databases. Therefore, the component name for `logical backups` is set as `dump`. + +Now, if we navigate to the GCS bucket, we will see the backed up data stored in the `demo/popstgres/repository/v1/frequent-backup/dump` directory. KubeStash also keeps the backup for `Snapshot` YAMLs, which can be found in the `demo/dep/snapshots` directory. + +> Note: KubeStash stores all dumped data encrypted in the backup directory, meaning it remains unreadable until decrypted. + + +## Restore + +In this section, we are going to restore the database from the backup we have taken in the previous section. We are going to deploy a new database and initialize it from the backup. + +Now, we have to deploy the restored database similarly as we have deployed the original `sample-postgres` database. However, this time there will be the following differences: + +- We are going to specify `.spec.init.waitForInitialRestore` field that tells KubeDB to wait for first restore to complete before marking this database is ready to use. + +Below is the YAML for `PostgreSQL` CR we are going deploy to initialize from backup, + +```yaml +apiVersion: kubedb.com/v1 +kind: Postgres +metadata: + name: restored-postgres + namespace: demo +spec: + init: + waitForInitialRestore: true + version: "16.4" + replicas: 3 + standbyMode: Hot + streamingMode: Synchronous + storageType: Durable + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the above database, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/kubestash/logical/examples/restored-postgres.yaml +postgres.kubedb.com/restore-postgres created +``` + +If you check the database status, you will see it is stuck in **`Provisioning`** state. + +```bash +$ kubectl get postgres -n demo restored-postgres +NAME VERSION STATUS AGE +restored-postgres 8.2.0 Provisioning 61s +``` + +#### Create RestoreSession: + +Now, we need to create a RestoreSession CRD pointing to targeted `PostgreSQL` database. + +Below, is the contents of YAML file of the `RestoreSession` object that we are going to create to restore backed up data into the newly created database provisioned by `PostgreSQL` object named `restored-postgres`. + +```yaml +apiVersion: core.kubestash.com/v1alpha1 +kind: RestoreSession +metadata: + name: sample-postgres-restore + namespace: demo +spec: + target: + apiGroup: kubedb.com + kind: Postgres + namespace: demo + name: restored-postgres + dataSource: + repository: gcs-postgres-repo + snapshot: latest + encryptionSecret: + name: encrypt-secret + namespace: demo + addon: + name: postgres-addon + tasks: + - name: logical-backup-restore +``` + +Here, + +- `.spec.target` refers to the newly created `restored-postgres` PostgreSQL object to where we want to restore backup data. +- `.spec.dataSource.repository` specifies the Repository object that holds the backed up data. +- `.spec.dataSource.snapshot` specifies to restore from latest `Snapshot`. + +Let's create the RestoreSession CRD object we have shown above, + +```bash +$ kubectl apply -f **https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/kubestash/logical/examples/restoresession.yaml +restoresession.core.kubestash.com/sample-postgres-restore created +``` + +Once, you have created the `RestoreSession` object, KubeStash will create restore Job. Run the following command to watch the phase of the `RestoreSession` object, + +```bash +$ watch kubectl get restoresession -n demo +Every 2.0s: kubectl get restores... AppsCode-PC-03: Wed Aug 21 10:44:05 2024 +NAME REPOSITORY FAILURE-POLICY PHASE DURATION AGE +sample-postgres-restore gcs-postgres-repo Succeeded 7s 116s +``` + +The `Succeeded` phase means that the restore process has been completed successfully. + +#### Verify Restored Data: + +In this section, we are going to verify whether the desired data has been restored successfully. We are going to connect to the database server and check whether the database and the table we created earlier in the original database are restored. + +At first, check if the database has gone into **`Ready`** state by the following command, + +```bash +$ kubectl get postgres -n demo restored-postgres +NAME VERSION STATUS AGE +restored-postgres 16.4 Ready 6m31s +``` + +Now, find out the database `Pod` by the following command, + +```bash +$ kubectl get pods -n demo --selector="app.kubernetes.io/instance=restored-postgres" +NAME READY STATUS RESTARTS AGE +restored-postgres-0 2/2 Running 0 6m7s +restored-postgres-1 2/2 Running 0 6m1s +restored-postgres-2 2/2 Running 0 5m55s +``` + +Now, lets exec one of the Pod and verify restored data. + +```bash +$ kubectl exec -it -n demo restored-postgres-0 -- /bin/sh +# login as "postgres" superuser. +/ # psql -U postgres +psql (11.11) +Type "help" for help. + +# verify that the "demo" database has been restored +postgres=# \l + List of databases + Name | Owner | Encoding | Locale Provider | Collate | Ctype | ICU Locale | ICU Rules | Access privileges +---------------+----------+----------+-----------------+------------+------------+------------+-----------+----------------------- + demo | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + kubedb_system | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + postgres | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | + template0 | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | =c/postgres + + | | | | | | | | postgres=CTc/postgres + template1 | postgres | UTF8 | libc | en_US.utf8 | en_US.utf8 | | | =c/postgres + + | | | | | | | | postgres=CTc/postgres +(5 rows) + +# connect to the "demo" database +postgres=# \c demo +You are now connected to database "demo" as user "postgres". + +# verify that the sample table has been restored +demo=# \d + List of relations + Schema | Name | Type | Owner +--------+---------+-------+---------- + public | company | table | postgres +(1 row) + +# disconnect from the database +demo=# \q + +# exit from the pod +/ # exit +``` + +So, from the above output, we can see the `demo` database we had created in the original database `sample-postgres` has been restored in the `restored-postgres` database. + + +## Cleanup + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete backupconfigurations.core.kubestash.com -n demo sample-postgres-backup +kubectl delete restoresessions.core.kubestash.com -n demo restore-sample-postgres +kubectl delete backupstorage -n demo gcs-storage +kubectl delete secret -n demo gcs-secret +kubectl delete secret -n demo encrypt-secret +kubectl delete retentionpolicies.storage.kubestash.com -n demo demo-retention +kubectl delete postgres -n demo restored-postgres +kubectl delete postgres -n demo sample-postgres +``` \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/overview/images/backup_overview.svg b/docs/guides/postgres/backup/kubestash/overview/images/backup_overview.svg new file mode 100644 index 000000000..9d245e0dc --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/overview/images/backup_overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/overview/images/kubedb_plus_kubestash.svg b/docs/guides/postgres/backup/kubestash/overview/images/kubedb_plus_kubestash.svg new file mode 100644 index 000000000..380d92d96 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/overview/images/kubedb_plus_kubestash.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/guides/postgres/backup/kubestash/overview/images/restore_overview.svg b/docs/guides/postgres/backup/kubestash/overview/images/restore_overview.svg new file mode 100644 index 000000000..f2c248896 --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/overview/images/restore_overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/guides/postgres/backup/kubestash/overview/index.md b/docs/guides/postgres/backup/kubestash/overview/index.md new file mode 100644 index 000000000..8d82725ef --- /dev/null +++ b/docs/guides/postgres/backup/kubestash/overview/index.md @@ -0,0 +1,98 @@ +--- +title: Backup & Restore PostgreSQL Using KubeStash +menu: + docs_{{ .version }}: + identifier: guides-pg-backup-overview-stashv2 + name: Overview + parent: guides-pg-backup-stashv2 + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +{{< notice type="warning" message="Please install [KubeStash](https://kubestash.com/docs/latest/setup/install/kubestash/) to try this feature. Database backup with KubeStash is already included in the KubeDB license. So, you don't need a separate license for KubeStash." >}} + +# PostgreSQL Backup & Restore Overview + +KubeDB also uses [KubeStash](https://kubestash.com) to backup and restore databases. KubeStash by AppsCode is a cloud native data backup and recovery solution for Kubernetes workloads and databases. KubeStash utilizes [restic](https://github.com/restic/restic) to securely backup stateful applications to any cloud or on-prem storage backends (for example, S3, GCS, Azure Blob storage, Minio, NetApp, Dell EMC etc.). + +
+  KubeDB + KubeStash +
Fig: Backup KubeDB Databases Using KubeStash
+
+ +## How Backup Works + +The following diagram shows how KubeStash takes backup of a `PostgreSQL` database. Open the image in a new tab to see the enlarged version. + +
+  PostgreSQL Backup Overview +
Fig: PostgreSQL Backup Overview
+
+ +The backup process consists of the following steps: + +1. At first, a user creates a `Secret`. This secret holds the credentials to access the backend where the backed up data will be stored. + +2. Then, she creates a `BackupStorage` custom resource that specifies the backend information, along with the `Secret` containing the credentials needed to access the backend. + +3. KubeStash operator watches for `BackupStorage` custom resources. When it finds a `BackupStorage` object, it initializes the `BackupStorage` by uploading the `metadata.yaml` file into the target storage. + +4. Then, she creates a `BackupConfiguration` custom resource that specifies the targeted the KubeDB managed `PostgreSQL` database, the `Addon` info with a specified task, etc. It also provides information about one or more repositories, each indicating a path and a `BackupStorage` for storing the backed-up data. + +5. KubeStash operator watches for `BackupConfiguration` objects. + +6. Once the KubeStash operator finds a `BackupConfiguration` object, it creates `Repository` with the information specified in the `BackupConfiguration`. + +7. KubeStash operator watches for `Repository` custom resources. When it finds the `Repository` object, it Initializes `Repository` by uploading `repository.yaml` file into the `spec.sessions[*].repositories[*].directory` path specified in `BackupConfiguration`. + +8. Then, it creates a `CronJob` for each session with the schedule specified in `BackupConfiguration` to trigger backup periodically. + +9. KubeStash operator triggers an instant backup as soon as the `BackupConfiguration` is ready. After that, backups are triggered by the `CronJob` according to the specified schedule. + +10. KubeStash operator watches for `BackupSession` custom resources. + +11. When it finds a `BackupSession` object, it creates a `Snapshot` custom resource for each `Repository` specified in the `BackupConfiguration`. + +12. Then it resolves the respective `Addon` and `Function` and prepares backup `Job` definition. + +13. Then, it creates the `Job` to backup the targeted `PostgreSQL` database. + +14. The backup `Job` reads necessary information (e.g. auth secret, port) to connect with the database from the `AppBinding` crd. It also reads backend information and access credentials from BackupStorage crd, Storage Secret and Repository path respectively. + +15. Then, the `Job` dumps the targeted `PostgreSQL` 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. + +16. After the backup process is completed, the backup `Job` updates the `status.components[dump]` field of the `Snapshot` resources with backup information of the target `PostgreSQL` database. + +## How Restore Process Works + +The following diagram shows how KubeStash restores backed up data into a `PostgreSQL` database. Open the image in a new tab to see the enlarged version. + +
+  Database Restore Overview +
Fig: PostgreSQL Restore Process Overview
+
+ +The restore process consists of the following steps: + +1. At first, a user creates a `PostgreSQL` database where the data will be restored or the user can use the same `PostgreSQL` database. + +2. Then, she creates a `RestoreSession` custom resource that specifies the target `PostgreSQL` database where the backed-up data will be restored. the `Repository` object that points to a `BackupStorage` that holds backend information, and the target `Snapshot`, which will be restored. It also specifies the `Addon` info with task to use to restore. + +3. KubeStash operator watches for `RestoreSession` custom resources. + +4. When it finds a `RestoreSession` custom resource, it resolves the respective `Addon` and `Function` and prepares a restore `Job` definition. + +5. Then, it creates the `Job` to restore the target. + +6. 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. + +7. 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. + +8. Finally, when the restore process is completed, the `Job` updates the `status.components[dump]` field of the `RestoreSession` with restore information of the target database. + +## Next Steps + +- Backup a `PostgreSQL` database using KubeStash by the following guides from [here](/docs/guides/postgres/backup/kubestash/logical/index.md). \ No newline at end of file diff --git a/docs/guides/postgres/backup/stash/_index.md b/docs/guides/postgres/backup/stash/_index.md new file mode 100644 index 000000000..7508f6b8c --- /dev/null +++ b/docs/guides/postgres/backup/stash/_index.md @@ -0,0 +1,10 @@ +--- +title: Backup & Restore PostgreSQL | Stash +menu: + docs_{{ .version }}: + identifier: guides-pg-backup-stashv1 + name: Stash + parent: guides-pg-backup + weight: 40 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/postgres/backup/auto-backup/examples/backupblueprint.yaml b/docs/guides/postgres/backup/stash/auto-backup/examples/backupblueprint.yaml similarity index 100% rename from docs/guides/postgres/backup/auto-backup/examples/backupblueprint.yaml rename to docs/guides/postgres/backup/stash/auto-backup/examples/backupblueprint.yaml diff --git a/docs/guides/postgres/backup/auto-backup/examples/sample-pg-1.yaml b/docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-1.yaml similarity index 100% rename from docs/guides/postgres/backup/auto-backup/examples/sample-pg-1.yaml rename to docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-1.yaml diff --git a/docs/guides/postgres/backup/auto-backup/examples/sample-pg-2.yaml b/docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-2.yaml similarity index 100% rename from docs/guides/postgres/backup/auto-backup/examples/sample-pg-2.yaml rename to docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-2.yaml diff --git a/docs/guides/postgres/backup/auto-backup/examples/sample-pg-3.yaml b/docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-3.yaml similarity index 100% rename from docs/guides/postgres/backup/auto-backup/examples/sample-pg-3.yaml rename to docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-3.yaml diff --git a/docs/guides/postgres/backup/auto-backup/images/sample-postgres-1.png b/docs/guides/postgres/backup/stash/auto-backup/images/sample-postgres-1.png similarity index 100% rename from docs/guides/postgres/backup/auto-backup/images/sample-postgres-1.png rename to docs/guides/postgres/backup/stash/auto-backup/images/sample-postgres-1.png diff --git a/docs/guides/postgres/backup/auto-backup/images/sample-postgres-2.png b/docs/guides/postgres/backup/stash/auto-backup/images/sample-postgres-2.png similarity index 100% rename from docs/guides/postgres/backup/auto-backup/images/sample-postgres-2.png rename to docs/guides/postgres/backup/stash/auto-backup/images/sample-postgres-2.png diff --git a/docs/guides/postgres/backup/auto-backup/images/sample-postgres-3.png b/docs/guides/postgres/backup/stash/auto-backup/images/sample-postgres-3.png similarity index 100% rename from docs/guides/postgres/backup/auto-backup/images/sample-postgres-3.png rename to docs/guides/postgres/backup/stash/auto-backup/images/sample-postgres-3.png diff --git a/docs/guides/postgres/backup/auto-backup/index.md b/docs/guides/postgres/backup/stash/auto-backup/index.md similarity index 96% rename from docs/guides/postgres/backup/auto-backup/index.md rename to docs/guides/postgres/backup/stash/auto-backup/index.md index 08dbc582d..b90494dbc 100644 --- a/docs/guides/postgres/backup/auto-backup/index.md +++ b/docs/guides/postgres/backup/stash/auto-backup/index.md @@ -3,9 +3,9 @@ title: PostgreSQL | Stash description: Stash auto-backup for PostgreSQL database menu: docs_{{ .version }}: - identifier: guides-pg-backup-auto-backup + identifier: guides-pg-backup-auto-backup-stashv1 name: Auto-Backup - parent: guides-pg-backup + parent: guides-pg-backup-stashv1 weight: 30 menu_name: docs_{{ .version }} section_menu_id: guides @@ -22,7 +22,7 @@ In this tutorial, we are going to show how you can configure a backup blueprint - At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. - Install KubeDB in your cluster following the steps [here](/docs/setup/README.md). - Install Stash in your cluster following the steps [here](https://stash.run/docs/latest/setup/install/stash/). -- If you are not familiar with how Stash backup and restore PostgreSQL databases, please check the following guide [here](/docs/guides/postgres/backup/overview/index.md). +- If you are not familiar with how Stash backup and restore PostgreSQL databases, please check the following guide [here](/docs/guides/postgres/backup/stash/overview/index.md). - If you are not familiar with how auto-backup works in Stash, please check the following guide [here](https://stash.run/docs/latest/guides/auto-backup/overview/). - If you are not familiar with the available auto-backup options for databases in Stash, please check the following guide [here](https://stash.run/docs/latest/guides/auto-backup/database/). @@ -99,7 +99,7 @@ Notice the `prefix` field of `backend` section. We have used some variables in f Let's create the `BackupBlueprint` we have shown above, ```bash -❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/auto-backup/examples/backupblueprint.yaml +❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/auto-backup/examples/backupblueprint.yaml backupblueprint.stash.appscode.com/postgres-backup-template created ``` @@ -154,7 +154,7 @@ Notice the `annotations` section. We are pointing to the `BackupBlueprint` that Let's create the above Postgres CRO, ```bash -❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/auto-backup/examples/sample-pg-1.yaml +❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-1.yaml postgres.kubedb.com/sample-postgres-1 created ``` @@ -272,7 +272,7 @@ app-sample-postgres-1-1614073215 BackupConfiguration app-sample-postgres-1 Once the backup has been completed successfully, you should see the backed-up data has been stored in the bucket at the directory pointed by the `prefix` field of the `Repository`.
- Backup data in GCS Bucket + Backup data in GCS Bucket
Fig: Backup data in GCS Bucket
@@ -323,7 +323,7 @@ Notice the `annotations` section. This time, we have passed a schedule via `stas Let's create the above Postgres CRO, ```bash -❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/auto-backup/examples/sample-pg-2.yaml +❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-2.yaml postgres.kubedb.com/sample-postgres-2 created ``` @@ -442,7 +442,7 @@ app-sample-postgres-2-1614073502 BackupConfiguration app-sample-postgres-2 Once the backup has been completed successfully, you should see that Stash has created a new directory as pointed by the `prefix` field of the new `Repository` and stored the backed-up data there.
- Backup data in GCS Bucket + Backup data in GCS Bucket
Fig: Backup data in GCS Bucket
@@ -493,7 +493,7 @@ Notice the `annotations` section. This time, we have passed an argument via `par Let's create the above Postgres CRO, ```bash -❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/auto-backup/examples/sample-pg-3.yaml +❯ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/auto-backup/examples/sample-pg-3.yaml postgres.kubedb.com/sample-postgres-3 created ``` @@ -616,7 +616,7 @@ app-sample-postgres-3-1614073808 BackupConfiguration app-sample-postgres-3 Once the backup has been completed successfully, you should see that Stash has created a new directory as pointed by the `prefix` field of the new `Repository` and stored the backed-up data there.
- Backup data in GCS Bucket + Backup data in GCS Bucket
Fig: Backup data in GCS Bucket
@@ -625,7 +625,7 @@ Once the backup has been completed successfully, you should see that Stash has c To cleanup the resources crated by this tutorial, run the following commands, ```bash -❯ kubectl delete -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/auto-backup/examples/ +❯ kubectl delete -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/auto-backup/examples/ backupblueprint.stash.appscode.com "postgres-backup-template" deleted postgres.kubedb.com "sample-postgres-1" deleted postgres.kubedb.com "sample-postgres-2" deleted diff --git a/docs/guides/postgres/backup/customization/examples/backup/multi-retention-policy.yaml b/docs/guides/postgres/backup/stash/customization/examples/backup/multi-retention-policy.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/backup/multi-retention-policy.yaml rename to docs/guides/postgres/backup/stash/customization/examples/backup/multi-retention-policy.yaml diff --git a/docs/guides/postgres/backup/customization/examples/backup/resource-limit.yaml b/docs/guides/postgres/backup/stash/customization/examples/backup/resource-limit.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/backup/resource-limit.yaml rename to docs/guides/postgres/backup/stash/customization/examples/backup/resource-limit.yaml diff --git a/docs/guides/postgres/backup/customization/examples/backup/specific-database-user.yaml b/docs/guides/postgres/backup/stash/customization/examples/backup/specific-database-user.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/backup/specific-database-user.yaml rename to docs/guides/postgres/backup/stash/customization/examples/backup/specific-database-user.yaml diff --git a/docs/guides/postgres/backup/customization/examples/backup/specific-user.yaml b/docs/guides/postgres/backup/stash/customization/examples/backup/specific-user.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/backup/specific-user.yaml rename to docs/guides/postgres/backup/stash/customization/examples/backup/specific-user.yaml diff --git a/docs/guides/postgres/backup/customization/examples/repository.yaml b/docs/guides/postgres/backup/stash/customization/examples/repository.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/repository.yaml rename to docs/guides/postgres/backup/stash/customization/examples/repository.yaml diff --git a/docs/guides/postgres/backup/customization/examples/restore/passing-args.yaml b/docs/guides/postgres/backup/stash/customization/examples/restore/passing-args.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/restore/passing-args.yaml rename to docs/guides/postgres/backup/stash/customization/examples/restore/passing-args.yaml diff --git a/docs/guides/postgres/backup/customization/examples/restore/resource-limit.yaml b/docs/guides/postgres/backup/stash/customization/examples/restore/resource-limit.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/restore/resource-limit.yaml rename to docs/guides/postgres/backup/stash/customization/examples/restore/resource-limit.yaml diff --git a/docs/guides/postgres/backup/customization/examples/restore/specific-database-user.yaml b/docs/guides/postgres/backup/stash/customization/examples/restore/specific-database-user.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/restore/specific-database-user.yaml rename to docs/guides/postgres/backup/stash/customization/examples/restore/specific-database-user.yaml diff --git a/docs/guides/postgres/backup/customization/examples/restore/specific-snapshot.yaml b/docs/guides/postgres/backup/stash/customization/examples/restore/specific-snapshot.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/restore/specific-snapshot.yaml rename to docs/guides/postgres/backup/stash/customization/examples/restore/specific-snapshot.yaml diff --git a/docs/guides/postgres/backup/customization/examples/restore/specific-user.yaml b/docs/guides/postgres/backup/stash/customization/examples/restore/specific-user.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/restore/specific-user.yaml rename to docs/guides/postgres/backup/stash/customization/examples/restore/specific-user.yaml diff --git a/docs/guides/postgres/backup/customization/examples/sample-postgres.yaml b/docs/guides/postgres/backup/stash/customization/examples/sample-postgres.yaml similarity index 100% rename from docs/guides/postgres/backup/customization/examples/sample-postgres.yaml rename to docs/guides/postgres/backup/stash/customization/examples/sample-postgres.yaml diff --git a/docs/guides/postgres/backup/customization/index.md b/docs/guides/postgres/backup/stash/customization/index.md similarity index 99% rename from docs/guides/postgres/backup/customization/index.md rename to docs/guides/postgres/backup/stash/customization/index.md index f40afa848..51758c5e9 100644 --- a/docs/guides/postgres/backup/customization/index.md +++ b/docs/guides/postgres/backup/stash/customization/index.md @@ -3,9 +3,9 @@ title: PostgreSQL Backup Customization | Stash description: Customizing PostgreSQL Backup and Restore process with Stash menu: docs_{{ .version }}: - identifier: guides-pg-backup-customization + identifier: guides-pg-backup-customization-stashv1 name: Customizing Backup & Restore Process - parent: guides-pg-backup + parent: guides-pg-backup-stashv1 weight: 40 menu_name: docs_{{ .version }} section_menu_id: guides diff --git a/docs/guides/postgres/backup/overview/images/backup_overview.svg b/docs/guides/postgres/backup/stash/overview/images/backup_overview.svg similarity index 100% rename from docs/guides/postgres/backup/overview/images/backup_overview.svg rename to docs/guides/postgres/backup/stash/overview/images/backup_overview.svg diff --git a/docs/guides/postgres/backup/overview/images/restore_overview.svg b/docs/guides/postgres/backup/stash/overview/images/restore_overview.svg similarity index 100% rename from docs/guides/postgres/backup/overview/images/restore_overview.svg rename to docs/guides/postgres/backup/stash/overview/images/restore_overview.svg diff --git a/docs/guides/postgres/backup/overview/index.md b/docs/guides/postgres/backup/stash/overview/index.md similarity index 93% rename from docs/guides/postgres/backup/overview/index.md rename to docs/guides/postgres/backup/stash/overview/index.md index c48a7c6cf..cb56b2b42 100644 --- a/docs/guides/postgres/backup/overview/index.md +++ b/docs/guides/postgres/backup/stash/overview/index.md @@ -2,9 +2,9 @@ title: Backup & Restore PostgreSQL Using Stash menu: docs_{{ .version }}: - identifier: guides-pg-backup-overview + identifier: guides-pg-backup-overview-stashv1 name: Overview - parent: guides-pg-backup + parent: guides-pg-backup-stashv1 weight: 10 menu_name: docs_{{ .version }} section_menu_id: guides @@ -28,7 +28,7 @@ KubeDB uses [Stash](https://stash.run) to backup and restore databases. Stash by The following diagram shows how Stash takes backup of a PostgreSQL database. Open the image in a new tab to see the enlarged version.
-  PostgreSQL Backup Overview +  PostgreSQL Backup Overview
Fig: PostgreSQL Backup Overview
@@ -63,7 +63,7 @@ The backup process consists of the following steps: The following diagram shows how Stash restores backed up data into a PostgreSQL database. Open the image in a new tab to see the enlarged version.
-  Database Restore Overview +  Database Restore Overview
Fig: PostgreSQL Restore Process Overview
@@ -85,5 +85,5 @@ The restore process consists of the following steps: ## Next Steps -- Backup a standalone PostgreSQL database using Stash following the guide from [here](/docs/guides/postgres/backup/standalone/index.md). -- Configure a generic backup template for all the PostgreSQL databases of your cluster using Stash Auto-backup by following the guide from [here](/docs/guides/postgres/backup/auto-backup/index.md). +- Backup a standalone PostgreSQL database using Stash following the guide from [here](/docs/guides/postgres/backup/stash/standalone/index.md). +- Configure a generic backup template for all the PostgreSQL databases of your cluster using Stash Auto-backup by following the guide from [here](/docs/guides/postgres/backup/stash/auto-backup/index.md). diff --git a/docs/guides/postgres/backup/standalone/examples/appbinding.yaml b/docs/guides/postgres/backup/stash/standalone/examples/appbinding.yaml similarity index 100% rename from docs/guides/postgres/backup/standalone/examples/appbinding.yaml rename to docs/guides/postgres/backup/stash/standalone/examples/appbinding.yaml diff --git a/docs/guides/postgres/backup/standalone/examples/backupconfiguration.yaml b/docs/guides/postgres/backup/stash/standalone/examples/backupconfiguration.yaml similarity index 100% rename from docs/guides/postgres/backup/standalone/examples/backupconfiguration.yaml rename to docs/guides/postgres/backup/stash/standalone/examples/backupconfiguration.yaml diff --git a/docs/guides/postgres/backup/standalone/examples/postgres.yaml b/docs/guides/postgres/backup/stash/standalone/examples/postgres.yaml similarity index 100% rename from docs/guides/postgres/backup/standalone/examples/postgres.yaml rename to docs/guides/postgres/backup/stash/standalone/examples/postgres.yaml diff --git a/docs/guides/postgres/backup/standalone/examples/repository.yaml b/docs/guides/postgres/backup/stash/standalone/examples/repository.yaml similarity index 100% rename from docs/guides/postgres/backup/standalone/examples/repository.yaml rename to docs/guides/postgres/backup/stash/standalone/examples/repository.yaml diff --git a/docs/guides/postgres/backup/standalone/examples/restored-postgres.yaml b/docs/guides/postgres/backup/stash/standalone/examples/restored-postgres.yaml similarity index 100% rename from docs/guides/postgres/backup/standalone/examples/restored-postgres.yaml rename to docs/guides/postgres/backup/stash/standalone/examples/restored-postgres.yaml diff --git a/docs/guides/postgres/backup/standalone/examples/restoresession.yaml b/docs/guides/postgres/backup/stash/standalone/examples/restoresession.yaml similarity index 100% rename from docs/guides/postgres/backup/standalone/examples/restoresession.yaml rename to docs/guides/postgres/backup/stash/standalone/examples/restoresession.yaml diff --git a/docs/guides/postgres/backup/standalone/images/sample-postgres-backup.png b/docs/guides/postgres/backup/stash/standalone/images/sample-postgres-backup.png similarity index 100% rename from docs/guides/postgres/backup/standalone/images/sample-postgres-backup.png rename to docs/guides/postgres/backup/stash/standalone/images/sample-postgres-backup.png diff --git a/docs/guides/postgres/backup/standalone/index.md b/docs/guides/postgres/backup/stash/standalone/index.md similarity index 97% rename from docs/guides/postgres/backup/standalone/index.md rename to docs/guides/postgres/backup/stash/standalone/index.md index 4a146a184..46ed3c04d 100644 --- a/docs/guides/postgres/backup/standalone/index.md +++ b/docs/guides/postgres/backup/stash/standalone/index.md @@ -3,9 +3,9 @@ title: PostgreSQL | Stash description: Backup and restore standalone PostgreSQL database using Stash menu: docs_{{ .version }}: - identifier: guides-pg-backup-standalone + identifier: guides-pg-backup-standalone-stashv1 name: Standalone PostgreSQL - parent: guides-pg-backup + parent: guides-pg-backup-stashv1 weight: 20 menu_name: docs_{{ .version }} section_menu_id: guides @@ -22,7 +22,7 @@ Stash 0.9.0+ supports backup and restoration of PostgreSQL databases. This guide - Install KubeDB in your cluster following the steps [here](/docs/setup/README.md). - Install Stash in your cluster following the steps [here](https://stash.run/docs/latest/setup/install/stash/). - Install Stash `kubectl` plugin following the steps [here](https://stash.run/docs/latest/setup/install/kubectl-plugin/). -- If you are not familiar with how Stash backup and restore PostgreSQL databases, please check the following guide [here](/docs/guides/postgres/backup/overview/index.md): +- If you are not familiar with how Stash backup and restore PostgreSQL databases, please check the following guide [here](/docs/guides/postgres/backup/stash/overview/index.md): You have to be familiar with following custom resources: @@ -73,7 +73,7 @@ spec: Create the above `Postgres` crd, ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/standalone/examples/postgres.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/standalone/examples/postgres.yaml postgres.kubedb.com/sample-postgres created ``` @@ -275,7 +275,7 @@ spec: Let's create the `Repository` we have shown above, ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/standalone/examples/repository.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/standalone/examples/repository.yaml repository.stash.appscode.com/gcs-repo created ``` @@ -320,7 +320,7 @@ Here, Let's create the `BackupConfiguration` object we have shown above, ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/standalone/examples/backupconfiguration.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/standalone/examples/backupconfiguration.yaml backupconfiguration.stash.appscode.com/sample-postgres-backup created ``` @@ -374,7 +374,7 @@ gcs-repo true 1.770 KiB 1 2m 4m1 Now, if we navigate to the GCS bucket, we are going to see backed up data has been stored in `demo/postgres/sample-postgres` directory as specified by `spec.backend.gcs.prefix` field of Repository crd.
- Backup data in GCS Bucket + Backup data in GCS Bucket
Fig: Backup data in GCS Bucket
@@ -443,7 +443,7 @@ Notice the `init` section. Here, we have specified `waitForInitialRestore: true` Let's create the above database, ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/standalone/examples/restored-postgres.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/standalone/examples/restored-postgres.yaml postgres.kubedb.com/restored-postgres created ``` @@ -512,7 +512,7 @@ Here, Let's create the `RestoreSession` crd we have shown above, ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/standalone/examples/restoresession.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/backup/stash/standalone/examples/restoresession.yaml restoresession.stash.appscode.com/sample-postgres-restore created ``` diff --git a/docs/guides/postgres/configuration/using-config-file.md b/docs/guides/postgres/configuration/using-config-file.md index 07f3a009b..bda13136e 100644 --- a/docs/guides/postgres/configuration/using-config-file.md +++ b/docs/guides/postgres/configuration/using-config-file.md @@ -203,7 +203,7 @@ If you would like to uninstall KubeDB operator, please follow the steps [here](/ ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) - Monitor your PostgreSQL database with KubeDB using [built-in Prometheus](/docs/guides/postgres/monitoring/using-builtin-prometheus.md). diff --git a/docs/guides/postgres/custom-rbac/using-custom-rbac.md b/docs/guides/postgres/custom-rbac/using-custom-rbac.md index eb4154ee5..fafb9db3d 100644 --- a/docs/guides/postgres/custom-rbac/using-custom-rbac.md +++ b/docs/guides/postgres/custom-rbac/using-custom-rbac.md @@ -386,7 +386,7 @@ If you would like to uninstall the KubeDB operator, please follow the steps [her ## Next Steps -- Learn about [backup & restore](/docs/guides/postgres/backup/overview/index.md) of PostgreSQL databases using Stash. +- Learn about [backup & restore](/docs/guides/postgres/backup/stash/overview/index.md) of PostgreSQL databases using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) - Monitor your PostgreSQL instance with KubeDB using [built-in Prometheus](/docs/guides/postgres/monitoring/using-builtin-prometheus.md). diff --git a/docs/guides/postgres/initialization/script_source.md b/docs/guides/postgres/initialization/script_source.md index 8c2f26e88..fdd1b0b94 100644 --- a/docs/guides/postgres/initialization/script_source.md +++ b/docs/guides/postgres/initialization/script_source.md @@ -236,6 +236,6 @@ $ kubectl delete ns demo ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/postgres/monitoring/using-builtin-prometheus.md b/docs/guides/postgres/monitoring/using-builtin-prometheus.md index 5c136b3f5..6adfa9f97 100644 --- a/docs/guides/postgres/monitoring/using-builtin-prometheus.md +++ b/docs/guides/postgres/monitoring/using-builtin-prometheus.md @@ -352,7 +352,7 @@ $ kubectl delete ns monitoring ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL databases using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL databases using Stash. - Monitor your PostgreSQL database with KubeDB using [`out-of-the-box` Prometheus operator](/docs/guides/postgres/monitoring/using-prometheus-operator.md). - Use [private Docker registry](/docs/guides/postgres/private-registry/using-private-registry.md) to deploy PostgreSQL with KubeDB. - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/postgres/pitr/archiver.md b/docs/guides/postgres/pitr/archiver.md index c04569395..449f6ae02 100644 --- a/docs/guides/postgres/pitr/archiver.md +++ b/docs/guides/postgres/pitr/archiver.md @@ -423,7 +423,7 @@ $ kubectl delete ns demo ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Learn about [custom PostgresVersions](/docs/guides/postgres/custom-versions/setup.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) diff --git a/docs/guides/postgres/private-registry/using-private-registry.md b/docs/guides/postgres/private-registry/using-private-registry.md index 8b0ca9c41..8720a7180 100644 --- a/docs/guides/postgres/private-registry/using-private-registry.md +++ b/docs/guides/postgres/private-registry/using-private-registry.md @@ -202,7 +202,7 @@ If you would like to uninstall KubeDB operator, please follow the steps [here](/ ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) - Monitor your PostgreSQL database with KubeDB using [built-in Prometheus](/docs/guides/postgres/monitoring/using-builtin-prometheus.md). diff --git a/docs/guides/postgres/quickstart/quickstart.md b/docs/guides/postgres/quickstart/quickstart.md index 6d8aa1aff..9a246e15a 100644 --- a/docs/guides/postgres/quickstart/quickstart.md +++ b/docs/guides/postgres/quickstart/quickstart.md @@ -541,7 +541,7 @@ If you are just testing some basic functionalities, you might want to avoid addi ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Learn about [custom PostgresVersions](/docs/guides/postgres/custom-versions/setup.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) diff --git a/docs/guides/postgres/remote-replica/remotereplica.md b/docs/guides/postgres/remote-replica/remotereplica.md index e4fc36668..33170ce78 100644 --- a/docs/guides/postgres/remote-replica/remotereplica.md +++ b/docs/guides/postgres/remote-replica/remotereplica.md @@ -355,7 +355,7 @@ kubectl delete ns demo ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Learn about [custom PostgresVersions](/docs/guides/postgres/custom-versions/setup.md). - Want to setup PostgreSQL cluster? Check how to [configure Highly Available PostgreSQL Cluster](/docs/guides/postgres/clustering/ha_cluster.md) diff --git a/docs/guides/postgres/synchronous/index.md b/docs/guides/postgres/synchronous/index.md index 13fd957d4..4495e3712 100644 --- a/docs/guides/postgres/synchronous/index.md +++ b/docs/guides/postgres/synchronous/index.md @@ -131,7 +131,7 @@ If you would like to uninstall KubeDB operator, please follow the steps [here](/ ## Next Steps -- Learn about [backup and restore](/docs/guides/postgres/backup/overview/index.md) PostgreSQL database using Stash. +- Learn about [backup and restore](/docs/guides/postgres/backup/stash/overview/index.md) PostgreSQL database using Stash. - Learn about initializing [PostgreSQL with Script](/docs/guides/postgres/initialization/script_source.md). - Monitor your PostgreSQL database with KubeDB using [built-in Prometheus](/docs/guides/postgres/monitoring/using-builtin-prometheus.md). - Monitor your PostgreSQL database with KubeDB using [Prometheus operator](/docs/guides/postgres/monitoring/using-prometheus-operator.md).