a backup-manager app for Cloud Foundry
- MariaDB / MySQL
- PostgreSQL
- MongoDB
- Elasticsearch
- Redis
- pick a Cloud Foundry provider. I'd suggest the Swisscom AppCloud
- create a service instance of an S3-compatible object storage
- modify the provided
manifest.yml
, specify your service instance(s) - configure backman, either through the provided
config.json
or by the environment variableBACKMAN_CONFIG
(seemanifest.yml
) - deploy the app
- enjoy!
backman also supports running as a one-off task inside Cloud Foundry. Simply push the app as normal, stop it, and then run it via cf run-task
with /app/backman -backup <service_name>
as task command to run a backup. For restoring an existing backup you can use /app/backman -restore <service_name> -filename <backup_filename>
. (or just backman ...
if the app was pushed with native buildpacks and not as a docker image)
backman can be configured via JSON configuration, either with a file config.json
in its root directory, or by the environment variable BACKMAN_CONFIG
.
Values configured in BACKMAN_CONFIG
take precedence over config.json
.
By default backman will assume useful values for all services/backups unless configured otherwise.
Note: Configuration via the config.json
only makes sense when either pushing with buildpacks to CF, or by building your own docker image.
If you are using the provided docker image jamesclonk/backman
(as is default in the manifest) then there will be no configuration file and all configuration options need to be set via environment variables.
It is generally recommended to use the BACKMAN_CONFIG
environment variable for all your configuration needs.
These here are the default values backman will use if not configured via JSON:
{
"log_level": "info",
"logging_timestamp": false,
"disable_web": false,
"disable_metrics": false,
"unprotected_metrics": false,
"notifications": {
"teams": {
"webhook": "https://example.webhook.office.com/webhookb2/deadbeef/IncomingWebhook/beefdead/deadbeef",
"events": ["backup-success", "backup-failed"]
}
},
"s3": {
"service_label": "dynstrg",
"encryption_key":"a_super_strong_key"
},
"services": {
...
"<service-instance-name>": {
"schedule": "<random-second> <random-minute> <random-hour> * * *",
"timeout": "1h",
"retention": {
"days": 31,
"files": 100
}
}
...
}
}
backman can be secured through HTTP basic auth, with username and password provided either in the JSON configuration
{
"username": "http_basic_auth_user_abc",
"password": "http_basic_auth_password_xyz"
}
or through the specific environment variables BACKMAN_USERNAME
and BACKMAN_PASSWORD
(see manifest.yml
)
Possible JSON properties:
log_level
: optional, specifies log output level, can be info, warn, debug, errorlogging_timestamp
: optional, enable timestamping log output, not needed when deployed on Cloud Foundryusername
: optional, HTTP basic auth usernamepassword
: optional, HTTP basic auth passworddisable_web
: optional, disable web interface and apidisable_metrics
: optional, disable Prometheus metrics endpointunprotected_metrics
: optional, disable HTTP basic auth protection for Prometheus metrics endpointnotifications.teams.webhook
: optional, setting a webhook URL will enable MS Teams notifications about backupsnotifications.teams.events
: optional, list of events to send a Teams notification for. Can be backup-started, backup-success, backup-failed. Sends a notification for all events if empty.s3.disable_ssl
: optional, S3 client connections will use HTTP instead of HTTPSs3.skip_ssl_verification
: optional, S3 client will still use HTTPS but skips certificate verifications3.service_label
: optional, defines which service label backman will look for to find the S3-compatible object storages3.bucket_name
: optional, bucket to use on S3 storage, backman will use service-instance/binding-name if not configureds3.encryption_key
: optional, defines the key which will be used to encrypt and decrypt backups as they are stored on the S3 can also be passed as an environment variable with the nameBACKMAN_ENCRYPTION_KEY
services.<service-instance>.schedule
: optional, defines cron schedule for running backupsservices.<service-instance>.timeout
: optional, backman will abort a running backup/restore if timeout is exceededservices.<service-instance>.retention.days
: optional, specifies how long backman will keep backups on S3 at maximum for this service instanceservices.<service-instance>.retention.files
: optional, specifies how maximum number of files backman will keep on S3 for this service instanceservices.<service-instance>.direct_s3
: optional / Elasticsearch-specific, bypasses backman internal backup stream and encryption entirely, streaming directly from/to S3 via elasticdumpservices.<service-instance>.disable_column_statistics
: optional / MySQL-specific, allows for disabling export of column statistics. Set totrue
to avoid issues with pre-8.0 versions of MySQLservices.<service-instance>.force_import
: optional / MySQL-specific. Set totrue
to use the--force
flag for mysql, ignoring any errors that might occur while importing backupsservices.<service-instance>.log_stderr
: optional. Outputs stderr of backup process to stdout in case of errors or timeoutsservices.<service-instance>.local_backup_path
: optional / PostgreSQL-specific, path where to store backup files locally first before uploading them. Otherwise streams directly to S3 if not specifiedservices.<service-instance>.ignore_tables
: optional / MySQL-specific, array of table names to be ignored for the backupservices.<service-instance>.backup_options
: optional, allows specifying additional parameters and flags for service backup executableservices.<service-instance>.restore_options
: optional, allows specifying additional parameters and flags for service restore executable
Note: Usage of s3.encryption_key
is not backward compatible! Backups generated without or with a different encryption key cannot be downloaded or restored anymore.
backman can of course also be deployed onto a Kubernetes cluster. There are ytt templates provided under kubernetes/templates that can be used to generate and deploy to Kubernetes. Some useful helper scripts can be found under kubernetes.
- clone this repository
- go into the kubernetes folder
- edit
values.yml
. See sample_values.yml for reference. - run
./deploy.sh
Additionally if you don't want to use any of the carvel.dev tooling you can just make use of the provided example deploy.yml, which is a complete pre-rendered Kubernetes deployment manifest. Please edit it first though to adjust its backman configuration values, the Secret, Ingress and NetworkPolicy resources, the default values these contain will very likely not work for you!
backman exposes a couple of metrics via Prometheus endpoint /metrics
.
Example:
$ curl localhost:9990/metrics
# HELP backman_backup_files_total Number of backup files in total per service.
# TYPE backman_backup_files_total gauge
backman_backup_files_total{name="my-elasticsearch",type="elasticsearch"} 7
backman_backup_files_total{name="my_mongodb",type="mongodb"} 1
backman_backup_files_total{name="my_postgres_db",type="postgres"} 25
# HELP backman_backup_filesize_last Filesize of last / most recent backup file per service.
# TYPE backman_backup_filesize_last gauge
backman_backup_filesize_last{name="my-elasticsearch",type="elasticsearch"} 58404
backman_backup_filesize_last{name="my_mongodb",type="mongodb"} 1067
backman_backup_filesize_last{name="my_postgres_db",type="postgres"} 684
# HELP backman_backup_filesize_total Total filesize sum of all backup files per service.
# TYPE backman_backup_filesize_total gauge
backman_backup_filesize_total{name="my-elasticsearch",type="elasticsearch"} 408740
backman_backup_filesize_total{name="my_mongodb",type="mongodb"} 1067
backman_backup_filesize_total{name="my_postgres_db",type="postgres"} 7404
# HELP backman_backup_failures_total Total number of backup failures per service.
# TYPE backman_backup_failures_total counter
backman_backup_failures_total{name="my-elasticsearch",type="Elasticsearch"} 3
backman_backup_failures_total{name="my_mongodb",type="MongoDB"} 1
backman_backup_failures_total{name="my_postgres_db",type="PostgreSQL"} 3
# HELP backman_backup_success_total Total number of backup failures per service.
# TYPE backman_backup_success_total counter
backman_backup_success_total{name="my-elasticsearch",type="Elasticsearch"} 18
backman_backup_success_total{name="my_mongodb",type="MongoDB"} 4
backman_backup_success_total{name="my_postgres_db",type="PostgreSQL"} 4
# HELP backman_backup_queued Backups currently in queue per service.
# TYPE backman_backup_queued gauge
backman_backup_queued{name="my-elasticsearch",type="elasticsearch"} 0
backman_backup_queued{name="my_mongodb",type="mongodb"} 0
backman_backup_queued{name="my_postgres_db",type="postgres"} 0
# HELP backman_backup_running Current running state of backups triggered per service.
# TYPE backman_backup_running gauge
backman_backup_running{name="my-elasticsearch",type="elasticsearch"} 0
backman_backup_running{name="my_mongodb",type="mongodb"} 0
backman_backup_running{name="my_postgres_db",type="postgres"} 0
# HELP backman_backup_total Total number of backups triggered per service.
# TYPE backman_backup_total counter
backman_backup_total{name="my-elasticsearch",type="Elasticsearch"} 21
backman_backup_total{name="my_mongodb",type="MongoDB"} 5
backman_backup_total{name="my_postgres_db",type="PostgreSQL"} 7
# HELP backman_restore_failures_total Total number of restore failures per service.
# TYPE backman_restore_failures_total counter
backman_restore_failures_total{name="my-elasticsearch",type="Elasticsearch"} 2
# HELP backman_restore_success_total Total number of successful restores per service.
# TYPE backman_restore_success_total counter
backman_restore_success_total{name="my-elasticsearch",type="Elasticsearch"} 1
backman_restore_success_total{name="my_mongodb",type="MongoDB"} 2
# HELP backman_restore_queued Restores currently in queue per service.
# TYPE backman_restore_queued gauge
backman_restore_queued{name="my-elasticsearch",type="elasticsearch"} 0
backman_restore_queued{name="my_mongodb",type="mongodb"} 0
backman_restore_queued{name="my_postgres_db",type="postgres"} 0
# HELP backman_restore_running Current running state of restores triggered per service.
# TYPE backman_restore_running gauge
backman_restore_running{name="my-elasticsearch",type="elasticsearch"} 1
backman_restore_running{name="my_mongodb",type="mongodb"} 0
backman_restore_running{name="my_postgres_db",type="postgres"} 0
# HELP backman_restore_total Total number of restores triggered per service.
# TYPE backman_restore_total counter
backman_restore_total{name="my-elasticsearch",type="Elasticsearch"} 3
backman_restore_total{name="my_mongodb",type="MongoDB"} 2
# HELP backman_scheduler_backup_failures_total Total number of backup failures over crontab-schedule.
# TYPE backman_scheduler_backup_failures_total counter
backman_scheduler_backup_failures_total 0
# HELP backman_scheduler_backup_success_total Total number of successful backups over crontab-schedule.
# TYPE backman_scheduler_backup_success_total counter
backman_scheduler_backup_success_total 4
# HELP backman_scheduler_runs_total Total number of backup runs triggered over crontab-schedule.
# TYPE backman_scheduler_runs_total counter
backman_scheduler_runs_total 4
backman has an API which can be used to trigger backups & restores. Have a look at the Swagger documentation
- shows all bound service instances
- display service, trigger backups/restores