Puppet/Wmflib

From Wikitech

wmflib is a Puppet module in the operations/puppet repository which contains generic custom functions, à la PuppetLab's stdlib. You can use these functions anywhere without having to explicitly include the module.

apply_format (removed)

This function has been removed, as we can now use the more standard syntax map, like this: 

$languages = [ 'finnish', 'french', 'greek', 'hebrew' ]
$packages = $languages.map |String $language| { "texlive-lang-${language}" }

ensure_directory

ensure_directory( string|bool $ensure )

Takes a generic ‘ensure’ parameter value and convert it to an appropriate value for use with a directory declaration.

If $ensure is ‘true’ or ‘present’, the return value is ‘directory’. Otherwise, the return value is the unmodified $ensure parameter.

Examples 

# Sample class which creates or removes '/srv/redis'
# based on the class's generic $ensure parameter:
class redis( $ensure = present ) {
    package { 'redis-server':
        ensure => $ensure,
    }

    file { '/srv/redis':
      ensure => ensure_directory($ensure),
    }
}

ensure_directory

ensure_directory( string|bool $ensure )

Takes a generic ‘ensure’ parameter value and convert it to an appropriate value for use with a symlink file declaration.

If $ensure is ‘true’ or ‘present’, the return value is ‘link’. Otherwise, the return value is the unmodified $ensure parameter.

Examples 

# Sample class which creates or remove a symlink
# based on the class's generic $ensure parameter:
class rsyslog( $ensure = present ) {
    package { 'rsyslog':
        ensure => $ensure,
    }

    file { '/etc/rsyslog.d/50-default.conf':
        ensure => ensure_link($ensure),
        target => '/usr/share/rsyslog/50-default.conf',
    }
}

ordered_json

ordered_json( hash $data [, hash $... ] )

Serialize a hash into JSON with lexicographically sorted keys.

Because the order of keys in Ruby 1.8 hashes is undefined, ‘to_pson’ is not idempotent: i.e., the serialized form of the same hash object can vary from one invocation to the next. This causes problems whenever a JSON-serialized hash is included in a file template, because the variations in key order are picked up as file updates by Puppet, causing Puppet to replace the file and refresh dependent resources on every run.

Examples 

# Render a Puppet hash as a configuration file:
$options = { 'useGraphite' => true, 'minVal' => '0.1' }
file { '/etc/kibana/config.json':
    content => ordered_json($options),
}

ordered_yaml

ordered_yaml( mixed $data )

Emit a hash as YAML with keys (both shallow and deep) in sorted order.

Examples 

# Render a Puppet hash as a configuration file:
$options = { 'useGraphite' => true, 'minVal' => '0.1' }
file { '/etc/kibana/config.yaml':
    content => ordered_yaml($options),
}

require_package

DEPRECATED. No longer needed. Use stdlib ensure_packages() instead.

See https://phabricator.wikimedia.org/T266479 and https://wikitech.wikimedia.org/wiki/Puppet_coding#Different_ways_to_install_apt_packages_with_puppet

require_package( string $package_name [, string $... ] )

Declare one or more packages a dependency for the current scope. This is equivalent to declaring and requiring the package resources. In other words, it ensures the package(s) are installed before evaluating any of the resources in the current scope.

Examples 

# Single package
require_package('python-redis')

# Multiple packages as arguments
require_package('redis-server', 'python-redis')

# Multiple packages as array
$deps = [ 'redis-server', 'python-redis' ]
require_package($deps)

requires_realm

requires_realm( string $realm, [ string $message ] )

Validate that the host realm is equal to some value. Abort catalog compilation if it is not.

Examples 

# Fail unless running in Labs:
requires_realm('labs')

requires_ubuntu

requires_ubuntu( string $version_predicate )

Validate that the host Ubuntu version satisfies a version check. Abort catalog compilation if not.

See the documentation for ubuntu_version() for supported predicate syntax.

Examples 

# Fail unless version is Trusty
requires_ubuntu('trusty')

# Fail unless Trusty or newer
requires_ubuntu('> trusty')

shell_exports

shell_exports( hash $variables [, bool $uppercase_keys = true ] )

Generate shell environment variable declarations out of a Puppet hash.

The hash keys are used as the variable names, and the values as the variable’s values. Values are automatically quoted with double quotes. If the second parameter is true (the default), keys are automatically uppercased.

Examples

Invocation: 

shell_exports({
    apache_run_user => 'apache',
    apache_pid_file => '/var/run/apache2/apache2.pid',
})

Output: 

export APACHE_RUN_USER="apache"
export APACHE_PID_FILE="/var/run/apache2/apache2.pid"

ssl_ciphersuite

ssl_ciphersuite( string $servercode, string $encryption_type, int $hsts_days )

Outputs the ssl configuration directives for use with either Nginx or Apache using our selection of ciphers and SSL options.

Takes three arguments:

  • The servercode, or which browser-version combination to support. At the moment only ‘apache-2.2’, ‘apache-2.4’ and ‘nginx’ are supported.
  • The compatibility mode,indicating the degree of compatibility we want to retain with older browsers (basically, IE6, IE7 and Android prior to 3.0)
  • An optional argument, that if non-nil will set HSTS to max-age of N days

Whenever called, this function will output a list of strings that can be safely used in your configuration file as the ssl configuration part.

Examples 

ssl_ciphersuite('apache-2.4', 'compat')
ssl_ciphersuite('nginx', 'strong')


ubuntu_version

ubuntu_version( string $version_predicate )

Performs semantic Ubuntu version comparison.

Takes a single string argument containing a comparison operator followed by an optional space, followed by a comparison target, provided as Ubuntu version number or release name.

The host’s Ubuntu version will be compared to to the comparison target using the specified operator, returning a boolean. If no operator is present, the equality operator is assumed.

Release names are case-insensitive. The comparison operator and comparison target can be provided as two separate arguments, if you prefer.

Examples 

# True if Precise or newer
ubuntu_version('>= precise')
ubuntu_version('>= 12.04.4')

# True if older than Utopic
ubuntu_version('< utopic')

# True if newer than Precise
ubuntu_version('> precise')

# True if Trusty or older
ubuntu_version('<= trusty')

# True if exactly Trusty
ubuntu_version('trusty')
ubuntu_version('== trusty')

# True if anything but Trusty
ubuntu_version('!trusty')
ubuntu_version('!= trusty')

validate_ensure

validate_ensure( string $ensure )

Throw an error if the $ensure argument is not ‘present’ or ‘absent’.

Examples 

# Abort compilation if $ensure is invalid
validate_ensure($ensure)
Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Puppet/Wmflib&oldid=2040846"