Puppet fonctions

Fiche express
Type	Référence langage Puppet
Portée	Fonctions natives du DSL Puppet
Doc officielle	Puppet Functions Reference
Voir aussi	Puppet · Puppet references · Puppet client

Puppet fonctions recense les fonctions natives du langage de déclaration Puppet (DSL), utilisables dans les manifests (fichiers .pp) pour manipuler des ressources, itérer sur des collections, journaliser ou transformer des chaînes de caractères.

Ces fonctions se répartissent en deux familles : les fonctions dites « statement » (appelées comme fonction(arguments)) et les fonctions de type « lambda » introduites par Puppet 4, qui acceptent un bloc de code entre barres verticales (|$x| { ... }) et peuvent aussi s'écrire en notation chaînée ($variable.fonction |$x| { ... }).

Gestion des ressources

create_resources

Permet de déclarer dynamiquement un ensemble de ressources à partir d'un hash, en évitant de dupliquer le code pour chaque instance.

# Hash de ressources utilisateur
$myusers = {
  'nick' => { uid    => '1330',
              gid    => allstaff,
              groups => ['developers', 'operations', 'release'], },
  'dan'  => { uid    => '1308',
              gid    => allstaff,
              groups => ['developers', 'prosvc', 'release'], },
}

create_resources(user, $myusers)

Un hash de valeurs par défaut peut être fourni en troisième argument :

$defaults = {
  'ensure'   => present,
  'provider' => 'ldap',
}
create_resources(user, $myusers, $defaults)

• Exporter des ressources : create_resources("@@user", $myusers)
• Ressources virtuelles : create_resources("@user", $myusers)

defined

Teste si une ressource, une classe ou un type est déjà défini dans le catalogue compilé — utile pour éviter les doublons de déclaration entre modules.

defined("file")
defined("customtype")
defined("foo")
defined("foo::bar")
defined('$name')

if defined(File['/tmp/foo']) {
  notify { "This configuration includes the /tmp/foo file.": }
}
file { "/tmp/foo":
  ensure => present,
}

defined(Resource['file', '/some/file'])
defined(File['/some/file'])
defined(Class['foo'])

realize

Rend effective (« réalise ») une ressource déclarée en virtual ailleurs dans le catalogue — la ressource n'est appliquée que si elle est explicitement réalisée.

realize User[luke]

require (fonction)

Évalue une classe et déclare implicitement une dépendance dessus (équivalent à include + relation d'ordre).

class myservice {
  service { foo: ensure => running }
}

class otherstuff {
  include myservice
  file { '/foo': notify => Service[foo] }
}

include

Charge une classe (avec ou sans paramètres) sans imposer d'ordre d'application vis-à-vis des autres ressources.

include <class name>::<parameter name>
include class {'name': parameter => 'value',}

tag / tagged

• tag : associe un ou plusieurs tags à la classe ou à la définition courante.
• tagged : fonction booléenne qui indique si la ressource porte un tag donné.

Itération sur les collections (Puppet 4+)

Les fonctions suivantes acceptent un bloc lambda |...| { ... } et s'utilisent soit en notation fonction, soit en notation chaînée sur la variable.

each

Applique un bloc à chaque élément d'un tableau, d'une paire clé/valeur de hash, ou d'un intervalle, sans retourner de valeur.

$a.each |$x| { ... }
each($a) |$x| { ... }

$a.each |$entry|       { notice "key ${entry[0]}, value ${entry[1]}" }
$a.each |$key, $value| { notice "key ${key}, value ${value}" }

[1,2,3].each |$val| { ... }                       # 1, 2, 3
[5,6,7].each |$index, $val| { ... }               # (0,5), (1,6), (2,7)
{a=>1, b=>2, c=>3}.each |$val| { ... }             # ['a',1], ['b',2], ['c',3]
{a=>1, b=>2, c=>3}.each |$key, $val| { ... }       # ('a',1), ('b',2), ('c',3)
Integer[10, 20].each |$index, $value| { ... }      # (0,10), (1,11) ...
"hello".each |$char| { ... }                       # 'h','e','l','l','o'
3.each |$number| { ... }                           # 0, 1, 2

map

Applique un bloc à chaque élément et retourne un tableau des résultats — utile pour transformer un hash en tableau de clés ou de valeurs.

$a.map |$x| { ... }
map($a) |$x| { ... }

# Hash vers tableau de valeurs
$a.map |$x| { $x[1] }
# Hash vers tableau de clés
$a.map |$x| { $x[0] }

# Notation à deux paramètres
$a.map |$key, $val| { $val }   # valeurs
$a.map |$key, $val| { $key }   # clés

filter

Sélectionne les éléments d'une collection qui satisfont une condition, retourne un tableau ou un hash filtré.

$a.filter |$x| { ... }
filter($a) |$x| { ... }

# Sélectionne les éléments finissant par "berry"
$a = ["raspberry", "blueberry", "orange"]
$a.filter |$x| { $x =~ /berry$/ }   # raspberry, blueberry

# Sélectionne selon l'index (pair) ET la valeur
$a = ["raspberry", "blueberry", "orange"]
$a.filter |$index, $x| { $index % 2 == 0 and $x =~ /berry$/ }   # raspberry

# Sur un hash
$a = {"raspberry"=>0, "blueberry"=>1, "orange"=>1}
$a.filter |$key, $x| { $x =~ /berry$/ and $x >= 1 }   # blueberry

reduce

Réduit une collection à une seule valeur en accumulant le résultat d'un bloc appliqué successivement à chaque élément (equivalent d'un fold/reduce classique).

