Writing Fact Plugins

Fact plugins are used during discovery whenever you run the agent with queries like -W country=de.

The default setup uses a YAML file typically stored in /etc/mcollective/facts.yaml to read facts. There are however many fact systems like Reductive Labs Facter and Opscode Ohai or you can come up with your own. The facts plugin type lets you write code to access these tools.

Facts at the moment should be simple variable = value style flat Hashes, if you have a hierarchical fact system like Ohai you can flatten them into var.subvar = value style variables.

Details

Implementing a facts plugin is made simple by inheriting from MCollective::Facts::Base, in that case you just need to provide 1 method, the YAML plugin code can be seen below:

For releases in the 1.0.x release cycle and older, use this plugin format:

 1 module MCollective
 2     module Facts
 3         require 'yaml'
 4 
 5         # A factsource that reads a hash of facts from a YAML file
 6         class Yaml<Base
 7             def self.get_facts
 8                 config = MCollective::Config.instance
 9 
10                 facts = {}
11 
12                 YAML.load_file(config.pluginconf["yaml"]).each_pair do |k, v|
13                     facts[k] = v.to_s
14                 end
15 
16                 facts
17             end
18         end
19     end
20 end

For releases 1.1.x and onward use this format:

 1 module MCollective
 2     module Facts
 3         require 'yaml'
 4 
 5         class Yaml_facts<Base
 6             def load_facts_from_source
 7                 config = MCollective::Config.instance
 8 
 9                 facts = {}
10 
11                 YAML.load_file(config.pluginconf["yaml"]).each_pair do |k, v|
12                     facts[k] = v.to_s
13                 end
14 
15                 facts
16             end
17         end
18     end
19 end

If using the newer format in newer releases of mcollective you do not need to worry about caching or thread safety as the base class does this for you. You can force reloading of facts by creating a force_reload? method that should return true or false. Returning true will force the cache to be rebuilt.

You can see that all you have to do is provide self.get_facts which should return a Hash as described above.

There’s a sample using Puppet Labs Facter on the plugins project if you wish to see an example that queries an external fact source.

Once you’ve written your plugin you can save it in the plugins directory and configure mcollective to use it:

factsource = yaml

This will result in MCollective::Facts::Yaml or MCollective::Facts::Yaml_facts being used as source for your facts.

↑ Back to top

Docs: Writing Fact Plugins

Writing Fact Plugins

Details