Skip to content

Commit

Permalink
Documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@WadeBarnes
WadeBarnes committed Feb 28, 2020
1 parent 27b238f commit 377cb2b
Show file tree
Hide file tree
Showing 6 changed files with 93 additions and 81 deletions.
53 changes: 23 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Backup Container
description: A simple containerized backup solution for backing up one or more postgres or mongo databases to a secondary location..
description: A simple containerized backup solution for backing up one or more postgres or mongo databases to a secondary location.
author: WadeBarnes
resourceType: Components
personas:
Expand All @@ -11,23 +11,24 @@ labels:
- backup
- backups
- postgres
- mongo
- database
---
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

# Backup Container
[Backup Container](https://github.com/BCDevOps/backup-container) is a simple containerized backup solution for backing up one or more mongo or postgres databases to a secondary location. _Code and documentation was originally pulled from the [HETS Project](https://github.com/bcgov/hets)_
[Backup Container](https://github.com/BCDevOps/backup-container) is a simple containerized backup solution for backing up one or more postgres or mongo databases to a secondary location. _Code and documentation was originally pulled from the [HETS Project](https://github.com/bcgov/hets)_

# Backup Container Options
You can run the Backup container for only Postgres or Mongo or mixed.
For Mixed (both Postgres and Mongo):
1) you must use the backup.conf.
2) within the backup.conf, specifying the DatabaseType is mandatory.
3) you will need to create two builds and two deployment configs. They use a single backup.conf.

You can run the Backup Container for postgres and mongo databases separately or in a mixed environment.
For a mixed environment:
1) You MUST use the recommended `backup.conf` configuration.
2) Within the `backup.conf`, you MUST specify the `DatabaseType` for each listed database.
3) You will need to create two builds and two deployment configs. One for a postgres backup container and the other for a mongo backup container.
4) Mount the same `backup.conf` file (ConfigMap) to each deployed container.

