Custom facts overview

Sometimes you need to be able to write conditional expressions based on site-specific data that just isn’t available via Facter, or perhaps you’d like to include it in a template.

Because you can’t include arbitrary Ruby code in your manifests, the best solution is to add a new fact to Facter. These additional facts can then be distributed to Puppet clients and are available for use in manifests and templates, just like any other fact is.

Facter offers multiple methods of loading facts.

These include:

You can use these methods to do things like test files locally before distributing them, or you can arrange to have a specific set of facts available on certain machines.

#~/lib/ruby
└── facter
    ├── rackspace.rb
    ├── system_load.rb
    └── users.rb

$ ls my_facts
system_load.rb
$ ls my_other_facts
users.rb
$ facter --custom-dir=./my_facts --custom-dir=./my_other_facts system_load users
system_load => 0.25
users => thomas,pat

$ ls my_facts
system_load.rb
$ ls my_other_facts
users.rb
$ export FACTERLIB="./my_facts:./my_other_facts"
$ facter system_load users
system_load => 0.25
users => thomas,pat

Most facts have at least two elements.

Facts can get a lot more complicated than that, but those two together are the most common implementation of a custom fact.

Puppet gets information about a system from Facter, and the most common way for Facter to get that information is by executing shell commands.

You can write a fact that uses other facts by accessing Facter.value('somefact'). If the fact fails to resolve or is not present, Facter returns nil.

Facter.add('osfamily') do
  setcode do
    distid = Facter.value('lsbdistid')
    case distid
    when /RedHatEnterprise|CentOS|Fedora/
      'redhat'
    when 'ubuntu'
      'debian'
    else
      distid
    end
  end
end

Facts have properties that you can use to customize how they are evaluated.

Facter.add('powerstates') do
  confine kernel: 'Linux'
  setcode do
    Facter::Core::Execution.execute('cat /sys/power/states')
  end
end

confine 'os.family' => :redhat

confine 'os' do |os|
  os['family'] == 'RedHat'
end

# Check to see if this server has been marked as a postgres server
Facter.add('role') do
  has_weight 100
  setcode do
    if File.exist? '/etc/postgres_server'
      'postgres_server'
    end
  end
end

# Guess if this is a server by the presence of the pg_create binary
Facter.add('role') do
  has_weight 50
  setcode do
    if File.exist? '/usr/sbin/pg_create'
      'postgres_server'
    end
  end
end

# If this server doesn't look like a server, it must be a desktop
Facter.add('role') do
  setcode do
    'desktop'
  end
end

Facter.add('foo', {timeout: 0.2}) do
 setcode do
   Facter::Core::Execution.execute("sleep 1")
 end
End

Facter.add('sleep') do
  setcode do
    begin
      Facter::Core::Execution.execute('sleep 10', options = {:timeout => 5})
      'did not timeout!'
    rescue Facter::Core::Execution::ExecutionFailure
      Facter.warn("Sleep fact timed out!")
    end
  end
end

Structured facts take the form of either a hash or an array.

To create a structured fact, return a hash or an array from the setcode statement.

You can see some relevant examples in the Writing structured facts section of the Custom facts overview.

Facter 4 introduced a new way to aggregate facts using dot notation. For more information, see Writing aggregate resolutions.

If your fact combines the output of multiple commands, use aggregate resolutions. An aggregate resolution is split into chunks, each one responsible for resolving one piece of the fact. After all of the chunks have been resolved separately, they’re combined into a single flat or structured fact and returned.

Facter.add('fact_name', :type => :aggregate) do
    #chunks go here
    #aggregate block goes here
end

chunk(:one) do
    'Chunk one returns this. '
end

chunk(:two) do
    'Chunk two returns this. '
end

aggregate do |chunks|
  result = ''

  chunks.each_value do |str|
    result += str
  end

  # Result: "Chunk one returns this. Chunk two returns this."
  result
end

For more examples of aggregate resolutions, visit Writing facts with aggregate resolutions.

If your Puppet primary servers are configured to use PuppetDB, you can view and search all of the facts for any node, including custom facts.

See the PuppetDB docs for more info.

Environment facts allow you to override core facts and add custom facts.

To access a fact set with environment variables, you can use the CLI or the Ruby API (Facter.value or Facter.fact methods). Use the environment variable prefixed with FACTER_, for example:

$ facter virtual
physical
$ FACTER_virtual=virtualbox facter virtual 
virtualbox

Note that environment facts are downcased before they are added to the fact collection, for example, FACTER_EXAMPLE and FACTER_example resolve to a single fact named example.