Extlib module for Puppet

Table of Contents

1. Overview
2. Setup - The basics of getting started with extlib
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Overview

This module provides functions that are out of scope for stdlib. Some of them are even intrinsically tied to stdlib.

Setup

 % puppet module install puppet-extlib

Usage

resources_deep_merge

• Type: rvalue

Returns a deep-merged resource hash (hash of hashes).

    $tcresource_defaults = {
      ensure     => 'present',
      attributes => {
        driverClassName => 'org.postgresql.Driver',
      }
    }

    $tcresources = {
      'app1:jdbc/db1' => {
        attributes => {
          url      => 'jdbc:postgresql://localhost:5432/db1',
          userpass => 'user1:pass1',
        },
      },
      'app2:jdbc/db2' => {
        attributes => {
          url      => 'jdbc:postgresql://localhost:5432/db2',
          userpass => 'user2:pass2',
        },
      }
    }

When called as:

    $result = resources_deep_merge($tcresources, $tcresource_defaults)

will return:

    {
     'app1:jdbc/db1' => {
       ensure     => 'present',
       attributes => {
         url      => 'jdbc:postgresql://localhost:5432/db1',
         userpass => 'user1:pass1',
         driverClassName => 'org.postgresql.Driver',
       },
     },
     'app2:jdbc/db2' => {
       ensure     => 'present',
       attributes => {
         url      => 'jdbc:postgresql://localhost:5432/db2',
         userpass => 'user2:pass2',
         driverClassName => 'org.postgresql.Driver',
       },
     }
    }

echo

This function outputs the variable content and its type to the debug log. It's similiar to the "notice" function but provides a better output format useful to trace variable types and values in the manifests.

# examples:
$v1 = 'test'
$v2 = ["1", "2", "3"]
$v3 = {"a"=>"1", "b"=>"2"}
$v4 = true
# $v5 is not defined
$v6 = { "b" => ["1","2","3"] }
$v7 = 12345

echo($v1, 'My string')
echo($v2, 'My array')
echo($v3, 'My hash')
echo($v4, 'My boolean')
echo($v5, 'My undef')
echo($v6, 'My structure')
echo($v7) # no comment here

# debug log output:
# My string (String) "test"
# My array (Array) ["1", "2", "3"]
# My hash (Hash) {"a"=>"1", "b"=>"2"}
# My boolean (TrueClass) true
# My undef (String) ""
# My structure (Hash) {"b"=>["1", "2", "3"]}
# (String) "12345"

cache_data

Retrieves data from a cache file, or creates it with supplied data if the file doesn't exist. Useful for having data that's randomly generated once on the master side (e.g. a password), but then stays the same on subsequent runs. The cache_data takes three parameters:

• namespace: the folder under Puppet's vardir that the data is placed (e.g. mysql becomes /var/lib/puppet/mysql)
• data_name: the filename to store the data as (e.g. mysql_password becomes /var/lib/puppet/mysql/mysql_password)
• initial_data: the data to store and cache in the data_name file

class mymodule::params {

  $password = cache_data('mysql', 'mysql_password', 'this_is_my_password')

}

random_password

Returns a string of arbitrary length that contains randomly selected characters.

Prototype:

    random_password(n)

Where n is a non-negative numeric value that denotes length of the desired password.

Given the following statements:

  $a = 4
  $b = 8
  $c = 16

  notice random_password($a)
  notice random_password($b)
  notice random_password($c)

The result will be as follows:

  notice: Scope(Class[main]): fNDC
  notice: Scope(Class[main]): KcKDLrjR
  notice: Scope(Class[main]): FtvfvkS9j9wXLsd6

default_content

Takes an optional content and an optional template name and returns the contents of a file.

$config_file_content = default_content($file_content, $template_location)
file { '/tmp/x':
  ensure  => 'file',
  content => $config_file_content,
}

extlib::has_module

See REFERENCE.md

Limitations

This module requires puppetlabs-stdlib >=3.2.1, which is when deep_merge() was introduced.

Development

We highly welcome new contributions to this module, especially those that include documentation, and rspec tests ;) but will happily guide you through the process, so, yes, please submit that pull request!

This module uses blacksmith for releasing and rspec for tests.

To release a new version please make sure tests pass! Then,

% rake travis_release

This will tag the current state under the version number described in metadata.json, and then bump the version there so we're ready for the next iteration. Finally it will git push --tags so travis can pick it up and release it to the forge!

Reference

Table of Contents

Functions