## Backups in OpenShift
This project provides you with a starting point for integrating backups into your OpenShift projects. The scripts and templates provided in the [openshift](./openshift) directory are compatible with the [openshift-developer-tools](https://github.com/BCDevOps/openshift-developer-tools) scripts. They help you create an OpenShift deployment or cronjob called `backup` in your projects that runs backups on a Postgres database(s) within the project environment. You only need to integrate the scripts and templates into your project(s), the builds can be done with this repository as the source.
This project provides you with a starting point for integrating backups into your OpenShift projects. The scripts and templates provided in the [openshift](./openshift) directory are compatible with the [openshift-developer-tools](https://github.com/BCDevOps/openshift-developer-tools) scripts. They help you create an OpenShift deployment or cronjob called `backup` in your projects that runs backups on databases within the project environment. You only need to integrate the scripts and templates into your project(s), the builds can be done with this repository as the source.

Following are the instructions for running the backups and a restore.

Expand Down Expand Up @@ -61,24 +62,14 @@ NFS backed storage is covered by the following backup and retention policies:
- 90 days

### Restore/Verification Storage Volume
The default storage class for the restore/verification volume is `gluster-file-db`. The supplied deployment template will auto-provision this volume for you with it is published. Refer to the *Storage Performance* section for performance considerations.
The default storage class for the restore/verification volume is `netapp-file-standard`. The supplied deployment template will auto-provision this volume for you with it is published. Refer to the *Storage Performance* section for performance considerations.

This volume should be large enough to host your largest database. Set the size by updating/overriding the `VERIFICATION_VOLUME_SIZE` value within the template.

### Storage Performance
The performance of `gluster-block` for restore/verification is far superior to that of `gluster-file-db`, however it should only be used in cases where the time it takes to verify a backup begins to encroach on the over-all timing and verification cycle. You want the verification(s) to complete before another backup and verification cycle begins and you want a bit of idle time between the end of one cycle and the beginning of another in case things take a little longer now and again.

Restore/Verification timing for a 9GB database:
- `gluster-block`: ~15 minutes
- `gluster-file-db`: ~1 hour

Restore/Verification timing for a 42GB database:
- `gluster-block`: ~1 hour
- `gluster-file-db`: ~3 hours
The performance of `netapp-block-standard` for restore/verification is far superior to that of `netapp-file-standard`, however it should only be used in cases where the time it takes to verify a backup begins to encroach on the over-all timing and verification cycle. You want the verification(s) to complete before another backup and verification cycle begins and you want a bit of idle time between the end of one cycle and the beginning of another in case things take a little longer now and again.

Restore/Verification timing for a 192GB database:
- `gluster-block`: not tested
- `gluster-file-db`: ~14.5 hours
*There are currently no performance stats for the `netapp` storage types.*

## Deployment / Configuration
Together, the scripts and templates provided in the [openshift](./openshift) directory will automatically deploy the `backup` app as described below. The [backup-deploy.overrides.sh](./openshift/backup-deploy.overrides.sh) script generates the deployment configuration necessary for the [backup.conf](config/backup.conf) file to be mounted as a ConfigMap by the `backup` container.
Expand All @@ -89,27 +80,29 @@ The following environment variables are defaults used by the `backup` app.

| Name | Default (if not set) | Purpose |
| ---- | ------- | ------- |
| BACKUP_STRATEGY | daily | To control the backup strategy used for backups. This is explained more below. |
| BACKUP_STRATEGY | rolling | To control the backup strategy used for backups. This is explained more below. |
| BACKUP_DIR | /backups/ | The directory under which backups will be stored. The deployment configuration mounts the persistent volume claim to this location when first deployed. |
| NUM_BACKUPS | 31 | For backward compatibility this value is used with the daily backup strategy to set the number of backups to retain before pruning. |
| NUM_BACKUPS | 31 | Used for backward compatibility only, this value is used with the daily backup strategy to set the number of backups to retain before pruning. |
| DAILY_BACKUPS | 6 | When using the rolling backup strategy this value is used to determine the number of daily (Mon-Sat) backups to retain before pruning. |
| WEEKLY_BACKUPS | 4 | When using the rolling backup strategy this value is used to determine the number of weekly (Sun) backups to retain before pruning. |
| MONTHLY_BACKUPS | 1 | When using the rolling backup strategy this value is used to determine the number of monthly (last day of the month) backups to retain before pruning. |
| BACKUP_PERIOD | 1d | Only used for Legacy Mode. Ignored when running in Cron Mode. The schedule on which to run the backups. The value is used by a sleep command and can be defined in d, h, m, or s. |
| DATABASE_SERVICE_NAME | postgresql | The name of the service/host for the *default* database target. |
| POSTGRESQL_DATABASE | my_postgres_db | The name of the *default* database target; the name of the database you want to backup. |
| POSTGRESQL_USER | *wired to a secret* | The username for the database(s) hosted by the `postgresql` Postgres server. The deployment configuration makes the assumption you have your database credentials stored in secrets (which you should), and the key for the username is `database-user`. The name of the secret must be provided as the `DATABASE_DEPLOYMENT_NAME` parameter to the deployment configuration template. |
| POSTGRESQL_PASSWORD | *wired to a secret* | The password for the database(s) hosted by the `postgresql` Postgres server. The deployment configuration makes the assumption you have your database credentials stored in secrets (which you should), and the key for the username is `database-password`. The name of the secret must be provided as the `DATABASE_DEPLOYMENT_NAME` parameter to the deployment configuration template. |
| DATABASE_SERVICE_NAME | postgresql | Used for backward compatibility only. The name of the service/host for the *default* database target. |
| DATABASE_NAME | my_postgres_db | Used for backward compatibility only. The name of the *default* database target; the name of the database you want to backup. |
| DATABASE_USER | *wired to a secret* | The username for the database(s) hosted by the database server. The deployment configuration makes the assumption you have your database credentials stored in secrets (which you should), and the key for the username is `database-user`. The name of the secret must be provided as the `DATABASE_DEPLOYMENT_NAME` parameter to the deployment configuration template. |
| DATABASE_PASSWORD | *wired to a secret* | The password for the database(s) hosted by the database server. The deployment configuration makes the assumption you have your database credentials stored in secrets (which you should), and the key for the username is `database-password`. The name of the secret must be provided as the `DATABASE_DEPLOYMENT_NAME` parameter to the deployment configuration template. |
| FTP_URL | | The FTP server URL. If not specified, the FTP backup feature is disabled. The default value in the deployment configuration is an empty value - not specified. |
| FTP_USER | *wired to a secret* | The username for the FTP server. The deployment configuration creates a secret with the name specified in the FTP_SECRET_KEY parameter (default: `ftp-secret`). The key for the username is `ftp-user` and the value is an empty value by default. |
| FTP_PASSWORD | *wired to a secret* | The password for the FTP server. The deployment configuration creates a secret with the name specified in the FTP_SECRET_KEY parameter (default: `ftp-secret`). The key for the password is `ftp-password` and the value is an empty value by default. |
| WEBHOOK_URL | | The URL of the webhook endpoint to use for notifications. If not specified, the webhook integration feature is disabled. The default value in the deployment configuration is an empty value - not specified. |
| ENVIRONMENT_FRIENDLY_NAME | | A friendly (human readable) name of the environment. This variable is used by the webhook integration to identify the environment from which the backup notifications originate. The default value in the deployment configuration is an empty value - not specified. |
| ENVIRONMENT_NAME | | A name or ID of the environment. This variable is used by the webhook integration to identify the environment from which the backup notifications originate. The default value in the deployment configuration is an empty value - not specified. |

Using this default configuration you can easily back up a single postgres database, however you can extend the configuration and use the `backup.conf` file to list a number of databases for backup and even set a cron schedule for the backups.
### backup.conf

Using this default configuration you can easily back up a single postgres database, however we recommend you extend the configuration and use the `backup.conf` file to list a number of databases for backup and even set a cron schedule for the backups.

When using the `backup.conf` file the following environment variables are ignored, since you list all of your `host`/`database` pairs in the file; `DATABASE_SERVICE_NAME`, `POSTGRESQL_DATABASE`. To provide the credentials needed for the listed databases you extend the deployment configuration to include `hostname_USER` and `hostname_PASSWORD` credential pairs which are wired to the appropriate secrets (where hostname matches the hostname/servicename, in all caps and underscores, of the database). For example, if you are backing up a database named `wallet-db/my_wallet`, you would have to extend the deployment configuration to include a `WALLET_DB_USER` and `WALLET_DB_PASSWORD` credential pair, wired to the appropriate secrets, to access the database(s) on the `wallet-db` server. You may notice the default configuration is already wired for the host/service name `postgresql`, so you're already covered if all your databases are on a server of that name.
When using the `backup.conf` file the following environment variables are ignored, since you list all of your `host`/`database` pairs in the file; `DATABASE_SERVICE_NAME`, `DATABASE_NAME`. To provide the credentials needed for the listed databases you extend the deployment configuration to include `hostname_USER` and `hostname_PASSWORD` credential pairs which are wired to the appropriate secrets (where hostname matches the hostname/servicename, in all caps and underscores, of the database). For example, if you are backing up a database named `wallet-db/my_wallet`, you would have to extend the deployment configuration to include a `WALLET_DB_USER` and `WALLET_DB_PASSWORD` credential pair, wired to the appropriate secrets, to access the database(s) on the `wallet-db` server.

### Cron Mode

Expand Down
7 changes: 7 additions & 0 deletions config/backup.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,16 @@
# Databases will be backed up in the order they are listed.
#
# The entries must be in one of the following forms:
# - <Hostname/>/<DatabaseName/>
# - <Hostname/>:<Port/>/<DatabaseName/>
# - <DatabaseType>=<Hostname/>/<DatabaseName/>
# - <DatabaseType>=<Hostname/>:<Port/>/<DatabaseName/>
# <DatabaseType> can be postgres or mongo
# <DatabaseType> MUST be specified when you are sharing a
# single backup.conf file between postgres and mongo
# backup containers. If you do not specify <DatabaseType>
# the listed databases are assumed to be valid for the
# backup container in which the configuration is mounted.
#
# Examples:
# - postgres=postgresql/my_database
Expand Down
82 changes: 47 additions & 35 deletions docs/ExampleLog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,48 +3,60 @@
```
Starting backup process ...
Reading backup config from backup.conf ...
Making backup directory /backups/daily/2018-10-04/ ...
Making backup directory /backups/daily/2020-02-28/ ...
Settings:
- Run mode: scheduled
- Backup strategy: rolling
- Backup type: daily
- Number of each backup to retain: 6
- Backup folder: /backups/daily/2018-10-04/
- Databases:
- wallet-db:5432/tob_verifier
- postgresql:5432/TheOrgBook_Database
- wallet-db:5432/tob_holder
Backing up wallet-db:5432/tob_verifier ...
Elapsed time: 0h:0m:1s
Backup written to /backups/daily/2018-10-04/wallet-db-tob_verifier_2018-10-04_22-49-39.sql.gz ...
Backing up postgresql:5432/TheOrgBook_Database ...
Elapsed time: 0h:2m:48s
Backup written to /backups/daily/2018-10-04/postgresql-TheOrgBook_Database_2018-10-04_22-49-41.sql.gz ...
Backing up wallet-db:5432/tob_holder ...
Elapsed time: 0h:24m:34s
Backup written to /backups/daily/2018-10-04/wallet-db-tob_holder_2018-10-04_22-52-29.sql.gz ...
- Current backup type: daily
- Backups to retain:
- Daily: 6
- Weekly: 4
- Monthly: 1
- Current backup folder: /backups/daily/2020-02-28/
- Time Zone: PST -0800
- Schedule:
- 0 1 * * * default ./backup.sh -s
- 0 4 * * * default ./backup.sh -s -v all
- Container Type: mongo
- Databases (filtered by container type):
- mongo=identity-kit-db-bc/identity_kit_db
- FTP server: not configured
- Webhook Endpoint: https://chat.pathfinder.gov.bc.ca/hooks/***
- Environment Friendly Name: Verifiable Organizations Network (mongo-test)
- Environment Name (Id): devex-von-test
Backing up 'identity-kit-db-bc/identity_kit_db' to '/backups/daily/2020-02-28/identity-kit-db-bc-identity_kit_db_2020-02-28_08-07-10.sql.gz.in_progress' ...
Successfully backed up mongo=identity-kit-db-bc/identity_kit_db.
Backup written to /backups/daily/2020-02-28/identity-kit-db-bc-identity_kit_db_2020-02-28_08-07-10.sql.gz.
Database Size: 1073741824
Backup Size: 4.0K
Elapsed time: 0h:0m:0s - Status Code: 0
================================================================================================================================
Current Backups:
Database Current Size
mongo=identity-kit-db-bc/identity_kit_db 1073741824
Filesystem Size Used Avail Use% Mounted on
192.168.111.90:/trident_qtree_pool_file_standard_WKDMGDWTSQ/file_standard_devex_von_test_backup_mongo_54218 1.0G 0 1.0G 0% /backups
--------------------------------------------------------------------------------------------------------------------------------
4.0K 2018-10-04 17:10 /backups/.trashcan/internal_op
8.0K 2018-10-04 17:10 /backups/.trashcan
3.5K 2018-10-04 17:17 /backups/daily/2018-10-04/wallet-db-tob_verifier_2018-10-04_17-17-02.sql.gz
687M 2018-10-04 17:20 /backups/daily/2018-10-04/postgresql-TheOrgBook_Database_2018-10-04_17-17-03.sql.gz
9.1G 2018-10-04 17:44 /backups/daily/2018-10-04/wallet-db-tob_holder_2018-10-04_17-20-06.sql.gz
3.5K 2018-10-04 17:48 /backups/daily/2018-10-04/wallet-db-tob_verifier_2018-10-04_17-48-42.sql.gz
687M 2018-10-04 17:51 /backups/daily/2018-10-04/postgresql-TheOrgBook_Database_2018-10-04_17-48-44.sql.gz
9.1G 2018-10-04 18:16 /backups/daily/2018-10-04/wallet-db-tob_holder_2018-10-04_17-51-36.sql.gz
3.5K 2018-10-04 22:49 /backups/daily/2018-10-04/wallet-db-tob_verifier_2018-10-04_22-49-39.sql.gz
687M 2018-10-04 22:52 /backups/daily/2018-10-04/postgresql-TheOrgBook_Database_2018-10-04_22-49-41.sql.gz
9.1G 2018-10-04 23:17 /backups/daily/2018-10-04/wallet-db-tob_holder_2018-10-04_22-52-29.sql.gz
30G 2018-10-04 23:17 /backups/daily/2018-10-04
30G 2018-10-04 23:17 /backups/daily
30G 2018-10-04 23:17 /backups/
4.0K 2020-02-27 13:26 /backups/daily/2020-02-27/identity-kit-db-bc-identity_kit_db_2020-02-27_13-26-21.sql.gz
4.0K 2020-02-27 13:27 /backups/daily/2020-02-27/identity-kit-db-bc-identity_kit_db_2020-02-27_13-27-10.sql.gz
12K 2020-02-27 13:27 /backups/daily/2020-02-27
4.0K 2020-02-28 06:44 /backups/daily/2020-02-28/identity-kit-db-bc-identity_kit_db_2020-02-28_06-44-19.sql.gz
4.0K 2020-02-28 07:12 /backups/daily/2020-02-28/identity-kit-db-bc-identity_kit_db_2020-02-28_07-12-29.sql.gz
4.0K 2020-02-28 08:07 /backups/daily/2020-02-28/identity-kit-db-bc-identity_kit_db_2020-02-28_08-07-10.sql.gz
16K 2020-02-28 08:07 /backups/daily/2020-02-28
32K 2020-02-28 08:07 /backups/daily
36K 2020-02-28 08:07 /backups/
================================================================================================================================
Sleeping for 1d ...
Scheduled backup run complete.
```
Binary file modified docs/SampleRocketChatMessage.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions openshift/templates/backup/backup-build.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@
{
"name": "NAME",
"displayName": "Name",
"description": "The name assigned to all of the resources defined in this template.",
"description": "The name assigned to all of the resources. Use 'backup-postgres' for Postgres builds or 'backup-mongo' for MongoDB builds.",
"required": true,
"value": "backup-postgres"
},
Expand Down Expand Up @@ -87,7 +87,7 @@
{
"name": "DOCKER_FILE_PATH",
"displayName": "Docker File",
"description": "The path and file of the docker file defining the build. Choose either 'Dockerfile' for Postgres bulds or 'Dockerfile_Mongo' for MongoDB build",
"description": "The path and file of the docker file defining the build. Choose either 'Dockerfile' for Postgres builds or 'Dockerfile_Mongo' for MongoDB builds.",
"required": false,
"value": "Dockerfile"
},
Expand Down
Loading

0 comments on commit 377cb2b

Please sign in to comment.