Codebase list facter / 6456bf7
(cfact-32) Add a first draft of Extensibility.md Kylo Ginsberg 9 years ago
1 changed file(s) with 65 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
+65
-0
Extensibility.md less more
0 Extensibility
1 =============
2
3 Native Facter has the following extensibility goals:
4 * Clear guidelines for what facts are supported in-project
5 * Compatibility with 90+% of existing Facter custom facts
6 * Compatibility with 100% of existing Facter external facts
7 * New features for external facts, including depends/requires logic
8
9 The following sections discuss those goals in more depth.
10
11 Note that this doc is work-in-progress and should be updated as extensibility features are implemented, refined or ruled out.
12
13 Built-in facts
14 --------------
15
16 These are the criteria for Native Facter pull requests:
17 * Additional resolutions for existing built-in facts (e.g. the operatingsystem facts for new Linux Distros) must conform to the facter.json schema.
18 * New facts must be accompanied by support in the facter.json schema.
19 * For [SemVer](http://semver.org) purposes, a change in fact value is only considered breaking if a) the fact is documented in the schema, and b) the fact is applicable on a platform we test againt in [Puppet CI](http://jenkins.puppetlabs.com).
20
21 Legacy Custom Facts Compatibility
22 ---------------------------------
23
24 The Ruby Facter project supports "custom facts" which are fact implementations written using the internal Facter API. For compatibility purposes, Native Facter will support the most commonly used subset of that API specifically:
25 ```
26 Facter.value
27 Facter.add
28 confine
29 setcode
30 has_weight (maybe?)
31 ```
32
33 It is TBD whether Native Facter will support custom facts which rely on other custom facts. (See New Features for External Facts below for possible mitigation.)
34
35 In terms of implementation, there are two avenues we may pursue:
36 * A standalone ruby shim which executes existing custom facts. This might be able to run as just another external fact.
37 * A custom fact resolver which calls the Ruby C API to execute custom facts.
38 We will decide between these two approaches after some spiking to see which will be most robust and maintainable.
39
40 Long-term, the new features for external facts should encourage users to port their legacy custom facts to external facts, so at some point (e.g. a couple major versions down the line) this shim logic should be retired.
41
42 External Facts Compatiblity
43 ---------------------------
44
45 Native Facter will support all 4 forms of "external facts" which Ruby Facter supports:
46 * JSON files with the .json extension whose key-value pairs will be mapped to fact-value pairs.
47 * YAML files with the .yaml extension whose key-value pairs will be mapped to fact-value pairs.
48 * Text files with the .txt extension containing `fact=some_value` strings
49 * Executable files returning `fact=some_value` strings
50
51 New Features for External Facts
52 -------------------------------
53
54 Caveat: It is TBD which of these features will be implemented in what releases.
55
56 * Executable external facts can take a json object on stdin describing all known facts. This will allow logic like the confine/value methods provide in the custom facts API.
57
58 * To support the use case of facts which depend on other facts: executable external facts can describe what facts they depend on and what facts they provide, via a json schema. (This schema could either be a parallel file distributed with the external fact following some naming convention (e.g. foo.schema for an external fact called foo.sh or foo.py), or the schema could be provided on stdout when executing the external fact with some parameter (e.g. foo.sh --show-schema).)
59
60 * Native Facter might add a weight indicator for returned facts, to support fact precedence for external facts, along the lines of the `has_weight` functionality.
61
62 * Native Facter might add a volatility indicator, such as a ttl field, to the json schema provided by external facts. This would allow facter in a long-running process to avoid unnecessary refreshes of non-volatile facts.
63
64 * Native Facter might include some language-specific shims for its external facts support, most likely for Ruby and Python, to ease writing new external facts (including ports of legacy custom facts).