change_window

pdk
Allows puppet code to be applied during specified change window(s)

Puppet

puppetlabs

339 downloads

339 latest version

5.0 quality score

Version information

  • 0.2.0 (latest)
released Apr 1st 2021
This version is compatible with:
  • Puppet Enterprise 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
  • Puppet >= 5.5.10 < 8.0.0
  • RedHat
    ,
    CentOS
    ,
    OracleLinux
    ,
    Scientific
    ,
    Debian
    ,
    SLES
    ,
    Ubuntu
    ,
    Windows

Start using this module

Documentation

puppetlabs/change_window — version 0.2.0 Apr 1st 2021

change_window

Table of Contents

  1. Background
  2. Overview
  3. Module Description
  4. Usage
  5. Contributions - Guide for contributing to the module

Background

This module is a fork of ipcrm-change_window which is no longer actively maintained. This fork has been moved under the puppetlabs namespace to allow for community contributions.

It is not supported or maintained by puppet.

Original Author:

  • Matt Cadorette

Week in Month feature:

  • Steve Jefferies (WTW)

Overview

Allows puppet code to be applied during specified change window(s).

The change_window functionality allows you to check current time against change windows and a defined type that applies noop() to classes when not within the change window.

Module Description

Why?

The original reason for this module was to use it in conjunction with the trlinkin/noop module. However, you can actually use the functions with any resource that you need to be sensitive to change windows by simply wrapping that resource declaration with some conditional logic.

The module is made up of two functions and a defined class. The functions, change_window() and merge_change_windows(), allow the comparison of a change window schedule against the current time to determine if the run is within the change window ('true'), or outside the change window ('false'). The change_window function checks against a single window definition, while the merge_change_window function will check a list windows and return 'true' if any one of them is true.

The defined type change_window::apply will accept an array of change windows and a list of classes. The class list is then included into the catalog with the noop() mode set appropriately. This define is intended for use during role definition and allows change window control over some or all of the profiles within the role. Keeping the role definition tidy and allowing some classes to function without change control. A handy feature when you have changes that you wish applied all the time.

IMPORTANT: Remember that if you are within the change window then the value returned by the functions is a String containing 'true', otherwise it returns 'false'.

Defined types

change_window::apply

Usage

change_window::apply { 'my_controlled_changes':
  change_window_set => hiera('weekly_window'),
  class_list        => [ 'profile::ntp', 'profile::resolver' ],
}

where:

change_window_set = An array of arrays defining your change windows to check. Most easily defined and retrieved via hiera (but does not have to be, see merge_change_windows for details)

class_list = an array of classes to include

The class_list will accept either simple class names to include or a hash describing the class/resource along with its parameters.

example class_list: with simple and parameterized classes

$class_list = [
  'profile::parameter_class' => {
    parm1 => 'value1',
    parm2 => 'value2',
  },
  'profile::simple_class',
]

Functions

change_window

Usage

change_window( $tz, $window_type, $window_wday, $window_time, [$window_week], [$window_month], [$time])

Where:

  • $tz is the timezone offset you want used when the current timestamp is generated.(this example is for EST)

  • $window_type accepts to values: per_day or window.

    • per_day tells change_window that the hours specified are valid on each day specified. For example if you set days 0-3 and start 20:00, end 23:00 - then Sunday through Wednesday from 8PM to 11PM this function will return true. For wrapped hours you receive start to midnight on the first day and midnight to end on the last day.
    • window tells change_window to treat the days and times as a continuous change window spanning from start day/start time through end day/end time.
  • $window_wday is a hash where start is the first weekday in your window and end is the last weekday - expressed as weekday names or 0-6. You can specify the same day if you like and you may wrap the weekend (i.e friday .. monday).

  • $window_time is a hash where the start key is a timestamp (HH:MM), and end sets the end hour and minute. You may wrap the midnight hour (i.e. 22:00 .. 02:00). For per_day windows that wrap the midnight hour, the first day will apply the start-to-midnight and the last day will apply the midnight-to-end of the window.

  • $window_week OPTIONAL array of weeks within a month to accept as within the change window. Values in the array must be of range 1-6. See Week in month for details.

  • $window_month OPTIONAL array of months within a year to accept as within the change window. Values in the array must be of range 1-12. See Month in year for details.

  • $time is an optional parameter that lets you specify the time to test as an array. This array is passed to the Time.new() object to set the time under test. This array should take the form of [ YYYY, MM, DD, HH, MM] and will apply the timezone specified.

$tz = "-05:00"
$window_wday  = { start => 'Friday', end => 'Saturday' }
$window_time = { start  => '20:00', end => '23:00' }
$window_type = 'window'
$val = change_window($tz, $window_type, $window_wday, $window_time)

if $val == 'false' {
    notify { "Puppet noop enabled in site.pp! Not within change window!": }
    noop()
}

