Merge pull request #1319 from fraenki/pg_dump

(MODULES-11251) Add support for backup provider "pg_dump"

Author: david22swan

.fixtures.yml

@@ -5,6 +5,7 @@ fixtures:
       repo: "https://github.com/puppetlabs/puppetlabs-augeas_core.git"
       puppet_version: ">= 6.0.0"
     concat: "https://github.com/puppetlabs/puppetlabs-concat.git"
+    cron_core: "https://github.com/puppetlabs/puppetlabs-cron_core.git"
     facts: 'https://github.com/puppetlabs/puppetlabs-facts.git'
     firewall: "https://github.com/puppetlabs/puppetlabs-firewall.git"
     provision: "https://github.com/puppetlabs/provision.git"

README.md

@@ -15,6 +15,7 @@
     * [Create an access rule for pg_hba.conf](#create-an-access-rule-for-pg_hbaconf)
     * [Create user name maps for pg_ident.conf](#create-user-name-maps-for-pg_identconf)
     * [Validate connectivity](#validate-connectivity)
+    * [Backups](#backups)
 4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
 5. [Limitations - OS compatibility, etc.](#limitations)
 6. [Development - Guide for contributing to the module](#development)
@@ -328,6 +329,26 @@ postgresql_conn_validator { 'validate my postgres connection':
 }
 ```
 
+### Backups
+
+This example demonstrates how to configure PostgreSQL backups with "pg_dump". This sets up a daily cron job to perform a full backup. Each backup will create a new directory. A cleanup job will automatically remove backups that are older than 15 days.
+
+```
+class { 'postgresql::server':
+  backup_enable   => true,
+  backup_provider => 'pg_dump',
+  backup_options  => {
+    db_user     => 'backupuser',
+    db_password => 'secret',
+    manage_user => true,
+    rotate      => 15,
+  },
+  ...
+}
+```
+
+It is possible to set parameter `$ensure` to `absent` in order to remove the backup job, user/role, backup script and password file. However, the actual backup files and directories will remain untouched.
+
 ## Reference
 
 For information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-postgresql/blob/main/REFERENCE.md)

manifests/backup/pg_dump.pp

@@ -0,0 +1,151 @@
+# @summary
+#   "Provider" for pg_dump backup
+#
+# @api private
+#
+# @param compress
+#   Whether or not to compress the backup. Support for compression also depends on other backup parameters.
+# @param databases
+#   Databases to backup. By default `[]` will back up all databases.
+# @param db_user
+#   PostgreSQL user to create with superuser privileges.
+# @param db_password
+#   Password to create for `$db_user`.
+# @param dir
+#   Directory to store backup.
+# @param dir_mode
+#   Permissions applied to the backup directory. This parameter is passed directly to the file resource.
+# @param dir_owner
+#   Owner for the backup directory. This parameter is passed directly to the file resource.
+# @param dir_group
+#   Group owner for the backup directory. This parameter is passed directly to the file resource.
+# @param format
+#   Backup format to use, must be supported by pg_dump or pg_dumpall. The choice will affect other options, i.e. compression.
+# @param install_cron
+#   Manage installation of cron package.
+# @param manage_user
+#   Manage creation of the backup user.
+# @param optional_args
+#   Specifies an array of optional arguments which should be passed through to the backup tool. These options are not validated, unsupported options may break the backup.
+# @param postscript
+#   One or more scripts that are executed when the backup is finished. This could be used to sync the backup to a central store.
+# @param prescript
+#   One or more scripts that are executed before the backup begins.
+# @param rotate
+#   Backup rotation interval in 24 hour periods.
+# @param success_file_path
+#   Specify a path where upon successful backup a file should be created for checking purposes.
+# @param time
+#   An array of two elements to set the backup time. Allows `['23', '5']` (i.e., 23:05) or `['3', '45']` (i.e., 03:45) for HH:MM times.
+# @param weekday
+#   Weekdays on which the backup job should run. Defaults to `*`. This parameter is passed directly to the cron resource.
+#
+class postgresql::backup::pg_dump (
+  Boolean $compress = true,
+  Array $databases = [],
+  Boolean $delete_before_dump = false,
+  String[1] $dir,
+  String[1] $dir_group = '0',
+  String[1] $dir_mode = '0700',
+  String[1] $dir_owner = 'root',
+  Enum['present','absent'] $ensure = 'present',
+  Enum['plain','custom','directory','tar'] $format = 'plain',
+  Boolean $install_cron = true,
+  Boolean $manage_user = false,
+  Array $optional_args = [],
+  Stdlib::Absolutepath $pgpass_path = '/root/.pgpass',
+  Integer $rotate = 30,
+  Stdlib::Absolutepath $script_path = '/usr/local/sbin/pg_dump.sh',
+  Stdlib::Absolutepath $success_file_path = '/tmp/pgbackup_success',
+  String[1] $template = 'postgresql/pg_dump.sh.epp',
+  Array $time = ['23', '5'],
+  String[1] $weekday = '*',
+  Optional[Variant[String, Sensitive[String]]] $db_password = undef,
+  Optional[String[1]] $db_user = undef,
+  Optional[String[1]] $package_name = undef,
+  Optional[String[1]] $post_script = undef,
+  Optional[String[1]] $pre_script = undef,
+) {
+  # Install required packages
+  if $package_name {
+    ensure_packages($package_name)
+  }
+  if $install_cron {
+    if $facts['os']['family'] == 'RedHat' {
+      ensure_packages('cronie')
+    } elsif $facts['os']['family'] != 'FreeBSD' {
+      ensure_packages('cron')
+    }
+  }
+
+  # Setup db user with required permissions
+  if $manage_user and $db_user and $db_password {
+    # Create user with superuser privileges
+    postgresql::server::role { $db_user:
+      ensure        => $ensure,
+      password_hash => postgresql::postgresql_password($db_user, $db_password),
+      superuser     => true,
+    }
+
+    # Allow authentication from localhost
+    postgresql::server::pg_hba_rule { 'local access as backup user':
+      type        => 'local',
+      database    => 'all',
+      user        => $db_user,
+      auth_method => 'md5',
+      order       => 1,
+    }
+  }
+
+  # Create backup directory
+  file { $dir:
+    ensure => 'directory',
+    mode   => $dir_mode,
+    owner  => $dir_owner,
+    group  => $dir_group,
+  }
+
+  # Create backup script
+  file { $script_path:
+    ensure  => $ensure,
+    mode    => '0700',
+    owner   => 'root',
+    group   => '0', # Use GID for compat with Linux and BSD.
+    content => epp($template, {
+      compress           => $compress,
+      databases          => $databases,
+      db_user            => $db_user,
+      delete_before_dump => $delete_before_dump,
+      dir                => $dir,
+      format             => $format,
+      optional_args      => $optional_args,
+      post_script        => $post_script,
+      pre_script         => $pre_script,
+      rotate             => $rotate,
+      success_file_path  => $success_file_path,
+    }),
+  }
+
+  # Create password file for pg_dump
+  file { $pgpass_path:
+    ensure    => $ensure,
+    mode      => '0600',
+    owner     => 'root',
+    group     => '0', # Use GID for compat with Linux and BSD.
+    content   => inline_epp('*:*:*:<%= $db_user %>:<%= $db_password %>',{
+      db_password => $db_password,
+      db_user     => $db_user,
+    }),
+    show_diff => false,
+  }
+
+  # Create cron job
+  cron { 'pg_dump backup job':
+    ensure  => $ensure,
+    command => $script_path,
+    user    => 'root',
+    hour    => $time[0],
+    minute  => $time[1],
+    weekday => $weekday,
+  }
+}

manifests/params.pp

@@ -31,6 +31,9 @@
   $manage_logdir                = true
   $manage_xlogdir               = true
 
+  $backup_enable = false
+  $backup_provider = 'pg_dump'
+
   # Amazon Linux's OS Family is 'Linux', operating system 'Amazon'.
   case $facts['os']['family'] {
     'RedHat', 'Linux': {

manifests/server.pp

@@ -77,6 +77,10 @@
 # @param roles Specifies a hash from which to generate postgresql::server::role resources.
 # @param config_entries Specifies a hash from which to generate postgresql::server::config_entry resources.
 # @param pg_hba_rules Specifies a hash from which to generate postgresql::server::pg_hba_rule resources.
+
+# @param backup_enable Whether a backup job should be enabled.
+# @param backup_options A hash of options that should be passed through to the backup provider.
+# @param backup_provider Specifies the backup provider to use.
 #
 # @param version Deprecated. Use postgresql::globals instead. Sets PostgreSQL version
 #
@@ -152,6 +156,10 @@
   Hash[String, Any] $config_entries = {},
   Hash[String, Hash] $pg_hba_rules  = {},
 
+  Boolean $backup_enable = $postgresql::params::backup_enable,
+  Hash $backup_options = {},
+  Enum['pg_dump'] $backup_provider = $postgresql::params::backup_provider,
+
   #Deprecated
   $version                    = undef,
 ) inherits postgresql::params {
@@ -201,4 +209,17 @@
       * => $rule,
     }
   }
+
+  if $backup_enable {
+    case $backup_provider {
+      'pg_dump': {
+        class { 'postgresql::backup::pg_dump':
+          * => $backup_options,
+        }
+      }
+      default: {
+        fail("Unsupported backup provider '${backup_provider}'.")
+      }
+    }
+  }
 }

spec/classes/server_spec.rb

@@ -256,4 +256,62 @@ class { 'postgresql::globals':
         .with_address('192.0.2.100')
     end
   end
+
+  describe 'backup_enable => false' do
+    let(:params) { { backup_enable: false } }
+
+    it { is_expected.to contain_class('postgresql::server') }
+    it { is_expected.not_to contain_class('postgresql::backup::pg_dump') }
+    it { is_expected.not_to contain_file('/root/.pgpass') }
+    it { is_expected.not_to contain_file('/usr/local/sbin/pg_dump.sh') }
+    it { is_expected.not_to contain_cron('pg_dump backup job') }
+  end
+
+  describe 'backup_enable => true' do
+    let(:params) do
+      {
+        backup_enable: true,
+        backup_provider: 'pg_dump',
+        backup_options: {
+          db_user: 'backupuser',
+          db_password: 'backuppass',
+          dir: '/tmp/backuptest',
+          manage_user: true,
+        },
+      }
+    end
+
+    it { is_expected.to contain_class('postgresql::server') }
+    it { is_expected.to contain_class('postgresql::backup::pg_dump') }
+    it {
+      is_expected.to contain_postgresql__server__role('backupuser')
+        .with_superuser(true)
+    }
+    it {
+      is_expected.to contain_postgresql__server__pg_hba_rule('local access as backup user')
+        .with_type('local')
+        .with_database('all')
+        .with_user('backupuser')
+        .with_auth_method('md5')
+    }
+    it {
+      is_expected.to contain_file('/root/.pgpass')
+        .with_content(%r{.*:backupuser:.*})
+    }
+    it {
+      is_expected.to contain_file('/usr/local/sbin/pg_dump.sh')
+        .with_content(%r{.*pg_dumpall \$_pg_args --file=\$\{FILE\} \$@.*})
+    }
+    it {
+      is_expected.to contain_cron('pg_dump backup job')
+        .with(
+          ensure: 'present',
+          command: '/usr/local/sbin/pg_dump.sh',
+          user: 'root',
+          hour: '23',
+          minute: '5',
+          weekday: '*',
+        )
+    }
+  end
 end