$a.reduce |$memo, $x| { ... }
reduce($a) |$memo, $x| { ... }
$a.reduce(start) |$memo, $x| { ... }
reduce($a, start) |$memo, $x| { ... }

# Somme d'un tableau
$a = [1,2,3]
$a.reduce |$memo, $entry| { $memo + $entry }        # => 6

# Réduction de valeurs de hash
$a = {a => 1, b => 2, c => 3}
$a.reduce |$memo, $entry| { [sum, $memo[1]+$entry[1]] }   # => [sum, 6]

# Renverser une chaîne
"abc".reduce |$memo, $char| { "$char$memo" }        # => "cba"

# Avec valeur de départ
$a = [1,2,3]
$a.reduce(4) |$memo, $entry| { $memo + $entry }      # => 10

Integer[1,4].reduce |$memo, $x| { $memo + $x }       # => 10

slice

Découpe une collection en sous-groupes de taille fixe et applique un bloc à chaque groupe.

$a.slice($n) |$x| { ... }
slice($a) |$x| { ... }

$a.slice(2) |$first, $second| { ... }
$a.slice(2) |$entry|          { notice "first ${entry[0]}, second ${entry[1]}" }
$a.slice(2) |$first, $second| { notice "first ${first}, second ${second}" }

with

Appelle un bloc lambda avec les arguments donnés — sert surtout à isoler une portée de variables locales.

# Notifie le tableau [1, 2, 'foo']
with(1, 2, 'foo') |$x, $y, $z| { notice [$x, $y, $z] }

Journalisation (logging)

Ces fonctions envoient un message au niveau de sévérité correspondant dans les logs de l'agent ou du master.

• emerg — message d'urgence
• err — message d'erreur
• fail — interrompt la compilation avec un message d'échec
• info — message d'information
• notice — message notice
• warning — message d'avertissement

Templates (ERB / EPP)

template / inline_template

Évalue un template ERB (fichier ou chaîne inline) et retourne le texte rendu.

template('<MODULE NAME>/<TEMPLATE FILE>')
template('<MODULES DIRECTORY>/apache/templates/vhost.conf.erb')

Voir la documentation officielle sur le templating.

epp

