Open source Puppet documentation

Before requesting a catalog for a managed node, or compiling one with puppet apply, Puppet collects system information, called facts, by using the Facter tool. The facts are assigned as values to variables that you can use anywhere in your manifests. Puppet also sets some additional special variables, called built-in variables, which behave a lot like facts.

Puppet code can access the following facts when compiling a catalog: To see the fact values for a node, run facter -p on the command line, or browse facts on node detail pages in the Puppet Enterprise console. You can also use the PuppetDB API to explore or build tools to search and report on your infrastructure's facts.

Puppet honors fact values of of any data type. It does not convert Boolean, numeric, or structured facts to strings.

Accessing facts from Puppet code

When you write Puppet code, you can access facts in two ways: with the $fact_name syntax, or with the $facts['fact_name'] hash.

Using the $fact_name syntax

Facts appear in Puppet as top-scope variables. They can be accessed in manifests as $fact_name.

For example:
if $osfamily == 'RedHat' { 
  # ...
Tip: When you code with this fact syntax, it's not immediately obvious that you're using a fact — someone reading your code needs to know which facts exist to guess that you're accessing a top-scope variable. To make your code easier for others to read, use the $::fact_name syntax as a hint, to show that it's accessing a top-scope variable.

Using the $facts['fact_name'] hash syntax

Alternatively, facts are structured in a $facts hash, and your manifest code can access them as $facts['fact_name']. The variable name $facts is reserved, so local scopes cannot re-use it. Structured facts show up as a nested structure inside the $facts namespace, and can be accessed using Puppet's normal hash access syntax.

For example:
if $facts['os']['family'] == 'RedHat' {
  # ...

Accessing facts using this syntax makes for more readable and maintainable code, by making facts visibly distinct from other variables. It eliminates confusion that is possible when you use a local variable whose name happens to match that of a common fact.

Because of ambiguity with function invocation, the dot-separated access syntax that is available in Facter commands is not available with the $facts hash access syntax. However, you can instead use the fact function included in the stdlib module. Read more about it in the stdlib module README.

Improving performance by blocking or caching built-in facts

If Facter is slowing down your code, you can configure Facter to block or cache built-in facts. When a system has a lot of something — for example, mount points or disks — Facter can take a long time to collect the facts from each one. When this is a problem, you can speed up Facter’s collection by configuring these settings in the facter.conf file:
  • blocklist for blocking built-in facts you’re uninterested in.

  • ttls for caching built-in facts you don’t need retrieved frequently.

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, master 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 should 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 hashPossible 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'      => '',
  'domain'        => '',
  'extensions'    => {
                      'pp_uuid'                         => 'ED803750-E3C7-44F5-BB08-41A04433FE2E',
                      'pp_image_name'           => 'storefront_production'
                      '' => '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
  - 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.''}.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    => "",
  serverip      => "",
  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 factsValues
$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_environmentis 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 variablesValues
$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.
$servernameThe 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.
$serveripThe master’s IP address.
$serverversionThe 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 $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.

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 variablesValues
$module_nameThe name of the module that contains the current class or defined type.
$caller_module_nameThe 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.
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.