Acceptable characters in names

Puppet limits the characters you can use when naming language constructs.

In some cases, names containing unsupported characters might still work. Such cases are bugs and could cease to work at any time. Removal of these bug cases is not limited to major releases.

Classes and defined resource type names

The names of classes and defined resource types can consist of one or more namespace segments. Each namespace segment:

  • Must begin with a lowercase letter.
  • Can include lowercase letters.
  • Can include digits.
  • Can include underscores.
The filename of a class (the loadable path) must be all lowercase ⁠— even if class name is mixed or camel case.

When you follow these rules, each namespace segment matches the following regular expression: 

\A[a-z][a-z0-9_]*\Z
The one exception is the top namespace, whose name is the empty string.

Multiple namespace segments are joined together in a class or defined type name with the double colon namespace separator: ::. Class names with multiple namespaces must match the following regular expression: 

\A([a-z][a-z0-9_]*)?(::[a-z][a-z0-9_]*)*\Z
Some words and class names are reserved and cannot be used as class or defined type names. Additionally, the filename init.pp is reserved for the class named after any given module, so you cannot use the name <MODULE NAME>::init for a class or defined type.

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

Module names

Module names obey the same rules as individual namespace segments, just as in a class or defined type name. That is, each namespace segment:

  • Must begin with a lowercase letter.
  • Can include lowercase letters.
  • Can include digits.
  • Can include underscores.

When you follow these rules, each namespace segment matches the following regular expression: 

\A[a-z][a-z0-9_]*\Z

Reserved words and class names cannot be used as module names.

Parameter names

Parameter names begin with a dollar sign prefix ($). The parameter name after the prefix:

  • Must begin with a lowercase letter.
  • Can include lowercase letters.
  • Can include digits.
  • Can include underscores.

When you follow these rules, a parameter name matches the following regular expression: 

\A\$[a-z][a-z0-9_]*\Z

Tag names

Tag names must begin with:

  • A lowercase letter, or

  • An number, or

  • An underscore.

Tag names can include:

  • Lowercase letters

  • Uppercase letters

  • Digits

  • Underscores

  • Colons

  • Periods

  • Hyphens

When you follow these rules, a tag name matches the following regular expression:

\A[[:alnum:]_][[:alnum:]_:.-]*\Z

Resource names

Resource titles can contain any characters whatsoever and are case-sensitive. Resource names, or the namevar attribute, might be limited by the system being managed. For example, most operating systems have limits on the characters permitted in the name of a user account. You are generally responsible for knowing the name limits on the platforms you manage.

Node names

Node names can contain:

  • Letters
  • Digits
  • Periods
  • Underscores
  • Dashes
That is, node names match the regular expression:
 /\A[a-z0-9._-]+\Z/

Environment names

Environment names can contain:

  • Lowercase letters
  • Numbers
  • Underscores
That is, environment names match the regular expression: 
\A[a-z0-9_]+\Z