Évalue un template EPP (Embedded Puppet, syntaxe <%= %> proche de l'ERB mais native au langage Puppet) depuis un fichier de module.

epp('<MODULE NAME>/<TEMPLATE FILE>', <PARAMETER HASH>)
epp('apache/templates/vhost/_docroot.epp', { 'docroot' => '/var/www/html', 'virtual_docroot' => '/var/www/example' })

inline_epp

Même principe que epp mais à partir d'une chaîne de caractères inline plutôt que d'un fichier.

inline_epp('<EPP TEMPLATE STRING>', <PARAMETER HASH>)
inline_epp('docroot: <%= $docroot %> Virtual docroot: <%= $virtual_docroot %>', { 'docroot' => '/var/www/html', 'virtual_docroot' => '/var/www/example' })

Lookup et Hiera

hiera / hiera_hash / hiera_array / hiera_include

Interroge la hiérarchie Hiera pour récupérer une valeur, en fusionnant éventuellement les résultats de plusieurs niveaux (hash, tableau, ou inclusion de classes). Depuis Puppet 4.x, la fonction lookup ci-dessous est l'API recommandée et remplace progressivement hiera*.

lookup

Fonction unifiée de résolution de données (remplaçante moderne de hiera), qui permet de valider le type de la valeur retournée.

lookup(name)
lookup(name, value_type)
lookup(name, value_type, merge)
lookup(name, value_type, merge, default_value)
lookup(options_hash)
lookup(name, options_hash)
lookup(...) |$name| { ... }

Types couramment utilisés (par défaut : data) :

Hash[<value_type>], Hash[<key_type>, <value_type>]
Pattern['.com$', '.net$'], Pattern[/[a-z]+[0-9]+/]
Enum[<s1>, <s2>, ..., <sn>]     # ex : Enum[blue, red, green]
Variant[<t1>, <t2>, ..., <tn>]  # ex : Variant[Integer[8000,8999], Integer[20000,99999]]

Exemples :

lookup('the_name')
lookup('the_name', String)
lookup('the_name', String, undef, 'Fred')
lookup('the_name', Array[String], 'unique', [Fred])

$are_you_there = lookup('peekaboo', { 'default_value' => undef })
$are_you_there = lookup({ 'name' => 'peekaboo', 'default_value' => undef })
$are_you_there = lookup('peekaboo', Optional[String]) |$name| { undef }

Chaînes de caractères et validation

regsubst

Effectue un remplacement par expression régulière sur une chaîne ou un tableau de chaînes.

Paramètres (dans l'ordre) :

• target — chaîne ou tableau de chaînes sur lesquelles opérer ;
• regexp — expression régulière (non ancrée automatiquement, utiliser ^/$ au besoin) ;
• replacement — chaîne de remplacement, avec rétro-références \0 (match complet), \1, etc. ;
• flags (optionnel) — E regex étendues, I insensible à la casse, M multiligne, G remplacement global ;
• encoding (optionnel) — N aucun, E EUC, S SJIS, U UTF-8.

# Extraire le 3e octet de l'adresse IP d'un nœud
$i3 = regsubst($ipaddress, '^(\d+)\.(\d+)\.(\d+)\.(\d+)$', '\3')

# Encadrer chaque octet de l'adresse IP par des chevrons
$x = regsubst($ipaddress, '([0-9]+)', '<\1>', 'G')

scanf

Analyse une chaîne selon un format et retourne un tableau des valeurs converties.

scanf("42", "%i")[0] == 42

"42".scanf("%i")
"42".scanf("%i") |$x| {
  unless $x[0] =~ Integer {
    fail "Expected a well formed integer value, got '$x[0]'"
  }
  $x[0]
}

split

Découpe une chaîne selon une expression régulière et retourne un tableau.

$string     = 'v1.v2:v3.v4'
$array_var1 = split($string, ':')
$array_var2 = split($string, '[.]')
$array_var3 = split($string, '[.:]')

match

Retourne les groupes capturés d'une expression régulière appliquée à une chaîne.

"abc123".match(/([a-z]+)[1-9]+/)          # => ["abc"]
"abc123".match(/([a-z]+)([1-9]+)/)        # => ["abc", "123"]

Autres fonctions utilitaires

• sprintf — formate une chaîne à partir d'un tableau d'arguments (façon printf).
• shellquote — quote et concatène des arguments pour un shell Bourne (chaque argument est quoté séparément puis les résultats sont joints par des espaces).
• md5 — calcule le hash MD5 d'une chaîne.
• sha1 — calcule le hash SHA1 d'une chaîne.
• versioncmp — compare deux numéros de version.
• fqdn_rand — génère un nombre pseudo-aléatoire salé avec le hostname (FQDN) du nœud, pour obtenir un résultat stable par machine mais réparti entre machines (utile pour étaler des cron jobs).

$result = versioncmp(a, b)

if versioncmp('2.6-1', '2.4.5') > 0 {
  notice('2.6-1 is > than 2.4.5')
}

Voir aussi

• Puppet — page hub de la sous-branche Puppet
• Puppet references — référence des types de ressources natifs
• Puppet client — configuration de l'agent qui exécute les manifests
• Hiera — hiérarchie de données consommée par lookup/hiera