Built-in 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-master 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 Puppet master 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 master’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_environment`is `undef`. That is, it doesn't default to `production` like the setting does.

Master variables

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

Master variables	Values
`$environment` (also available to`puppet 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 master’s fully-qualified domain name (FQDN). Note that this information is gathered from the master by Facter, rather than read from the config files. Even if the master’s certname is set to something other than its FQDN, this variable still contains the server’s FQDN.
`$serverip`	The master’s IP address.
`$serverversion`	The current version of Puppet on the master.
`$settings::<SETTING_NAME>`(also available to `puppet apply`)	The value of any of the master’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 master, you must create a custom fact.
`$settings::all_local`	Contains all variables in the `$settings`namespace 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_variables`is 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.

These variables are always considered defined, suc strict_variables setting always considers these variables to be defined, but their value is undef whenever no other value is applicable.

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.