Skip to content

REFERENCE.md

Latest commit

 

History

History
895 lines (512 loc) · 24.5 KB

REFERENCE.md

File metadata and controls

895 lines (512 loc) · 24.5 KB

Reference

Table of Contents

Classes

  • os_patching: This manifest sets up a script and cron job to populate the os_patching fact.

Tasks

  • clean_cache: Clean patch caches (yum/dpkg) via a task
  • patch_server: Carry out OS patching on the server, optionally including a reboot and/or only applying security related updates
  • refresh_fact: Force a refresh of the os_patching fact cache via a task

Plans

Classes

os_patching

This manifest sets up a script and cron job to populate the os_patching fact.

Examples

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',
  reboot_override  => 'always',
  blackout_windows => {
    'End of year change freeze' => {
      'start' => '2018-12-15T00:00:00+10:00',
      'end'   => '2019-01-15T23:59:59+10:00',
    },
  },
  group            => 'patching01',
}
An example profile to setup patching, sourcing blackout windows from hiera
class profiles::soe::patching (
  $patch_window     = undef,
  $blackout_windows = undef,
  $reboot_override  = undef,
){
  # Pull any blackout windows out of hiera
  $hiera_blackout_windows = lookup('profiles::soe::patching::blackout_windows',Hash,hash,{})

  # Merge the blackout windows from the parameter and hiera
  $full_blackout_windows = $hiera_blackout_windows + $blackout_windows

  # Call the os_patching class to set everything up
  class { 'os_patching':
    patch_window     => $patch_window,
    reboot_override  => $reboot_override,
    blackout_windows => $full_blackout_windows,
    group            => 'patching01',
  }
}
JSON hash to specify a change freeze from 2018-12-15 to 2019-01-15
{"End of year change freeze": {"start": "2018-12-15T00:00:00+10:00", "end": "2019-01-15T23:59:59+10:00"}}
Run patching on the node centos.example.com using the smart reboot option
puppet task run os_patching::patch_server --params '{"reboot": "smart"}' --targets centos.example.com
Remove from a managed system
class { 'os_patching':
  ensure => absent,
}

Parameters

The following parameters are available in the os_patching class:

puppet_binary

Data type: Stdlib::Absolutepath

Location of the Puppet binary

patch_data_owner

Data type: String

User name for the owner of the patch data

patch_data_group

Data type: String

Group name for the owner of the patch data

patch_cron_user

Data type: String

User who runs the cron job

manage_yum_utils

Data type: Boolean

Should the yum_utils/dnf_utils package be managed by this module on RedHat family nodes? If true, use the parameter yum_utils to determine how it should be manged

block_patching_on_warnings

Data type: Boolean

If there are warnings present in the os_patching fact, should the patching task run? If true the run will abort and take no action If false the run will continue and attempt to patch (default)

yum_utils

Data type: Enum['installed', 'absent', 'purged', 'held', 'latest']

If managed, what should the yum_utils package set to?

fact_upload

Data type: Boolean

Should puppet fact upload be run after any changes to the fact cache files?

autoremove

Data type: Boolean

Should autoremove via the package manager be run after reboot? Only supported on Debian and RedHat family nodes.

manage_delta_rpm

Data type: Boolean

Should the deltarpm package be managed by this module on RedHat family nodes? If true, use the parameter delta_rpm to determine how it should be manged

delta_rpm

Data type: Enum['installed', 'absent', 'purged', 'held', 'latest']

If managed, what should the delta_rpm package set to?

manage_yum_plugin_security

Data type: Boolean

Should the yum_plugin_security package be managed by this module on RedHat family nodes? If true, use the parameter yum_plugin_security to determine how it should be manged

yum_plugin_security

Data type: Enum['installed', 'absent', 'purged', 'held', 'latest']

If managed, what should the yum_plugin_security package set to?

reboot_override

Data type: Optional[Variant[Boolean, Enum['always', 'never', 'patched', 'smart', 'default']]]

Controls on a node level if a reboot should/should not be done after patching. This overrides the setting in the task

patch_window

Data type: Optional[Pattern[/^[A-Za-z0-9\-_ ]+$/]]

A freeform text entry used to allocate a node to a specific patch window (Optional)

Default value: undef

