Skip to content

Latest commit

 

History

History
692 lines (382 loc) · 20.5 KB

REFERENCE.md

File metadata and controls

692 lines (382 loc) · 20.5 KB

Reference

Table of Contents

Classes

Defined types

Resource types

Functions

Tasks

  • install_kb: Immediately installs a specific KB update

Classes

patching_as_code

Framework for patch management as code. Works alongside the puppetlabs/pe_patch or albatrossflavour/os_patching modules

Examples

Using the module with defaults, or controlling options through Hiera
include patching_as_code
Forcing the classification of pe_patch on PE 2019.8.0+
class {'patching_as_code':
  classify_pe_patch => true
}
Forcing the use of albatrossflavour/os_patching on PE 2019.8.0+
class {'patching_as_code':
  use_pe_patch => false
}

Parameters

The following parameters are available in the patching_as_code class:

Variant

Data type: String, Array[String]

patch_group Name(s) of the patch_group(s) for this node. Must match one or more of the patch groups in $patch_schedule To assign multiple patch groups, provide this parameter as an array

patch_schedule

Data type: Hash

Hash of available patch_schedules. Default schedules are in /data/common.yaml of this module

Options:

  • :day_of_week String: Day of the week to patch, valid options: 'Any', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'
  • :count_of_week Variant[Integer,Array[Integer]]: Which week(s) in the month to patch, use number(s) between 1 and 5
  • :hours String: Which hours on patch day to patch, define a range as 'HH:MM - HH:MM'
  • :max_runs String: How many Puppet runs during the patch window can Puppet install patches. Must be at least 1.
  • :reboot String: Reboot behavior, valid options: 'always', 'never', 'ifneeded'

Default value: { 'weekly' => { 'day_of_week' => 'Thursday', 'count_of_week' => [1, 2, 3, 4, 5], 'hours' => '09:00 - 11:00', 'max_runs' => 4, 'reboot' => 'ifneeded' }, 'testing' => { 'day_of_week' => 'Thursday', 'count_of_week' => 2, 'hours' => '07:00 - 09:00', 'max_runs' => 4, 'reboot' => 'ifneeded' }, 'early' => { 'day_of_week' => 'Monday', 'count_of_week' => 3, 'hours' => '20:00 - 22:00', 'max_runs' => 4, 'reboot' => 'ifneeded' }, 'primary' => { 'day_of_week' => 'Friday', 'count_of_week' => 3, 'hours' => '22:00 - 00:00', 'max_runs' => 4, 'reboot' => 'ifneeded' }, 'secondary' => { 'day_of_week' => 'Saturday', 'count_of_week' => 3, 'hours' => '22:00 - 00:00', 'max_runs' => 4, 'reboot' => 'ifneeded' }, 'late' => { 'day_of_week' => 'Saturday', 'count_of_week' => 4, 'hours' => '22:00 - 00:00', 'max_runs' => 4, 'reboot' => 'ifneeded' } }

blocklist

Data type: Array

List of updates to block from installing

Default value: []

allowlist

Data type: Array

List of updates that are allowed to be installed. Any updates not on this list get blocked.

Default value: []

blocklist_choco

Data type: Array

List of Chocolatey updates to block from installing

Default value: []

allowlist_choco

Data type: Array

List of Chocolatey updates that are allowed to be installed. Any Chocolatey updates not on this list get blocked.

Default value: []

high_priority_patch_group

Data type: String

Name of the high_priority_patch_group for this node. Must match a patch group in $patch_schedule This patch schedule will only be used for patches in the $high_priority_list.

Default value: 'never'

high_priority_list

Data type: Array

List of updates to install on the patch schedule set by $high_priority_patch_group.

Default value: []

high_priority_list_choco

Data type: Array

List of Chocolatey updates to install on the patch schedule set by $high_priority_patch_group.

Default value: []

unsafe_process_list

Data type: Array

