(PE-35906) Adding plans for backing up and restoring CA (#400)

Utilising puppet_backup for backing up and restoring CA and SSL certificates on a target

Author: ragingra

REFERENCE.md

@@ -85,9 +85,11 @@
 #### Public Plans
 
 * [`peadm::add_database`](#peadm--add_database)
+* [`peadm::backup_ca`](#peadm--backup_ca)
 * [`peadm::convert`](#peadm--convert): Convert an existing PE cluster to a PEAdm-managed cluster
 * [`peadm::install`](#peadm--install): Install a new PE cluster
 * [`peadm::modify_certificate`](#peadm--modify_certificate): Modify the certificate of one or more targets
+* [`peadm::restore_ca`](#peadm--restore_ca)
 * [`peadm::status`](#peadm--status): Return status information from one or more PE clusters in a table format
 * [`peadm::upgrade`](#peadm--upgrade): Upgrade a PEAdm-managed cluster
 
@@ -1527,6 +1529,31 @@ Optional[Enum[
 
 Default value: `undef`
 
+### <a name="peadm--backup_ca"></a>`peadm::backup_ca`
+
+The peadm::backup_ca class.
+
+#### Parameters
+
+The following parameters are available in the `peadm::backup_ca` plan:
+
+* [`target`](#-peadm--backup_ca--target)
+* [`output_directory`](#-peadm--backup_ca--output_directory)
+
+##### <a name="-peadm--backup_ca--target"></a>`target`
+
+Data type: `Peadm::SingleTargetSpec`
+
+
+
+##### <a name="-peadm--backup_ca--output_directory"></a>`output_directory`
+
+Data type: `Optional[String]`
+
+
+
+Default value: `'/tmp'`
+
 ### <a name="peadm--convert"></a>`peadm::convert`
 
 This plan sets required certificate extensions on PE nodes, and configures
@@ -1965,6 +1992,38 @@ Data type: `Boolean`
 
 Default value: `false`
 
+### <a name="peadm--restore_ca"></a>`peadm::restore_ca`
+
+The peadm::restore_ca class.
+
+#### Parameters
+
+The following parameters are available in the `peadm::restore_ca` plan:
+
+* [`target`](#-peadm--restore_ca--target)
+* [`file_path`](#-peadm--restore_ca--file_path)
+* [`recovery_directory`](#-peadm--restore_ca--recovery_directory)
+
+##### <a name="-peadm--restore_ca--target"></a>`target`
+
+Data type: `Peadm::SingleTargetSpec`
+
+
+
+##### <a name="-peadm--restore_ca--file_path"></a>`file_path`
+
+Data type: `String`
+
+
+
+##### <a name="-peadm--restore_ca--recovery_directory"></a>`recovery_directory`
+
+Data type: `Optional[String]`
+
+
+
+Default value: `'/tmp/peadm_recovery'`
+
 ### <a name="peadm--status"></a>`peadm::status`
 
 Return status information from one or more PE clusters in a table format

documentation/backup_restore_ca.md

@@ -0,0 +1,39 @@
+# Backup and Restore Puppet Enterprise CA
+
+## Overview
+Backup and restore plans for the Puppet Enterprise CA. This utilises the [puppet_backup](https://www.puppet.com/docs/pe/2023.4/backing_up_and_restoring_pe.html) tool. This plan has scope set to only CERTS, and will backup CA and SSL certificates. The backup plan will create a tarball of the CA and store it by default in the `/tmp` directory. The restore plan will restore the CA from the tarball at the path you provide.
+
+## Notes
+There can be some downtime associated with the restore process. Restore will stop PE services, restore the CA, and then start the PE services. This can take a few minutes.
+
+## Usage
+
+### Backup
+
+```bash
+peadm backup_ca target=primary.example.com
+```
+
+Backup will output the path to a timestamped folder containing the backup file. The backup file will be named `backup_ca.tgz`. At this stage the backup file can be copied to a safe location.
+
+Optionaly "output_directory" can be specified to change the location of the backup file.
+
+```bash
+peadm::backup_ca target=primary.example.com output_directory=/custompath
+```
+
+### Restore
+
+```bash
+peadm::restore_ca target=primary2.example.com path=/tmp/backup_ca.tgz file_path=/tmp/backup_ca.tgz
+```
+
+Restore will stop PE services, restore the CA, and then start the PE services. This can take a few minutes.
+
+Optionaly "recovery_directory" can be specified to change the temporary location where the backup file will be unzipped.
+
+```bash
+peadm::restore_ca target=primary2.example.com path=/tmp/backup_ca.tgz file_path=/tmp/backup_ca.tgz recovery_directory=/custompath
+```
+
+

plans/backup_ca.pp

@@ -0,0 +1,26 @@
+plan peadm::backup_ca(
+  Peadm::SingleTargetSpec $target,
+  Optional[String]                  $output_directory = '/tmp',
+) {
+  out::message('# Backing up ca and ssl certificates')
+  # lint:ignore:strict_indent
+
+  $timestamp = Timestamp.new().strftime('%Y-%m-%dT%H%M%SZ')
+  $backup_directory = "${output_directory}/pe-backup-${timestamp}"
+
+  # Create backup folder
+  apply($target) {
+    file { $backup_directory :
+      ensure => 'directory',
+      owner  => 'root',
+      group  => 'root',
+      mode   => '0700',
+    }
+  }
+
+  run_command(@("CMD"), $target)
+    /opt/puppetlabs/bin/puppet-backup create --dir=${shellquote($backup_directory)} --name=ca_backup.tgz --scope=certs
+    | CMD
+  # lint:endignore
+  return({ 'path' => "${backup_directory}/ca_backup.tgz" })
+}

plans/restore_ca.pp

@@ -0,0 +1,16 @@
+plan peadm::restore_ca(
+  Peadm::SingleTargetSpec $target,
+  String                  $file_path,
+  Optional[String]                  $recovery_directory = '/tmp/peadm_recovery',
+) {
+  out::message('# Restoring ca and ssl certificates')
+
+  # lint:ignore:strict_indent
+  run_command(@("CMD"/L), $target)
+    /opt/puppetlabs/bin/puppet-backup restore \
+    --scope=certs \
+    --tempdir=${shellquote($recovery_directory)} \
+    --force \
+    ${shellquote($file_path)}
+  | CMD
+}

spec/plans/backup_ca_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+describe 'peadm::backup_ca' do
+  include BoltSpec::Plans
+
+  let(:params) { { 'target' => 'myserver.example.com' } }
+
+  it 'will create backup directory and run puppet-backup command' do
+    allow_apply
+    expect_out_message.with_params('# Backing up ca and ssl certificates')
+    allow_any_command
+    expect(run_plan('peadm::backup_ca', params)).to be_ok
+  end
+end

spec/plans/restore_ca_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe 'peadm::restore_ca' do
+  include BoltSpec::Plans
+
+  let(:params) do
+    {
+      'target' => 'myserver.example.com',
+      'file_path' => '/tmp/backup_ca.tgz'
+    }
+  end
+
+  it 'will run puppet-backup command' do
+    expect_out_message.with_params('# Restoring ca and ssl certificates')
+    allow_any_command
+    expect(run_plan('peadm::restore_ca', params)).to be_ok
+  end
+end