blackout_windows

Data type: Optional[Hash]

Hash of start/end blackout dates+times (Optional)

Options:

  • :title String: Name of the blackout window
  • :start String: Start of the blackout window (ISO8601 format)
  • :end String: End of the blackout window (ISO8601 format)

Default value: undef

pre_patching_command

Data type: Optional[Stdlib::Absolutepath]

The full path of the command to run prior to running patching. Can be used to run customised workflows such as gracefully shutting down applications. The entry must be a single absolute filename with no arguments or parameters.

patch_cron_hour

Data type: Variant[Enum['absent'], Integer[0,23]]

The hour(s) for the cron job to run (defaults to absent, which means '*' in cron)

patch_cron_month

Data type: Variant[Enum['absent'], Integer[1,12]]

The month(s) for the cron job to run (defaults to absent, which means '*' in cron)

patch_cron_monthday

Data type: Variant[Enum['absent'], Integer[1,31]]

The monthday(s) for the cron job to run (defaults to absent, which means '*' in cron)

patch_cron_weekday

Data type: Variant[Enum['absent'], Integer[0,7]]

The weekday(s) for the cron job to run (defaults to absent, which means '*' in cron)

patch_cron_min

Data type: Integer[0,59]

The min(s) for the cron job to run (defaults to a random number between 0 and 59)

Default value: fqdn_rand(59)

windows_update_hour

Data type: Integer[0,23]

Control the hour on which windows nodes check for updates

windows_update_interval_mins

Data type: Integer

Control how often windows updates for updates

fact_mode

Data type: Stdlib::Filemode

Mode to set on fact command file

ensure

Data type: Enum['present', 'absent']

present to install scripts, cronjobs, files, etc, absent to cleanup a system that previously hosted us

group

Data type: Optional[Pattern[/^[A-Za-z0-9\-_ ]+$/]]

The group to assign the node for patching purposes.

Default value: undef

autoremove_delay_sec

Data type: Integer

The number of seconds to wait after boot before running autoremove

Tasks

clean_cache

Clean patch caches (yum/dpkg) via a task

Supports noop? false

patch_server

Carry out OS patching on the server, optionally including a reboot and/or only applying security related updates

Supports noop? false

Parameters

yum_params

Data type: Optional[String]

Any additional parameters to include in the yum upgrade command (such as including/excluding repos)

dpkg_params

Data type: Optional[String]

Any additional parameters to include in the dpkg command

zypper_params

Data type: Optional[String]

Any additional parameters to include in the zypper update command

reboot

Data type: Optional[Variant[Boolean, Enum['always', 'never', 'patched', 'smart']]]

Should the server reboot after patching has been applied? (Defaults to 'never')

timeout

Data type: Integer

How many seconds should we wait until timing out the patch run? (Defaults to 3600 seconds)

security_only

Data type: Optional[Boolean]

Limit patches to those tagged as security related? (Defaults to false)

clean_cache

Data type: Optional[Boolean]

Should the yum/dpkg caches be cleaned at the start of the task? (Defaults to false)

refresh_fact

Force a refresh of the os_patching fact cache via a task

Supports noop? false

Plans

os_patching::patch_after_healthcheck

An example plan that uses the 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

Parameters

The following parameters are available in the os_patching::patch_after_healthcheck plan:

nodes

Data type: TargetSpec

noop_state

Data type: Optional[Boolean]

Default value: false

runinterval

Data type: Optional[Integer]

Default value: 1800

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

Data type: TargetSpec

The batch of nodes to patch

catch_errors

Data type: Boolean

Whether to catch errors during task execution

Default value: true

clean_cache

Data type: Optional[Boolean]

Whether to clean the package manager cache before patching

Default value: undef

debug

Data type: Boolean

Whether to enable debug output

Default value: false

dpkg_params

Data type: Optional[String]

Additional parameters for apt/dpkg

Default value: undef

noop_state

Data type: Boolean

Whether to consider noop state during health check

Default value: false

reboot

Data type: Optional[Variant[Boolean, Enum['always', 'never', 'patched', 'smart']]]

Reboot strategy after patching

Default value: undef

run_health_check

Data type: Boolean

Whether to run a health check before patching

Default value: false

runinterval