List of processes that will cause patching to be skipped if any of the processes in the list are active on the system. Prepend an entry with {full} to match against the full process arguments.

Default value: []

pre_patch_commands

Data type: Hash

Hash of command to run before patching

Options:

  • :command String: The pre-patching command to execute
  • :path String: The path for the command
  • :provider String: The provider for the command

Default value: {}

post_patch_commands

Data type: Hash

Hash of command to run after patching

Options:

  • :command String: The post-patching command to execute
  • :path String: The path for the command
  • :provider String: The provider for the command

Default value: {}

pre_reboot_commands

Data type: Hash

Hash of command to run before rebooting

Options:

  • :command String: The pre-reboot command to execute
  • :path String: The path for the command
  • :provider String: The provider for the command Note: the provider for the command gets forced to posix on Linux and powershell on Windows

Default value: {}

fact_upload

Data type: Boolean

How os_patching/pe_patch handles changes to fact cache. Defaults to true. When true (default), puppet fact upload occurs as expected When false, changes to fact cache are not uploaded

Default value: true

enable_patching

Data type: Boolean

Controls if patching_as_code is allowed to install any updates. Can be used to disable patching with a single override. Can be used to disable patching with a single override.

Default value: true

security_only

Data type: Boolean

Install only security updates. Requires latest version of Puppet Enterprise to work on Windows. When using os_patching, security updates can only be applied to Linux. If patching of Chocolatey packages is enabled, Chocolatey packages will still update even if security_only is set to true.

Default value: false

high_priority_only

Data type: Boolean

Only allow updates from the $high_priority_list to be installed. Enabling this option will prevent regular patches from being installed, and will skip a pending reboot at the beginning of the patch run if a pending reboot is detected. A pending reboot may still happen at the end of the patch run, as long as the patch schedule set by $high_priority_patch_group allows reboots to occur.

Default value: false

patch_choco

Data type: Boolean

Also patch outdated Chocolatey packages (on Windows)

Default value: false

use_pe_patch

Data type: Boolean

Use the pe_patch module if available (PE 2019.8+). Defaults to true.

Default value: true

classify_pe_patch

Data type: Boolean

Controls if the pe_patch class (PE 2019.8+) is controlled by this module. When enabled, this module will classify the node with pe_patch, and set it's patch_group according to this module's patch_group. When disabled (default), you can use PE's own "PE Patch Management" groups to classify nodes with pe_patch. In that case, please make sure you match the patch_group variable in pe_patch with the patch_group in patching_as_code

Default value: false

patch_on_metered_links

Data type: Boolean

Controls if patches are installed when the active network connection is a metered link. This setting only has affect for Windows operating systems. When enabled, patching are installed even over a metered link. When disabled (default), patches are not installed over a metered link.

Default value: false

plan_patch_fact

Data type: Optional[String]

Reserved parameter for running patching_as_code via a Plan (future functionality).

Default value: undef

patch_group

Data type: Variant[String,Array[String]]

Default value: 'primary'

patching_as_code::high_prio_reboot

Class: patching_as_code::high_prio_reboot

Parameters

The following parameters are available in the patching_as_code::high_prio_reboot class:

reboot_if_needed

Data type: Boolean

Only reboot the node if a system reboot is pending. This parameter is passed automatically from init.pp

Default value: true

reboot_delay

Data type: Integer

Time in seconds to delay the reboot by, defaults to 2 minutes. To override for patching, specify an alternate value by setting the patching_as_code::high_prio_reboot::reboot_delay parameter in Hiera.

Default value: 120

patching_as_code::linux::patchday

Class: patching_as_code::linux::patchday

Parameters

The following parameters are available in the patching_as_code::linux::patchday class:

updates

Data type: Array

List of Linux packages to update.

choco_updates

Data type: Array

List of Chocolatey packages to update, which should always be empty for Linux. This parameter exists only for compability.

Default value: []

high_prio_updates

Data type: Array

List of high-priority Linux packages to update.

Default value: []

high_prio_choco_updates