• cache_data: Retrieves data from a cache file, or creates it with supplied data if the file doesn't exist Useful for having data that's randomly generate
• default_content: Takes an optional content and an optional template name and returns the contents of a file. Examples: $config_file_content = default_co
• dump_args: dump_args - prints the args to STDOUT in Pretty JSON format. Useful for debugging purposes only. Ideally you would use this in conjunction w
• echo: This function output the variable content and its type to the debug log. It's similiar to the "notice" function but provides a better output
• extlib::has_module: A function that lets you know whether a specific module is on your modulepath.
• extlib::sort_by_version: A function that sorts an array of version numbers
• ip_to_cron:
• random_password: Returns a string of arbitrary length that contains randomly selected characters. Prototype: random_password(n) Where n is a non-negati
• resources_deep_merge: Deeply merge a "defaults" hash into a "resources" hash like the ones expected by create_resources(). Internally calls the puppetlabs-stdlib f

Functions

cache_data

Type: Ruby 3.x API

Retrieves data from a cache file, or creates it with supplied data if the file doesn't exist

Useful for having data that's randomly generated once on the master side (e.g. a password), but then stays the same on subsequent runs.

Usage: cache_data(namespace, name, initial_data) Example: $password = cache_data('mysql', 'mysql_password', 'this_is_my_password')

cache_data()

Retrieves data from a cache file, or creates it with supplied data if the file doesn't exist

Useful for having data that's randomly generated once on the master side (e.g. a password), but then stays the same on subsequent runs.

Usage: cache_data(namespace, name, initial_data) Example: $password = cache_data('mysql', 'mysql_password', 'this_is_my_password')

Returns: Any

default_content

Type: Ruby 3.x API

Takes an optional content and an optional template name and returns the contents of a file.

Examples:

$config_file_content = default_content($file_content, $template_location)
file { '/tmp/x':
  ensure  => 'file',
  content => $config_file_content,
}

default_content()

Takes an optional content and an optional template name and returns the contents of a file.

Examples:

$config_file_content = default_content($file_content, $template_location)
file { '/tmp/x':
  ensure  => 'file',
  content => $config_file_content,
}

Returns: Any

dump_args

Type: Ruby 3.x API

dump_args - prints the args to STDOUT in Pretty JSON format.

Useful for debugging purposes only. Ideally you would use this in conjunction with a rspec-puppet unit test. Otherwise the output will be shown during a puppet run when verbose/debug options are enabled.

dump_args()

dump_args - prints the args to STDOUT in Pretty JSON format.

Useful for debugging purposes only. Ideally you would use this in conjunction with a rspec-puppet unit test. Otherwise the output will be shown during a puppet run when verbose/debug options are enabled.

Returns: Any

echo

Type: Ruby 3.x API

This function output the variable content and its type to the debug log. It's similiar to the "notice" function but provides a better output format useful to trace variable types and values in the manifests.

Example: $v1 = 'test' $v2 = ["1", "2", "3"] $v3 = {"a"=>"1", "b"=>"2"} $v4 = true

$v5 is not defined

$v6 = { "b" => { "b" => [1,2,3], "c" => true, "d" => { 'x' => 'y' }}, 'x' => 'y', 'z' => [1,2,3,4,5,6]} $v7 = 12345

echo($v1, 'My string') echo($v2, 'My array') echo($v3, 'My hash') echo($v4, 'My boolean') echo($v5, 'My undef') echo($v6, 'My structure') echo($v7) # no comment here

debug log output

My string (String) "test"

My array (Array) ["1", "2", "3"]

My hash (Hash) {"a"=>"1", "b"=>"2"}

My boolean (TrueClass) true

My undef (String) ""

My structure (Hash) {"b"=>{"b"=>["1", "2", "3"], "c"=>true, "d"=>{"x"=>"y"}}, "x"=>"y", "z"=>["1", "2", "3", "4", "5", "6"]}

(String) "12345"

echo()

This function output the variable content and its type to the debug log. It's similiar to the "notice" function but provides a better output format useful to trace variable types and values in the manifests.

Example: $v1 = 'test' $v2 = ["1", "2", "3"] $v3 = {"a"=>"1", "b"=>"2"} $v4 = true

$v5 is not defined

$v6 = { "b" => { "b" => [1,2,3], "c" => true, "d" => { 'x' => 'y' }}, 'x' => 'y', 'z' => [1,2,3,4,5,6]} $v7 = 12345

echo($v1, 'My string') echo($v2, 'My array') echo($v3, 'My hash') echo($v4, 'My boolean') echo($v5, 'My undef') echo($v6, 'My structure') echo($v7) # no comment here

debug log output

My string (String) "test"

My array (Array) ["1", "2", "3"]

My hash (Hash) {"a"=>"1", "b"=>"2"}

My boolean (TrueClass) true

My undef (String) ""