Data type: Integer[0]

The runinterval to use during health check

Default value: 1800

security_only

Data type: Optional[Boolean]

Whether to apply only security updates

Default value: undef

service_enabled

Data type: Boolean

Whether the puppet service should be enabled during health check

Default value: true

service_running

Data type: Boolean

Whether the puppet service should be running during health check

Default value: true

timeout

Data type: Optional[Integer[1]]

The timeout for the patching task

Default value: undef

yum_params

Data type: Optional[String]

Additional parameters for yum

Default value: undef

zypper_params

Data type: Optional[String]

Additional parameters for zypper

Default value: undef

os_patching::patch_group

Patch nodes collected by a fact group

Parameters

The following parameters are available in the os_patching::patch_group plan:

batch_size

Data type: Integer[1]

The size of each batch if patching in batches

Default value: 15

catch_errors

Data type: Boolean

Whether to catch errors during task execution

Default value: true

clean_cache

Data type: Optional[Boolean]

Whether to clean the package manager cache before patching

Default value: undef

debug

Data type: Boolean

Whether to enable debug output

Default value: false

dpkg_params

Data type: Optional[String]

Additional parameters for apt/dpkg

Default value: undef

group

Data type: String[1]

The fact group name to patch

noop_state

Data type: Boolean

Whether to consider noop state during health check

Default value: false

patch_in_batches

Data type: Boolean

Whether to patch nodes in batches

Default value: true

pql_query

Data type: String[1]

The PQL query to retrieve nodes in the group

Default value: "inventory[certname] { facts.os_patching.group = '${group}'}"

reboot

Data type: Optional[Variant[Boolean, Enum['always', 'never', 'patched', 'smart']]]

Reboot strategy after patching

Default value: undef

run_health_check

Data type: Boolean

Whether to run a health check after patching

Default value: true

runinterval

Data type: Integer[0]

The runinterval to use during health check

Default value: 1800

security_only

Data type: Optional[Boolean]

Whether to apply only security updates

Default value: undef

service_enabled

Data type: Boolean

Whether the puppet service should be enabled during health check

Default value: true

service_running

Data type: Boolean

Whether the puppet service should be running during health check

Default value: true

timeout

Data type: Optional[Integer[1]]

The timeout for the patching task

Default value: undef

yum_params

Data type: Optional[String]

Additional parameters for yum

Default value: undef

zypper_params

Data type: Optional[String]

Additional parameters for zypper

Default value: undef

os_patching::patch_pql

Patch nodes collected by a PQL query

Parameters

The following parameters are available in the os_patching::patch_pql plan:

batch_size

Data type: Integer[1]

The size of each batch if patching in batches

Default value: 15

catch_errors

Data type: Boolean

Whether to catch errors during task execution

Default value: true

clean_cache

Data type: Optional[Boolean]

Whether to clean the package manager cache before patching

Default value: undef

debug

Data type: Boolean

Whether to enable debug output

Default value: false

dpkg_params

Data type: Optional[String]

Additional parameters for apt/dpkg

Default value: undef

noop_state

Data type: Boolean

Whether to consider noop state during health check

Default value: false

patch_in_batches

Data type: Boolean

Whether to patch nodes in batches

Default value: true

pql_query

Data type: String[1]

The PQL query to retrieve nodes to patch

Default value: 'inventory[certname] { facts.os.family = "redhat" }'

reboot

Data type: Optional[Variant[Boolean, Enum['always', 'never', 'patched', 'smart']]]

Reboot strategy after patching

Default value: undef

run_health_check

Data type: Boolean

Whether to run a health check after patching

Default value: true

runinterval

Data type: Integer[0]

The runinterval to use during health check

Default value: 1800

security_only

Data type: Optional[Boolean]

Whether to apply only security updates

Default value: undef

service_enabled

Data type: Boolean

Whether the puppet service should be enabled during health check

Default value: true

service_running

Data type: Boolean

Whether the puppet service should be running during health check

Default value: true

timeout

Data type: Optional[Integer[1]]

The timeout for the patching task

Default value: undef

yum_params

Data type: Optional[String]

Additional parameters for yum

Default value: undef

zypper_params

Data type: Optional[String]

Additional parameters for zypper

Default value: undef