Data type: Array

List of high-priority Chocolatey packages to update, which should always be empty for Linux. This parameter exists only for compability.

Default value: []

patching_as_code::reboot

Class: patching_as_code::reboot

Parameters

The following parameters are available in the patching_as_code::reboot class:

reboot_if_needed

Data type: Boolean

Only reboot the node if a system reboot is pending. This parameter is passed automatically from init.pp

Default value: true

reboot_delay

Data type: Integer

Time in seconds to delay the reboot by, defaults to 2 minutes. To override for patching, specify an alternate value by setting the patching_as_code::reboot::reboot_delay parameter in Hiera.

Default value: 120

patching_as_code::windows::patchday

Class: patching_as_code::windows::patchday

Parameters

The following parameters are available in the patching_as_code::windows::patchday class:

updates

Data type: Array

List of Windows KB patches to install.

choco_updates

Data type: Array

List of Chocolatey packages to update.

high_prio_updates

Data type: Array

List of high-priority Windows KB patches to install.

Default value: []

high_prio_choco_updates

Data type: Array

List of high-priority Chocolatey packages to update.

Default value: []

patching_as_code::wu

class patching_as_code::wu

Defined types

patching_as_code::kb

define patching_as_code::kb

Parameters

The following parameters are available in the patching_as_code::kb defined type:

ensure

Data type: String

When set to 'enabled' or 'present', will allow this resource to be applied. Removing updates is currently not supported.

Default value: 'enabled'

kb

Data type: String

Name of the KB patch to install.

Default value: $name

maintwindow

Data type: Optional[String]

Name of the patch window to use for installing the patch.

Default value: undef

Resource types

patch_package

Define a package resource to patch

Parameters

The following parameters are available in the patch_package type.

chocolatey

Whether this is a Chocolatey package (Windows only)

name

namevar

Name of the package to patch

patch_window

Puppet schedule to link package resource to

reboot_if_pending

Perform a clean reboot if it was pending before this agent run

Parameters

The following parameters are available in the reboot_if_pending type.

name

namevar

Name of this resource (has no function)

os

OS type from kernel fact

patch_window

Puppet schedule to link the reboot resource to

Functions

patching_as_code::dedupe_arch

Type: Ruby 4.x API

The patching_as_code::dedupe_arch function.

patching_as_code::dedupe_arch(Array $patches)

The patching_as_code::dedupe_arch function.

Returns: Any

patches

Data type: Array

patching_as_code::high_prio_last_run

Type: Ruby 4.x API

The patching_as_code::high_prio_last_run function.

patching_as_code::high_prio_last_run(Array $patches, Array $choco_patches)

The patching_as_code::high_prio_last_run function.

Returns: Any

patches

Data type: Array

choco_patches

Data type: Array

patching_as_code::is_patchday

Type: Puppet Language

The patching_as_code::is_patchday function.

patching_as_code::is_patchday(Enum['Any','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'] $day_of_week, Variant[Integer, Array] $week_iteration, String $patch_group)

The patching_as_code::is_patchday function.

Returns: Any

day_of_week

Data type: Enum['Any','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday']

week_iteration

Data type: Variant[Integer, Array]

patch_group

Data type: String

patching_as_code::last_run

Type: Ruby 4.x API

The patching_as_code::last_run function.

patching_as_code::last_run(Array $patches, Array $choco_patches)

The patching_as_code::last_run function.

Returns: Any

patches

Data type: Array

choco_patches

Data type: Array

patching_as_code::process_patch_groups

Type: Puppet Language

The patching_as_code::process_patch_groups function.

patching_as_code::process_patch_groups()

The patching_as_code::process_patch_groups function.

Returns: Any

Tasks

install_kb

Immediately installs a specific KB update

Supports noop? false

Parameters

kb

Data type: Pattern[/^KB\d+$/]

The KB number of the patch you want to install (e.g. KB123456)

restart

Data type: Boolean

Perform a restart after installing the patch