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.
-
Core facts from Facter.
-
Custom facts and external facts that are present in your modules.
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
.
if $osfamily == 'RedHat' {
# ...
}
$::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.
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
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 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:
|
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.
|
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 |
$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.
$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 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 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. |