puppet_run_scheduler

Configure and distribute Puppet run frequency using Cron (Posix) and Scheduled Tasks (Windows).

• Description
• Setup
  • What puppet_run_scheduler affects
• Reference
• Known Issues

Description

By default, Puppet runs once every 30 minutes on client systems, with a service and timer controlling the frequency of runs. For massive installations of Puppet the imprecise timing results in "waves" of load being seen on the Puppet servers, as tens of thousands of systems rarely distribute themselves perfectly throughout the run interval.

The puppet_run_scheduler module replaces the running service method of scheduling and replaces it with precise distribution of load using system schedulers, Cron (Posix) and Scheduled Tasks (Windows). This eliminates "waves" of load in massive installations, perfectly distributing activity through the run interval period.

Setup

What puppet_run_scheduler affects

The puppet service will be disabled when puppet_run_scheduler is implemented on all platforms.

On Windows, puppet_run_scheduler will install a Scheduled Task called "puppet-run-scheduler".

On Linux/Unix, puppet_run_scheduler will install a puppet-run-scheduler cron job under the root user.

Basic Usage

Using a default 30m run interval, you can simply include the class.

include puppet_run_scheduler

Parameters exist that can be used to fine-tune exactly how the runs are scheduled.

class { 'puppet_run_scheduler':
  run_interval => '4h',
  splaylimit   => '1h',
  start_time   => '16:00',
}

Reference

This module is documented via pdk bundle exec puppet strings generate --format markdown. Please see REFERENCE.md for more info.

Known Issues

See https://tickets.puppetlabs.com/browse/PUP-9238.

On Windows, when running from a Scheduled Task, Puppet creates cache files that are not readable by "Everyone", only SYSTEM. This has the effect of making manual puppet agent -t runs return a lot of red text in the shell. The last line of red text even suggests that Puppet was unable to submit a report. This isn't true though; Puppet DOES submit a report.

A workaround exists in the module to avoid this by explicitly ensuring minimal ACEs exist on those files.

Reference

Table of Contents

Classes

• puppet_run_scheduler: Configure and distribute Puppet run frequency using Cron (Posix) and Scheduled Tasks (Windows).
• puppet_run_scheduler::posix: Private implementation class for posix OSes
• puppet_run_scheduler::windows: Private implementation class for Windows OS

Functions

• puppet_run_scheduler::minutes

Data types

• Puppet_run_scheduler::Run_interval: A list of permissible run_interval settings

Classes

puppet_run_scheduler

puppet_run_scheduler

Examples

Using a default 30m run interval, you can simply include the class

include puppet_run_scheduler

Parameters exist that can be used to fine-tune exactly how the runs are scheduled

class { 'puppet_run_scheduler':
  run_interval => '4h',
  splaylimit   => '1h',
  start_time   => '16:00',
}

Parameters

The following parameters are available in the puppet_run_scheduler class:

• ensure
• run_interval
• start_time
• splaylimit
• posix_puppet_executable
• windows_puppet_executable

ensure

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

Whethor or not to schedule the running of puppet. "absent" only exists to provide clean-up or rollback options in case the class is applied somewhere it shouldn't have been.

Default value: 'present'

run_interval

Data type: Puppet_run_scheduler::Run_interval

What frequency Puppet should run at. This value cannot be any period; there is an enumerated list of acceptable values. Valid values: 15m, 30m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 24h

Default value: '30m'

start_time

Data type: Pattern[/[0-2]\d:\d\d/]

A specific time in the form of HH:MM that a Puppet run should start ( subject to the splaylimit parameter). This is useful for organizations with long run intervals and specific maintenance windows. For example, given a run_interval of 4h and a splaylimit of 30m, administrators can use start_time to ensure that Puppet runs occur during the first 30 minutes of a known maintenance window.

Default value: '00:00'

splaylimit

Data type: Puppet_run_scheduler::Run_interval

Same format as run_interval. How long a period of time to spread runs out over. By default runs will be fully spread out over the entire run_interval, but it is possible to have a shorter splaylimit.

Default value: $run_interval

posix_puppet_executable

Data type: Stdlib::Absolutepath

The fully qualified path to the Puppet executable to run on Posix systems. All of the Puppet command-line arguments appropriate for perfoming a one-time run will be passed to this executable.

Default value: '/opt/puppetlabs/bin/puppet'

windows_puppet_executable

Data type: Stdlib::Absolutepath

The fully qualified path to the Puppet executable to run on Windows systems. All of the Puppet command-line arguments appropriate for perfoming a one-time run will be passed to this executable.

Default value: 'C:\\Program Files\\Puppet Labs\\Puppet\\bin\\puppet.bat'

puppet_run_scheduler::posix

puppet_run_scheduler::posix

Parameters

The following parameters are available in the puppet_run_scheduler::posix class:

• puppet_executable

puppet_executable

Data type: Stdlib::Absolutepath

The fully qualified path to the Puppet executable to run on Posix systems. All of the Puppet command-line arguments appropriate for perfoming a one-time run will be passed to this executable.

Default value: $puppet_run_scheduler::posix_puppet_executable

puppet_run_scheduler::windows

puppet_run_scheduler::windows

Parameters

The following parameters are available in the puppet_run_scheduler::windows class:

• scheduled_task_user
• puppet_executable
• manage_lastrun_acls
• scheduled_task_password

scheduled_task_user

Data type: String[1]

The user to run the Puppet run scheduled task as.

Default value: 'system'

puppet_executable

Data type: Stdlib::Absolutepath

The fully qualified path to the Puppet executable to run on Windows systems. All of the Puppet command-line arguments appropriate for perfoming a one-time run will be passed to this executable.

Default value: $puppet_run_scheduler::windows_puppet_executable

manage_lastrun_acls

Data type: Boolean

Whether or not to manage acl entries on Puppet lastrun files, to work around PUP-9238.

Default value: true

scheduled_task_password

Data type: Optional[Variant[String[1], Sensitive[String[1]]]]

The password for the user to run the Puppet run scheduled task as. Only used if specifying a user other than "system" via scheduled_task_user.

Default value: undef

Functions

puppet_run_scheduler::minutes

Type: Puppet Language

The puppet_run_scheduler::minutes function.

puppet_run_scheduler::minutes(Puppet_run_scheduler::Run_interval $value)

The puppet_run_scheduler::minutes function.

Returns: Any

value

Data type: Puppet_run_scheduler::Run_interval

Data types

Puppet_run_scheduler::Run_interval

A list of permissible run_interval settings

Alias of

Enum['15m', '30m', '1h', '2h', '3h', '4h', '6h', '8h', '12h', '24h']

Changelog

All notable changes to this project will be documented in this file.

Release 1.0.2

Bug fixes

• ACL ordering corrected for lastrun files on Windows

Release 1.0.1

Improvements

• Minor documentation updates for new REFERENCE.md

Release 1.0.0

Features

• Add puppet_executable parameters to puppet_run_scheduler class, for easier inclusion and use in profiles.

Improvements

• Ensure basic unit tests run to completion

Bug fixes

• Use an absolute path for command in the scheduled_task resource on Windows. This is necessary to pass the type parameter validation checks.

Release 0.4.2

Update module dependency metadata to indicate that the newest versions of required modules puppetlabs-acl and puppetlabs-scheduled_task are compatible.

Release 0.4.1

Bug fixes

• Sets inherit_parent_permissions to false for lastrun ACLs on Windows. This should work around some observed idempotence issues with the ACL type and this property.

Release 0.4.0

Features

• Manage ACEs for last_run files to work around PUP-9238 bug