Puppet provides a comprehensive set of built-in variables, often referred to as facts, that offer crucial information about nodes, the Puppet environment, and the catalog compilation process. These variables empower Puppet manifests to make dynamic decisions based on the system's current state and context, streamlining configuration management. Beyond Facter's core and custom facts, Puppet itself generates several categories of these variables, including trusted facts, server facts, agent facts, server variables, and compiler variables.
Understanding Puppet's Built-in Variables
Built-in variables are pre-defined data points that Puppet makes available during its operation. They eliminate the need for manual data input for common system attributes, enabling highly automated and adaptive infrastructure management.
Facter Facts
Facter facts are the most common type of built-in variable in Puppet. Facter is Puppet's system inventory tool, which gathers extensive information about a node's operating system, network interfaces, memory, CPU, and many other system attributes.
- Core Facts: These are automatically discovered by Facter on nearly every system Puppet runs on. Examples include
os['family'],ipaddress,fqdn,architecture, anduptime. - Custom Facts: You can define your own custom facts to gather specific information not provided by Facter's core facts, tailored to your environment's unique needs.
Accessing Facter Facts:
In modern Puppet, Facter facts are accessed through the $facts hash. While direct access like $osfamily was common, using the $facts hash (e.g., $facts['os']['family']) is the recommended and future-proof method.
Example:
To ensure a package is installed only on RedHat-based systems:
if $facts['os']['family'] == 'RedHat' {
package { 'httpd':
ensure => present,
}
}For more details, refer to the official Facter documentation.
Trusted Facts
Trusted facts are a special category of built-in variables that provide cryptographically secure information about the node. These facts are generated by the Puppet agent and then verified by the Puppet server during the SSL handshake process, ensuring their integrity and authenticity.
- Purpose: Trusted facts are crucial for security, allowing Puppet to make access control and configuration decisions based on verified node identity. They prevent spoofing by ensuring the data comes from the expected, authenticated agent.
- Accessing Trusted Facts: These are always accessed via the
$trustedhash.
Examples:
$trusted['certname']: The agent's certificate name, which is its unique identifier in Puppet.$trusted['hostname']: The agent's hostname.$trusted['domain']: The agent's domain name.$trusted['extensions']: Any custom OID extensions included in the agent's certificate, often used to embed extra verified information like organizational roles.
For more information, see the Puppet Trusted Facts documentation.
Server Variables (including Server Facts)
Server variables provide information about the Puppet Server, its configuration, and the environment in which the catalog is being compiled. While Facter collects facts about the agent node, these variables give insights into the server-side context. These are often made available through the $server_facts hash.
- Purpose: Useful for auditing, conditional logic based on the server's identity, or dynamically configuring agents based on their assigned environment.
- Accessing Server Variables: Typically accessed through the
$server_factshash or direct variable names for some common server-related information.
Examples:
$server_facts['environment']: The name of the environment (e.g.,production,development) for which the current catalog is being compiled.$server_facts['version']: The version of the Puppet Server software.$server_facts['fqdn']: The fully qualified domain name of the Puppet Server.$server_facts['puppet_version']: The version of Puppet running on the server.
Compiler Variables
Compiler variables are intrinsic to the Puppet catalog compilation process. They provide context specific to the manifest file being processed or the module currently in use, helping authors write more dynamic and reusable code.
- Purpose: Offer contextual information within Puppet manifests, enabling modular and environment-aware configurations.
- Accessing Compiler Variables: These are accessed as direct variable names within Puppet manifests.
Examples:
$environment: The name of the environment currently being compiled. This is also often available as$server_facts['environment'].$module_name: The name of the module containing the current class or defined type.$caller_module_name: The name of the module that declared the current class or defined type. This is useful for preventing recursive dependencies or for context-aware configurations.$title: The title of the current resource being declared.
More details on these variables can be found in the Puppet language documentation.
Agent Variables
While much of the agent's specific information is covered by Facter, Puppet also makes a few variables available that relate directly to the agent's operational state or identifier during a run. These are less a distinct category and more specific runtime values.
- Purpose: Primarily for tracking or debugging specific agent executions.
- Accessing Agent Variables: Accessed as direct variable names.
Example:
$agent_run_id: A unique identifier generated for the current Puppet agent run. This can be useful for linking logs or external reporting to a specific agent execution.
Summary Table of Built-in Puppet Variables
| Category | Description | Access Method | Example |
|---|---|---|---|
| Facter Facts | Information about the agent node (OS, hardware, network, etc.) discovered by Facter. Includes core and custom facts. | $facts['name'] or $name |
$facts['os']['family'], $facts['ipaddress'] |
| Trusted Facts | Cryptographically verified information about the agent node, provided during the SSL handshake between agent and server, ensuring authenticity. | $trusted['name'] |
$trusted['certname'], $trusted['extensions']['pp_role'] |
| Server Variables | Information about the Puppet Server itself, its configuration, and the environment being compiled. | $server_facts['name'] |
$server_facts['environment'], $server_facts['version'] |
| Compiler Variables | Contextual variables available during catalog compilation, specific to the manifest or module being processed. | $variable_name |
$environment, $module_name, $caller_module_name |
| Agent Variables | Specific runtime variables related to the Puppet agent's operation. (Less a distinct category, more specific runtime values). | $variable_name |
$agent_run_id |
Practical Insights and Best Practices
- Viewing All Variables:
- On a Puppet agent node, you can run
facter -pto see all Facter facts (including custom facts) in a structured JSON format. - For debugging during catalog compilation, you can use
puppet lookup --node <node_name> --environment <environment> <variable_name>or addnotifyresources in your manifests to output variable values during a Puppet run.
- On a Puppet agent node, you can run
- Consistency: Always use the
$facts['name']syntax for Facter facts to ensure compatibility with future Puppet versions and to maintain a clear distinction from other variable types. - Security: Leverage trusted facts for any security-sensitive logic, such as assigning roles, granting access, or making critical configuration changes, as their authenticity is guaranteed.
- Context Awareness: Understand where each variable is available. Facter facts and agent variables are client-side, while trusted facts, server variables, and compiler variables are primarily used during server-side catalog compilation.
- Modularity: Utilize compiler variables like
$module_nameand$caller_module_nameto create highly reusable and context-aware modules that adapt based on where and how they are used.
