Variables

Variables store values so that those values can be accessed in code later.

After you've assigned a variable a value, you cannot reassign it. Variables depend on order of evaluation: you must assign a variable a value before it can be resolved.

The following video gives you an overview of variables:

Note: Puppet contains built-in variables that you can use in your manifests. For a list of these, see the page on facts and built-in variables.

Assigning variables

Prefix variable names with a dollar sign ($). Assign values to variables with the equal sign (=) assignment operator.

Variables accept values of any data type. You can assign literal values, or you can assign any statement that resolves to a normal value, including expressions, functions, and other variables. The variable then contains the value that the statement resolves to, rather than a reference to the statement.
$content = "some content\n"

Assign variables using their short name within their own scope. You cannot assign values in one scope from another scope. For example, you can assign a value to the apache::params class's $vhostdir variable only from within the apache::params class.

You can assign multiple variables at the same time from an array or hash.

To assign multiple variables from an array, you must specify an equal number of variables and values. If the number of variables and values do not match, the operation fails. You can also use nested arrays. For example, all of the variable assignments shown below are valid.
[$a, $b, $c] = [1,2,3]      # $a = 1, $b = 2, $c = 3
[$a, [$b, $c]] = [1,[2,3]]  # $a = 1, $b = 2, $c = 3
[$a, $b] = [1, [2]]            # $a = 1, $b = [2]
[$a, [$b]] = [1, [2]]          # $a = 1, $b = 2
When you assign multiple variables with a hash, list the variables in an array on the left side of the assignment operator, and list the hash on the right. Hash keys must match their corresponding variable name. This example assigns a value of 10 to the $a variable and a value of 20 to the $b variable.
[$a, $b] = {a => 10, b => 20}  # $a = 10, $b = 20
You can include extra key-value pairs in the hash, but all variables to the left of the operator must have a corresponding key in the hash:
[$a, $c] = {a => 5, b => 10, c => 15, d => 22}  # $a = 5, $c = 15
Puppet allows a given variable to be assigned a value only one time within a given scope. This is a little different from most programming languages. You cannot change the value of a variable, but you can assign a different value to the same variable name in a new scope:
# scope-example.pp
# Run with puppet apply --certname www1.example.com scope-example.pp
$myvar = "Top scope value"
node 'www1.example.com' {
  $myvar = "Node scope value"
  notice( "from www1: $myvar" )
  include myclass
}
node 'db1.example.com' {
  notice( "from db1: $myvar" )
  include myclass
}
class myclass {
  $myvar = "Local scope value"
  notice( "from myclass: $myvar" )
}

Resolution

You can use the name of a variable in any place where a value of the variable's data type would be accepted, including expressions, functions, and resource attributes. Puppet replaces the name of the variable with its value. By default, unassigned variables have a value of undef. See the section about unassigned variables and strict mode for more details.

In these examples, the content parameter value resolves to whatever value has been assigned to the $content variable. The $address_array variable resolves to an array of the values assigned to the $address1, $address2, and $address3 variables:
file {'/tmp/testing':
  ensure  => file,
  content => $content,
}

$address_array = [$address1, $address2, $address3]

Interpolation

Puppet can resolve variables that are included in double-quoted strings; this is called interpolation. Inside a double-quoted string, surround the name of the variable (the portion after the $) with curly braces, such as ${var_name}. This syntax is optional, but it helps to avoid ambiguity and allows variables to be placed directly next to non-whitespace characters. These optional curly braces are permitted only inside strings.

For example, the curly braces make it easier to quickly identify the variable $homedir.
$rule = "Allow * from $ipaddress"
file { "${homedir}/.vim":
  ensure => directory,
  ...
}
            

Scope

The area of code where a given variable is visible is dictated by its scope. Variables in a given scope are available only within that scope and its child scopes, and any local scope can locally override the variables it receives from its parents. See the section on scope for complete details.

You can access out-of-scope variables from named scopes by using their qualified names, which include namespaces representing the variable's scope. The scope is where the variable is defined and assigned a value. For example, the qualified name of this $vhost variable shows that the variable is found and assigned a value in the apache::params class:
$vhostdir = $apache::params::vhostdir

Variables can be assigned outside of any class, type, or node definition. These top scope variables have an empty string as their first namespace segment, so that the qualified name of a top scope variable begins with a double colon, such as $::osfamily.

Unassigned variables and strict mode

By default, you can access variables that have never had values assigned to them. If you do, their value is undef. This can be a problem, because an unassigned variable is often an accident or a typo. To make unassigned variable usage return an error, so that you can find and fix the problem, enable strict mode by setting strict_variables = true strict_variables in the puppet.conf file on your primary server and on any nodes that run puppet apply. For details about this setting, see the configuration page.

Naming variables

Some variable names are reserved; for detailed information, see the reserved name page.

Variable names

Variable names are case-sensitive and must begin with a dollar sign ($). Most variable names must start with a lowercase letter or an underscore. The exception is regex capture variables, which are named with only numbers.

Variable names can include:
  • Uppercase and lowercase letters

  • Numbers

  • Underscores ( _ ). If the first character is an underscore, access that variable only from its own local scope.

Qualified variable names are prefixed with the name of their scope and the double colon (::) namespace separator. For example, the $vhostdir variable from the apache::params class would be $apache::params::vhostdir.

Optionally, the name of the very first namespace can be empty, representing the top namespace. The main reason to namespace this way is to indicate to anyone reading your code that you're accessing a top-scope variable, such as $::is_virtual.

You can also use a regular expression for variable names. Short variable names match the following regular expression:
\A\$[a-z0-9_][a-zA-Z0-9_]*\Z
Qualified variable names match the following regular expression:
\A\$([a-z][a-z0-9_]*)?(::[a-z][a-z0-9_]*)*::[a-z0-9_][a-zA-Z0-9_]*\Z