Functions are plugins written in Ruby, which you can call during compilation. A call to any function is an expression that resolves to a value.
Most functions take one or more values as arguments, then return some other, resulting value. The Ruby code in the function can do any number of things to produce the final value, including evaluating templates, doing math, and looking up values from an external source.
Functions may also:
Puppet includes several built-in functions, and more are available in modules on the Puppet Forge, particularly the puppetlabs-stdlib module. You can also write custom functions and put them in your own modules.
Like any expression, a function call can be used anywhere the value it returns would be allowed.
Function calls can also stand on their own, which will cause their value to be ignored. (Any side effects will still occur.)
There are two ways to call functions in the Puppet language: classic prefix calls like str2bool("true")
, and chained calls like "true".str2bool
. There’s also a modified form of prefix call that can only be used with certain functions.
These two call styles have the exact same capabilities, so you can choose whichever one is more readable. In general:
For other cases, tastes vary, so do whatever you prefer.
Most functions have short, one-word names. However, the modern function API also allows qualified function names like mymodule::foo
.
Functions must always be called with their full names; you can’t shorten a qualified function name.
You can call a function by writing its name and providing a list of arguments in parentheses.
file {"/etc/ntp.conf":
ensure => file,
content => template("ntp/ntp.conf"), # function call; resolves to a string
}
# Note: str2bool is part of the puppetlabs-stdlib module.
if str2bool("$is_virtual") { # function call; resolves to a boolean
include ntp::disabled # function call; modifies catalog
}
else {
include ntp # function call; modifies catalog
}
$binaries = [
"cfacter",
"facter",
"hiera",
"mco",
"puppet",
"puppetserver",
]
# function call with lambda; runs block of code several times
each($binaries) |$binary| {
file {"/usr/bin/$binary":
ensure => link,
target => "/opt/puppetlabs/bin/$binary",
}
}
In the examples above, template
, str2bool
, include
, and each
are all functions. template
and str2bool
are used for their return values, include
adds a class to the catalog, and each
runs a block of code several times with different values.
The general form of a prefix function call is:
name(argument, argument, ...) |$parameter, $parameter, ...| { code block }
(
).
include apache
). They’re mandatory in all other cases.)
), if an opening parenthesis was used.You can also call a function by writing its first argument, a period, and the name of the function.
file {"/etc/ntp.conf":
ensure => file,
content => "ntp/ntp.conf".template, # function call; resolves to a string
}
# Note: str2bool is part of the puppetlabs-stdlib module.
if str2bool("$is_virtual") { # function call; resolves to a boolean
"ntp::disabled".include # function call; modifies catalog
}
else {
ntp.include # function call; modifies catalog
}
$binaries = [
"cfacter",
"facter",
"hiera",
"mco",
"puppet",
"puppetserver",
]
# function call with lambda; runs block of code several times
$binaries.each |$binary| {
file {"/usr/bin/$binary":
ensure => link,
target => "/opt/puppetlabs/bin/$binary",
}
}
In the examples above, template
, str2bool
, include
, and each
are all functions. template
and str2bool
are used for their return values, include
adds a class to the catalog, and each
runs a block of code several times with different values.
The general form of a chained function call is:
argument.name(argument, ...) |$parameter, $parameter, ...| { code block }
.
).An entire function call (including the name, arguments, and lambda) constitutes an expression. It will resolve to a single value, and can be used anywhere a value of that type is accepted.
A function call may also result in some side effect, in addition to returning a value.
All functions run during compilation, which means they can only access code and data available on the Puppet master. To make changes to an agent node, you must use a resource; to collect data from an agent node, you must use a custom fact.
Each function defines how many arguments it takes, what data types it expects those arguments to be, what values it returns, and any side effects it has. Thus, each function has its own docs.
For info about any built-in function, see the Function Reference.
For info about a function included in a module, see that module’s documentation.
“Statement functions” are a group of built-in functions that are used only for their side effects. This version of the language only recognizes Puppet’s built-in statements; it doesn’t allow adding new statement functions as plugins.
The only real difference between statement functions and other functions is that you can omit parentheses when calling a statement function with at least one argument (e.g. include apache
).
Statement functions return a value like any other function, but will always return a value of undef
.
The built-in statement functions are:
include
— includes given classes in catalogrequire
— includes given classes in the catalog and adds them as a dependency of the current class or defined resourcecontain
— includes given classes in the catalog and contains them in the current classrealize
— makes a virtual resource realtag
— adds the specified tag(s) to the containing class or defined resourcedebug
— logs message at debug levelinfo
— logs message at info levelnotice
— logs message at notice levelwarning
— logs message at warning levelAlthough there are a few additional logging functions, they cannot be called as statements.
fail
— logs error message and aborts compilation