My structure (Hash) {"b"=>{"b"=>["1", "2", "3"], "c"=>true, "d"=>{"x"=>"y"}}, "x"=>"y", "z"=>["1", "2", "3", "4", "5", "6"]}

(String) "12345"

Returns: Any

extlib::has_module

Type: Ruby 4.x API

A function that lets you know whether a specific module is on your modulepath.

extlib::has_module(Pattern[/\A\w+[-\/]\w+\z/] $module_name)

The extlib::has_module function.

Returns: Boolean Returns true or false.

module_name

Data type: Pattern[/\A\w+[-\/]\w+\z/]

The full name of the module you want to know exists or not. Namespace and modulename can be separated with either '-' or '/'.

extlib::sort_by_version

Type: Ruby 4.x API

A function that sorts an array of version numbers

extlib::sort_by_version(Array[String] $versions)

The extlib::sort_by_version function.

Returns: Array Returns the sorted array.

versions

Data type: Array[String]

An array of version strings you want sorted

ip_to_cron

Type: Ruby 3.x API

The ip_to_cron function.

ip_to_cron()

The ip_to_cron function.

Returns: Any

random_password

Type: Ruby 3.x API

Returns a string of arbitrary length that contains randomly selected characters.

Prototype:

random_password(n)

Where n is a non-negative numeric value that denotes length of the desired password.

For example:

Given the following statements:

$a = 4
$b = 8
$c = 16

notice random_password($a)
notice random_password($b)
notice random_password($c)

The result will be as follows:

notice: Scope(Class[main]): fNDC
notice: Scope(Class[main]): KcKDLrjR
notice: Scope(Class[main]): FtvfvkS9j9wXLsd6

random_password()

Returns a string of arbitrary length that contains randomly selected characters.

Prototype:

random_password(n)

Where n is a non-negative numeric value that denotes length of the desired password.

For example:

Given the following statements:

$a = 4
$b = 8
$c = 16

notice random_password($a)
notice random_password($b)
notice random_password($c)

The result will be as follows:

notice: Scope(Class[main]): fNDC
notice: Scope(Class[main]): KcKDLrjR
notice: Scope(Class[main]): FtvfvkS9j9wXLsd6

Returns: Any

resources_deep_merge

Type: Ruby 3.x API

Deeply merge a "defaults" hash into a "resources" hash like the ones expected by create_resources(). Internally calls the puppetlabs-stdlib function deep_merge(). In case of duplicate keys the "resources" hash keys win over the "defaults" hash keys.

Example:

$defaults_hash = { 'one' => '1', 'two' => '2', 'three' => '3', 'four' => { 'five' => '5', 'six' => '6', 'seven' => '7', } }

$numbers_hash = { 'german' => { 'one' => 'eins' 'three' => 'drei', 'four' => { 'six' => 'sechs', } }, 'french' => { 'one' => 'un', 'two' => 'deux', 'four' => { 'five' => 'cinq', 'seven' => 'sept', } } }

$result_hash = resources_deep_merge($numbers_hash, $defaults_hash)

The $result_hash then looks like this:

$result_hash = {

'german' => {

'one' => 'eins',

'two' => '2',

'three' => 'drei',

'four' => {

'five' => '5',

'six' => 'sechs',

'seven' => '7',

}

},

'french' => {

'one' => 'un',

'two' => 'deux',

'three' => '3',

'four' => {

'five' => 'cinq',

'six' => '6',

'seven' => 'sept',

}

}

}

resources_deep_merge()

Deeply merge a "defaults" hash into a "resources" hash like the ones expected by create_resources(). Internally calls the puppetlabs-stdlib function deep_merge(). In case of duplicate keys the "resources" hash keys win over the "defaults" hash keys.

Example:

$defaults_hash = { 'one' => '1', 'two' => '2', 'three' => '3', 'four' => { 'five' => '5', 'six' => '6', 'seven' => '7', } }

$numbers_hash = { 'german' => { 'one' => 'eins' 'three' => 'drei', 'four' => { 'six' => 'sechs', } }, 'french' => { 'one' => 'un', 'two' => 'deux', 'four' => { 'five' => 'cinq', 'seven' => 'sept', } } }

$result_hash = resources_deep_merge($numbers_hash, $defaults_hash)

The $result_hash then looks like this:

$result_hash = {

'german' => {

'one' => 'eins',

'two' => '2',

'three' => 'drei',

'four' => {

'five' => '5',

'six' => 'sechs',

'seven' => '7',

}

},

'french' => {

'one' => 'un',

'two' => 'deux',

'three' => '3',

'four' => {

'five' => 'cinq',

'six' => '6',

'seven' => 'sept',

}

}

}

Returns: Any

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v2.2.0 (2018-07-24)

Full Changelog

Implemented enhancements:

• Add sort_by_version function #99 (alexjfisher)