Another example shows wrapping the weekend. You can specify combinations like below (days 5 - 0). This will result in days 5,6,0 as being valid for the change window. In this case I'm using per_day so on Friday, Saturday, or Sunday between 8PM and 11PM changes will be allowed.

$tz = "-05:00"
$window_wday  = { start => 'Friday', end => 'Sunday' }
$window_time = { start  => '20:00', end => '23:00' }
$window_type = 'per_day'
$val = change_window($tz, $window_type, $window_wday, $window_time)

if $val == 'false' {
    notify { "Puppet noop enabled in site.pp! Not within change window!": }
    noop()
}

Example of using week and month windows, run on first and second week of the month and only between January and March.

$tz = "-05:00"
$window_wday  = { start => 'Friday', end => 'Saturday' }
$window_time = { start  => '20:00', end => '23:00' }
$window_type = 'window'
$window_week = [1,2]
$window_month = [1,2,3]
$val = change_window($tz, $window_type, $window_wday, $window_time, $window_week, $window_month)

if $val == 'false' {
    notify { "Puppet noop enabled in site.pp! Not within change window!": }
    noop()
}

You can also use hiera to enable more complex windows:

hiera:

tz_dev: "-05:00"
window_type_dev: per_day
window_wday_dev:
  start: Friday
  end: Sunday
window_time_dev:
  start: "20:00"
  end: "23:00"

site.pp:

$e = $::custom_env
$val = change_window(
         hiera("tz_${e}"),
         hiera("window_type_${e}"),
         hiera("window_wday_${e}"),
         hiera("window_time_${e}")
         )
if $val == 'false' {
  notify { "Puppet noop enabled in site.pp for env ${e}! Not within change window!": }
  noop()
}

merge_change_windows

Usage

merge_change_windows( $list_of_windows )

Where:

$list_of_windows is an Array made up of Arrays containing change_window parameters.

Manifest Example

$tz = "-05:00"

# Friday @ 10 PM until Monday @ 2 AM
$window1_type = 'window'
$window1_wday = { start => 'Friday', end => 'Monday' }
$window1_time = { start => '22:00',  end => '02:00' }

# Wednesday @ 10 PM until Thursday @ 2 AM
$window2_type = 'window'
$window2_wday = { start => 'Wednesday', end => 'Thursday' }
$window2_time = { start => '22:00',     end => '02:00' }

$change_windows = [
  [$tz, $window1_type, $window1_wday, $window1_time],
  [$tz, $window2_type, $window2_wday, $window2_time],
]

if merge_change_windows($change_windows) == 'false' {
  notify { "Puppet noop enabled in site.pp! Not within change window!": }
  noop()
}

Hiera Example

hiera:

change_window_set::my_change_window:
  - # Friday @ 10 PM until Monday @ 2 AM
    - '-05:00'
    - 'window'
    - start: 'Friday'
      end:   'Monday'
    - start: '22:00'
      end:   '02:00'
  - # Wednesday @ 10 PM until Thursday @ 2 AM
    - '-05:00'
    - 'window'
    - start: 'Wednesday'
      end:   'Thursday'
    - start: '22:00'
      end:   '02:00'

site.pp:

$change_window_set = 'my_change_window'
$change_windows    = hiera("change_window_set::${my_change_window}")

if merge_change_windows($change_windows) == 'false' {
  notify { "Puppet noop enabled in site.pp! Not within change window!": }
  noop()
}

Week in Month Change Windows

Using the $window_week parameter in change_window you can specify a sub-set of weeks within each month to be accepted as valid change windows.

This parameter is optional, if not used all weeks are included

The parameter takes an Array of integers, between 1-6 as valid week definitions.

Example

Given the month is April 2021: window week example

Then:

  • Week 1 runs from first of the month to the first Sunday
  • Week 2 runs from the following Monday to the next Sunday
  • etc...
  • Last week of the month runs from final Monday to last day of the month

Month in Year Change Windows

Using the $window_month parameter in change_window you can specify a sub-set of months within each year to be accepted as valid change windows.

This parameter is optional, if not used all months are included.

The parameter takes an array of integers and/or string ranges of values.

Months are represented by numerical values:

Month Value
January 1
February 2
March 3
April 4
May 5
June 6
July 7
August 8
September 9
October 10
November 11
December 12

For example:

  • Run only every other month: [1,3,5,7,9,11]
  • Run only between January and March (inclusive): [1,2,3] or ['1-3']

Individual values and ranges must only be between 1 and 12.

Acknowledgements

  • window_week functionality is provided through an extension which is a modified version of week-of-month

Contributions

If anyone would like to contribute to the module, PR's are welcome.

If you're experiencing any bugs you can raise an issue below however, given that this is a community module, it will only be resolved if someone submits a PR with a fix. Puppet accepts no responsibility for this module as described in Background.

Repo: https://github.com/puppetlabs/change_window

Issues link: https://github.com/puppetlabs/change_window/issues