Built-in variables

In addition to Facter's core facts and custom facts, Puppet creates several variables for a node to facilitate managing it. These variables are called trusted facts, server facts, agent facts, server variables, and compiler variables.

Trusted facts

Normal facts are self-reported by the node, and nothing guarantees their accuracy. Trusted facts are extracted from the node's certificate, which can prove that the certificate authority checked and approved them, making them useful for deciding whether a given node can receive the sensitive data in its catalog.

Trusted facts is a hash that contains trusted data from the node's certificate. You can access the data using the syntax $trusted['fact_name']. The variable name $trusted is reserved, so local scopes cannot reuse it.

Keys in the $trusted hash Possible values
authenticated An indication of whether the catalog request was authenticated, as well as how it was authenticated. The value will be one of these:

  • remote for authenticated remote requests, as with agent-server Puppet configurations.

  • local for all local requests, as with standalone Puppet apply nodes.

  • false for unauthenticated remote requests, possible if your auth.conf configuration allows unauthenticated catalog requests.
certname The node’s subject certificate name, as listed in its certificate. When first requesting its certificate, the node requests a subject certificate name matching the value of its certname setting.
  • If authenticated is remote, the value is the subject certificate name extracted from the node’s certificate.
  • If authenticated is local, the value is read directly from the certname setting.
  • If authenticated is false, the value will be an empty string.
domain The node’s domain, as derived from its validated certificate name. The value can be empty if the certificate name doesn’t contain a fully qualified domain name.
extensions A hash containing any custom extensions present in the node’s certificate. The keys of the hash are the extension OIDs. OIDs in the ppRegCertExt range appear using their short names, and other OIDs appear as plain dotted numbers. If no extensions are present, or authenticated is local or false, this is an empty hash.
hostname The node’s hostname, as derived from its validated certificate name
A typical $trusted hash looks something like this: 
{
  'authenticated' => 'remote',
  'certname'      => 'web01.example.com',
  'domain'        => 'example.com',
  'extensions'    => {
                      'pp_uuid'                         => 'ED803750-E3C7-44F5-BB08-41A04433FE2E',
                      'pp_image_name'           => 'storefront_production'
                      '1.3.6.1.4.1.34380.1.2.1' => 'ssl-termination'
                   },
  'hostname'      => 'web01'
}
Here is some example Puppet code using a certificate extension: 
if $trusted['extensions']['pp_image_name'] == 'storefront_production' {
  include private::storefront::private_keys
}
Here's an example of a hiera.yaml file using certificate extensions in a hierarchy: 
---
version: 5
hierarchy:
  - name: "Certname"
    path: "nodes/%{trusted.certname}.yaml"
  - name: "Original VM image name"
    path: "images/%{trusted.extensions.pp_image_name}.yaml"
  - name: "Machine role (custom certificate extension)"
    path: "role/%{trusted.extensions.'1.3.6.1.4.1.34380.1.2.1'}.yaml"
  - name: "Common data"
    path: "common.yaml"

Server facts

The $server_facts variable provides a hash of server-side facts that cannot be overwritten by client side facts. This is important because it enables you to get trusted server facts that could otherwise be overwritten by client-side facts.

For example, the primary Puppet server sets the global $::environment variable to contain the name of the node's environment. However, if a node provides a fact with the name environment, that fact's value overrides the server-set environment fact. The same happens with other server-set global variables, like $::servername and $::serverip. As a result, modules can't reliably use these variables for whatever their intended purpose was.

A warning is issued any time a node parameter is overwritten.

Here is an example $server_facts hash: 
{
  serverversion => "4.1.0",
  servername    => "v85ix8blah.delivery.example.com",
  serverip      => "192.0.2.10",
  environment   => "production",
}

Agent facts

Puppet agent and Puppet apply both add several extra pieces of info to their facts before requesting or compiling a catalog. Like other facts, these are available as either top-scope variables or elements in the $facts hash.

Agent facts Values
$clientcert The node’s certname setting. This is self-reported; for the verified certificate name, use$trusted['certname'].
$clientversion The current version of Puppet agent.
$puppetversion The current version of Puppet on the node.
$clientnoop The value of the node’s noop setting (true or false) at the time of the run.
$agent_specified_environment The value of the node’s environment setting. If the primary server’s node classifier specified an environment for the node, $agent_specified_environment and $environment can have different values. If no value was set for the environment setting (in puppet.conf or with --environment), the value of $agent_specified_environmentis undef. That is, it doesn't default to production like the setting does.

Server variables

Several variables are set by the compiling Puppet server. These are most useful when managing Puppet with Puppet, for example, managing the puppet.conf file with a template. Server variables are not available in the $facts hash.

Server variables Values
$environment (also available topuppet apply) The agent node’s environment. Note that nodes can accidentally or purposefully override this with a custom fact; the $server_facts['environment'] variable always contains the correct environment, and can’t be overridden.
$servername The compiling server’s fully-qualified domain name (FQDN). Note that this information is gathered from the compiling server by Facter, rather than read from the config files. Even if the compiling server’s certname is set to something other than its FQDN, this variable still contains the server’s FQDN.
$serverip The compiling server’s IP address.
$serverversion The current version of Puppet on the compiling server.
$settings::<SETTING_NAME>(also available to puppet apply) The value of any of the compiling server’s configuration settings. This is implemented as a special namespace and these variables must be referred to by their qualified names. Other than $environment and $clientnoop, the agent node’s settings are not available in manifests. If you wish to expose them to the compiling server, you must create a custom fact.
$settings::all_local Contains all variables in the $settingsnamespace as a hash of <SETTING_NAME> => <SETTING_VALUE>. This helps you reference settings that might be missing, because a direct reference to such a missing setting raises an error when --strict_variablesis enabled.

Compiler variables

Compiler variables are set in every local scope by the compiler during compilation. They are mostly used when implementing complex defined types. Compiler variables are not available in the $facts hash.

By default, compiler variables have a value of undef (undefined). If you reference an undefined compiler variable, and you have specified the strict_variables=true setting, an error message flags the undefined variable.

Compiler variables Values
$module_name The name of the module that contains the current class or defined type.
$caller_module_name The name of the module in which the specific instance of the surrounding defined type was declared. This is useful when creating versatile defined types that will be reused by several modules.