v2.1.0 (2018-06-16)

Full Changelog

Implemented enhancements:

• Add has_module function #92 (alexjfisher)

Merged pull requests:

• Remove docker nodesets #96 (bastelfreak)
• drop EOL OSs; fix puppet version range #94 (bastelfreak)

v2.0.1 (2017-12-18)

Full Changelog

Merged pull requests:

• declare compatible with Puppet 5.x #89 (mmoll)

v2.0.0 (2017-10-11)

Full Changelog

Fixed bugs:

• Fix stdlib version requirement in metadata #83 (oranenj)

v1.1.0 (2017-01-13)

Full Changelog

Merged pull requests:

• Bump min version_requirement for Puppet + dep #75 (juniorsysadmin)
• Add missing badges #70 (dhoppe)

v1.0.0 (2016-08-19)

Full Changelog

Closed issues:

• Unit tests are spread across 2 directories #60
• ip_to_cron needs unit tests #59
• please make a fresh release #54

Merged pull requests:

• typo #65 (mmckinst)
• Add better ip_to_cron unit tests #62 (alexjfisher)
• Move function spec tests #61 (alexjfisher)

v0.11.3 (2016-04-17)

Full Changelog

Merged pull requests:

• bump again #56 (bastelfreak)

v0.11.2 (2016-04-17)

Full Changelog

v0.11.1 (2016-04-17)

Full Changelog

Closed issues:

• import ip_to_cron #48

Merged pull requests:

• Release 0.11.1 #55 (jyaworski)
• Fixes GH-48: Import ip_to_cron.rb from theforeman/puppet-puppet #52 (jyaworski)
• Pin rake to avoid rubocop/rake 11 incompatibility #51 (roidelapluie)
• rename puppet[ -]?community -> voxpupuli #47 (igalic)
• chore(sync) ensure Rakefile and Gemfile are msynced #46 (igalic)
• Added dump_args statement function for debugging puppet code #30 (logicminds)

v0.11.0 (2015-12-31)

Full Changelog

Merged pull requests:

• Release PR for version 0.11.0 #45 (rnelson0)
• fix(default_content) don't call template() on empty template_name #44 (igalic)

v0.10.7 (2015-12-29)

Full Changelog

Merged pull requests:

• feat (release) more solid way to release (thru travis) #42 (igalic)

v0.10.6 (2015-12-22)

Full Changelog

v0.10.5 (2015-12-21)

Full Changelog

Closed issues:

• document default_content function #36
• New Release #20

Merged pull requests:

• prepare for 0.10.5 release #38 (igalic)
• docs (default_content) align rdoc and readme #37 (igalic)
• prep 0.10.4 release #35 (igalic)
• feat (release) travis_release now creates -rc version #34 (igalic)
• Puppet 4-safe function calls #31 (igalic)
• fixing 2 typos that bugged me in the readme #29 (ApisMellow)
• Add default_content function #4 (alvagante)

v0.10.3 (2015-10-05)

Full Changelog

v0.10.2 (2015-10-05)

Full Changelog

0.10.1 (2015-10-05)

Full Changelog

v0.10.1 (2015-10-05)

Full Changelog

v0.10.0 (2015-10-05)

Full Changelog

Closed issues:

• deployment, how does it work!? #10

Merged pull requests:

• prepare release of 0.10.0 #27 (igalic)
• fix Rubocop complaints + rspec deprecations #26 (igalic)
• rubcop:auto_correct #24 (igalic)
• Add random_password function to generate alphanumeric passwords #19 (ehelms)
• Add "echo" function for debugging #18 (dmitryilyin)
• Adds cache_data function for caching values on the master #17 (ehelms)
• "Update Readme for puppet- namechange" #16 (nibalizer)
• "Enable metadata.json linting" #15 (nibalizer)
• Check functions against stdlib #13 (nibalizer)
• document (and simplify) release process #12 (igalic)
• further distill matrix, following @camptocamp's example #11 (igalic)

v0.9.3 (2015-03-17)

Full Changelog

Merged pull requests:

• rename module in README, also. #9 (igalic)
• no email plz #8 (nibalizer)
• our forge name is puppet, not puppetcommunity! #7 (igalic)
• test more puppet versions #6 (igalic)

v0.9.2 (2015-03-16)

Full Changelog

Merged pull requests:

• Set up autodeployment #5 (nibalizer)
• Fix name for puppetlabs/stdlib in metadata.json #3 (antaflos)

v0.9.1 (2014-09-03)

Full Changelog

Closed issues:

• spec tests to 3.0 #2

Merged pull requests:

• Improve function documentation by simplifying it #1 (antaflos)

v0.9.0 (2014-09-02)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator