feat: add group and batch patching

REFERENCE.md

@@ -21,6 +21,9 @@ the `os_patching` fact.
 [puppet health check](https://forge.puppet.com/albatrossflavour/puppet_health_check)
 module to perform a pre-check on the nodes you're planning to patch.  If the nodes pass the
 check, they get patched
+* [`os_patching::patch_batch`](#os_patching--patch_batch): Patch nodes in a batch, is called from patch_group plan or patch_pql plan
+* [`os_patching::patch_group`](#os_patching--patch_group): Patch nodes collected by a fact group
+* [`os_patching::patch_pql`](#os_patching--patch_pql): Patch nodes collected by a PQL query
 
 ## Classes
 
@@ -43,6 +46,7 @@ class { 'os_patching':
       'end'   => '2019-01-15T23:59:59+10:00',
     },
   },
+  group            => 'patching01',
 }
 ```
 
@@ -65,6 +69,7 @@ class profiles::soe::patching (
     patch_window     => $patch_window,
     reboot_override  => $reboot_override,
     blackout_windows => $full_blackout_windows,
+    group            => 'patching01',
   }
 }
 ```
@@ -119,6 +124,7 @@ The following parameters are available in the `os_patching` class:
 * [`windows_update_interval_mins`](#-os_patching--windows_update_interval_mins)
 * [`fact_mode`](#-os_patching--fact_mode)
 * [`ensure`](#-os_patching--ensure)
+* [`group`](#-os_patching--group)
 
 ##### <a name="-os_patching--puppet_binary"></a>`puppet_binary`
 
@@ -212,7 +218,7 @@ This overrides the setting in the task
 
 ##### <a name="-os_patching--patch_window"></a>`patch_window`
 
-Data type: `Optional[String]`
+Data type: `Optional[Pattern[/^[A-Za-z0-9\-_ ]+$/]]`
 
 A freeform text entry used to allocate a node to a specific patch window (Optional)
 
@@ -296,6 +302,14 @@ Data type: `Enum['present', 'absent']`
 
 `present` to install scripts, cronjobs, files, etc, `absent` to cleanup a system that previously hosted us
 
+##### <a name="-os_patching--group"></a>`group`
+
+Data type: `Optional[Pattern[/^[A-Za-z0-9\-_ ]+$/]]`
+
+The group to assign the node for patching purposes.
+
+Default value: `undef`
+
 ## Tasks
 
 ### <a name="clean_cache"></a>`clean_cache`
@@ -399,3 +413,197 @@ Data type: `Optional[Integer]`
 
 Default value: `1800`
 
+### <a name="os_patching--patch_batch"></a>`os_patching::patch_batch`
+
+Patch nodes in a batch, is called from patch_group plan or patch_pql plan
+
+#### Parameters
+
+The following parameters are available in the `os_patching::patch_batch` plan:
+
+* [`batch`](#-os_patching--patch_batch--batch)
+* [`catch_errors`](#-os_patching--patch_batch--catch_errors)
+* [`noop_state`](#-os_patching--patch_batch--noop_state)
+* [`run_health_check`](#-os_patching--patch_batch--run_health_check)
+* [`service_enabled`](#-os_patching--patch_batch--service_enabled)
+* [`service_running`](#-os_patching--patch_batch--service_running)
+* [`runinterval`](#-os_patching--patch_batch--runinterval)
+* [`debug`](#-os_patching--patch_batch--debug)
+
+##### <a name="-os_patching--patch_batch--batch"></a>`batch`
+
+Data type: `TargetSpec`
+
+The batch of nodes to patch
+
+##### <a name="-os_patching--patch_batch--catch_errors"></a>`catch_errors`
+
+Data type: `Boolean`
+
+Whether to catch errors during task execution
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_batch--noop_state"></a>`noop_state`
+
+Data type: `Boolean`
+
+Whether to consider noop state during health check
+
+Default value: `false`
+
+##### <a name="-os_patching--patch_batch--run_health_check"></a>`run_health_check`
+
+Data type: `Boolean`
+
+Whether to run a health check before patching
+
+Default value: `false`
+
+##### <a name="-os_patching--patch_batch--service_enabled"></a>`service_enabled`
+
+Data type: `Boolean`
+
+Whether the puppet service should be enabled during health check
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_batch--service_running"></a>`service_running`
+
+Data type: `Boolean`
+
+Whether the puppet service should be running during health check
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_batch--runinterval"></a>`runinterval`
+
+Data type: `Integer[0]`
+
+The runinterval to use during health check
+
+Default value: `1800`
+
+##### <a name="-os_patching--patch_batch--debug"></a>`debug`
+
+Data type: `Boolean`
+
+Whether to enable debug output
+
+Default value: `false`
+
+### <a name="os_patching--patch_group"></a>`os_patching::patch_group`
+
+Patch nodes collected by a fact group
+
+#### Parameters
+
+The following parameters are available in the `os_patching::patch_group` plan:
+
+* [`group`](#-os_patching--patch_group--group)
+* [`patch_in_batches`](#-os_patching--patch_group--patch_in_batches)
+* [`batch_size`](#-os_patching--patch_group--batch_size)
+* [`run_health_check`](#-os_patching--patch_group--run_health_check)
+* [`debug`](#-os_patching--patch_group--debug)
+* [`pql_query`](#-os_patching--patch_group--pql_query)
+
+##### <a name="-os_patching--patch_group--group"></a>`group`
+
+Data type: `String[1]`
+
+The fact group name to patch
+
+##### <a name="-os_patching--patch_group--patch_in_batches"></a>`patch_in_batches`
+
+Data type: `Boolean`
+
+Whether to patch nodes in batches
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_group--batch_size"></a>`batch_size`
+
+Data type: `Integer[0]`
+
+The size of each batch if patching in batches
+
+Default value: `15`
+
+##### <a name="-os_patching--patch_group--run_health_check"></a>`run_health_check`
+
+Data type: `Boolean`
+
+Whether to run a health check after patching
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_group--debug"></a>`debug`
+
+Data type: `Boolean`
+
+Whether to enable debug output
+
+Default value: `false`
+
+##### <a name="-os_patching--patch_group--pql_query"></a>`pql_query`
+
+Data type: `String[1]`
+
+The PQL query to retrieve nodes in the group
+
+Default value: `"inventory[certname] { facts.os_patching.group = '${group}'}"`
+
+### <a name="os_patching--patch_pql"></a>`os_patching::patch_pql`
+
+Patch nodes collected by a PQL query
+
+#### Parameters
+
+The following parameters are available in the `os_patching::patch_pql` plan:
+
+* [`pql_query`](#-os_patching--patch_pql--pql_query)
+* [`patch_in_batches`](#-os_patching--patch_pql--patch_in_batches)
+* [`batch_size`](#-os_patching--patch_pql--batch_size)
+* [`run_health_check`](#-os_patching--patch_pql--run_health_check)
+* [`debug`](#-os_patching--patch_pql--debug)
+
+##### <a name="-os_patching--patch_pql--pql_query"></a>`pql_query`
+
+Data type: `String[1]`
+
+The PQL query to retrieve nodes to patch
+
+Default value: `'inventory[certname] { facts.os.family = "redhat" }'`
+
+##### <a name="-os_patching--patch_pql--patch_in_batches"></a>`patch_in_batches`
+
+Data type: `Boolean`
+
+Whether to patch nodes in batches
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_pql--batch_size"></a>`batch_size`
+
+Data type: `Integer[0]`
+
+The size of each batch if patching in batches
+
+Default value: `15`
+
+##### <a name="-os_patching--patch_pql--run_health_check"></a>`run_health_check`
+
+Data type: `Boolean`
+
+Whether to run a health check after patching
+
+Default value: `true`
+
+##### <a name="-os_patching--patch_pql--debug"></a>`debug`
+
+Data type: `Boolean`
+
+Whether to enable debug output
+
+Default value: `false`
+

lib/facter/os_patching.rb

@@ -302,5 +302,21 @@
       data['blocked_reasons'] = blocked_reasons
       data
     end
+
+    chunk(:group) do
+      data = {}
+      groupfile = os_patching_dir + '/group'
+      if File.file?(groupfile)
+        group = File.open(groupfile, 'r').to_a
+        line = group.last.chomp
+        matchdata = line.match(/^(.*)$/)
+        if matchdata[0]
+          data['group'] = matchdata[0]
+        end
+      else
+        data['group'] = 'default'
+      end
+      data
+    end
   end
 end

manifests/init.pp

@@ -96,6 +96,9 @@
 # @param ensure
 #   `present` to install scripts, cronjobs, files, etc, `absent` to cleanup a system that previously hosted us
 #
+# @param group
+#   The group to assign the node for patching purposes.
+#
 # @example assign node to 'Week3' patching window, force a reboot and create a blackout window for the end of the year
 #   class { 'os_patching':
 #     patch_window     => 'Week3',
@@ -106,6 +109,7 @@
 #         'end'   => '2019-01-15T23:59:59+10:00',
 #       },
 #     },
+#     group            => 'patching01',
 #   }
 #
 # @example An example profile to setup patching, sourcing blackout windows from hiera
@@ -125,6 +129,7 @@
 #       patch_window     => $patch_window,
 #       reboot_override  => $reboot_override,
 #       blackout_windows => $full_blackout_windows,
+#       group            => 'patching01',
 #     }
 #   }
 #
@@ -163,8 +168,9 @@
   Variant[Enum['absent'], Integer[1,31]] $patch_cron_monthday,
   Variant[Enum['absent'], Integer[0,7]] $patch_cron_weekday,
   Integer[0,59] $patch_cron_min = fqdn_rand(59),
-  Optional[String] $patch_window = undef,
+  Optional[Pattern[/^[A-Za-z0-9\-_ ]+$/]] $patch_window = undef,
   Optional[Hash] $blackout_windows = undef,
+  Optional[Pattern[/^[A-Za-z0-9\-_ ]+$/]] $group = undef,
 ) {
   # None tunable
   $cache_dir = lookup('os_patching::cache_dir',Stdlib::Absolutepath,first,undef)
@@ -207,10 +213,6 @@
     default   => 'absent',
   }
 
-  if ($patch_window and $patch_window !~ /[A-Za-z0-9\-_ ]+/ ) {
-    fail('The patch window can only contain alphanumerics, space, underscore and dash')
-  }
-
   file { $cache_dir:
     ensure => $ensure_dir,
     force  => true,
@@ -243,6 +245,11 @@
     default => 'absent'
   }
 
+  $group_ensure = ($ensure == 'present' and $group) ? {
+    true    => 'file',
+    default => 'absent',
+  }
+
   file { "${cache_dir}/patch_window":
     ensure  => $patch_window_ensure,
     content => $patch_window,
@@ -258,6 +265,11 @@
     notify => Exec[$fact_exec],
   }
 
+  file { "${cache_dir}/group":
+    ensure  => $group_ensure,
+    content => $group,
+  }
+
   $reboot_override_ensure = ($ensure == 'present' and $reboot_override) ? {
     true    => 'file',
     default => 'absent',
@@ -314,6 +326,7 @@
         "${cache_dir}/patch_window",
         "${cache_dir}/reboot_override",
         "${cache_dir}/blackout_windows",
+        "${cache_dir}/group",
       ],
     }
   }

plans/patch_after_healthcheck.pp

@@ -9,13 +9,12 @@
 ) {
   # Run an initial health check to make sure the target nodes are ready
 
-  $health_checks = run_task('puppet_health_check::agent_health',
-    $nodes,
+  $health_checks = run_task('puppet_health_check::agent_health', $nodes,
     target_noop_state      => $noop_state,
     target_service_enabled => true,
     target_service_running => true,
     target_runinterval     => $runinterval,
-    '_catch_errors'        => true,
+    _catch_errors          => true,
   )
 
   $nodes_to_patch = $health_checks.filter | $items | { $items.value['state'] == 'clean' }