Augments
Augments files can be used to define variables and classes for use by all CFEngine components before any parsing or evaluation happen. Augments are fundamentally JSON data files, so you should view and edit them with a JSON-aware editor if possible. This is a convenient way to override defaults defined in the default policy, the Masterfiles Policy Framework (MPF), without modifying the shipped policy files.
Using the MPF without maintaining your own patches to it
As an example, you can add your own policy file to inputs and bundle name to the
bundle sequence, without editing promises.cf, by adding the Augments file below
(/var/cfengine/masterfiles/def.json):
}
In this case, the contents of the policy file, /var/cfengine/masterfiles/services/my_policy_file.cf, could look something like this:
bundle agent my_bundle_name
{
files:
"/tmp/hello"
create => "true",
content => "cfengine";
}
You can ensure the file is deleted and use the info log output to confirm that the policy is actually being run:
$ cf-agent -Kf update.cf && cf-agent -K
$ rm /tmp/hello ; cf-agent -KI
info: Created file '/tmp/hello', mode 0600
info: Updated content of '/tmp/hello' with content 'cfengine'
In this example, control_common_bundlesequence_end is a special variable, handled by the Masterfiles Policy Framework (MPF).
To learn about more variables like this and ways to interact with the MPF without editing it, see the MPF Reference documentation.
The rest of this documentation page below focuses on the specifics of how augments files work, independently of everything they can be used for in the MPF.
Augments files
There are two canonical augments files, host_specific.json, and def.json which may load additional Augments
as specified by the augments key.
Notes:
- CFEngine variables are not expanded unless otherwise noted.
host_specific.json
If $(sys.workdir)/data/host_specific.json (typically /var/cfengine/data/host_specific.json) is the first augments file that is loaded. Any variables defined as a result of processing this file
are automatically tagged with source=cmdb. Variables defined from this file can not be overridden by subsequently processed augments files. Policy always wins and thus can overwrite the variable.
Notes:
- This file does not support the augments key.
def.json
The file def.json is found based on the location of the policy entry (the first policy file read by the agent):
- with no arguments, it's in
$(sys.inputdir)/def.jsonbecause$(sys.inputdir)/promises.cfis used - with
-f /dirname/myfile.cf, it's in/dirname/def.json - with
-f ./myfile.cf, it's in./def.json
Notes:
sysvariables are expanded indef.jsonand all subsequently loaded augments as specified by theaugmentskey.def_preferred.jsonwill be used instead ofdef.jsonif it is present. This preferential loading can be disabled by providing the--ignore-preferred-augmentsoption to the agent.
Augments keys
An augments file can contain the following keys:
inputs
This key is supported in def.json, def_preferred.json, and augments loaded by the augments key.
Filenames entered here will appear in the def.augments_inputs variable.
Notes:
Files are loaded relative to
sys.policy_entry_dirname.The inputs key has precedence over the vars key.
If both the inputs key and
vars.augments_inputsare populated concurrently, the variabledef.augments_inputswill hold the value set by the inputs key. Thedef.augments_inputsvariable is part of the default inputs in theMasterfiles Policy Framework.
Examples:
}
The above Augments results in $(sys.policy_entry_dirname)/services/hello-world.cf, $(sys.policy_entry_dirname)/example.cf and /tmp/my_policy.cf being added to inputs.
}
The above Augments results in $(sys.policy_entry_dirname)/goodbye.cf being added to inputs.
variables
This key is supported in both host_specific.json, def.json, def_preferred.json, and augments loaded by the augments key.
Variables defined here can target a namespace and or bundle scope explicitly. When defined from host_specific.json, variables default to the variables bundle in the data namespace ($(data:variables.MyVariable)).
For example:
}
}
Variables can target the implicit namespace while specifying the bundle.
For example:
}
}
Variables can also target a namespace explicitly.
For example:
}
}
The comment key is optional, if supplied, the comment will be associated with the variable definition as if you had applied the comment attribute to a vars type promise.
For example, this JSON:
}
}
Is equivalent to this policy:
body file control
{
namespace => "MyNamespace";
}
bundle agent my_bundle
{
vars:
"Variable"
string => "value",
comment => "An optional note about why this variable is important";
}
The tags key is optional, if supplied, the tags will be associated with the variable definition as if you had applied the meta attribute to a vars type promise.
For example, this JSON:
}
}
Is equivalent to this policy:
body file control
{
namespace => "MyNamespace";
}
bundle agent my_bundle
{
vars:
"Variable"
string => "value",
meta => { "inventory", "attribute_name=My Inventory" };
}
Notes:
varsandvariableskeys are allowed concurrently in the same file.- If
varsandvariableskeys in the same augments file define the same variable, the definition provided by thevariableskey wins.
History:
- Added in 3.18.0
vars
This key is supported in both host_specific.json, def.json, and def_preferred.json and augments loaded by the augments key.
Variables defined here can target a namespace and or bundle scope
explicitly. When defined from def.json, variables default to the def
bundle in the default namespace ($(default:def.MyVariable)).
Thus:
}
results in the variable default:def.phone with value 22-333-4444,
default:def.myplatform with the value of your current OS,
default:MyBundle.MyVariable with the value MyValue in MyBundle.MyVariable
and MyNamespace:MyBundle.MyVariable with the value MyValue in
MyNamespace:MyBundle.MyVariable.
Again, note that this happens before policy is parsed or evaluated.
You can see the list of variables thus defined in the output of cf-promises
--show-vars (see Components). They will be tagged with
the tag source=augments_file. For instance, the above two variables (assuming
you placed the data in $(sys.inputdir)/def.json) result in
cf-promises --show-vars=default:def
...
default:def.myplatform linux source=augments_file
default:def.phone 22-333-4444 source=augments_file
Variables of other types than string can be defined too, like in this example
"vars" : {
"str1" : "string 1",
"num1" : 5,
"num2" : 3.5
"slist1" : ["sliststr1", "sliststr2"]
"array1" : {
"idx1" : "val1",
"idx2" : "val2"
}
}
Notes:
varsandvariableskeys are allowed concurrently in the same file.- If
varsandvariableskeys in the same augments file define the same variable, the definition provided by thevariableskey wins.
History:
- 3.18.0 gained ability to specify the namespace and bundle the variable should be defined in.
classes
This key is supported in both host_specific.json, def.json, def_preferred.json, and augments loaded by the augments key.
Any class defined via augments will be evaluated and installed as soft classes. This key supports both array and dict formats.
For an array each element of the array is tested against currently defined
classes as an anchored regular expression unless the string ends with :: indicating it should be interpreted as a
class expression.
For example:
}
The tags, comment, and the mutually exclusive class_expressions, and regular_expressions subkeys
are supported when using the dict structure.
For example:
{
"classes": {
"myclass_defined_by_augments_in_def_json_3_18_0_v0": {
"class_expressions": [ "linux.redhat::", "cfengine|linux::" ],
"comment": "Optional description about why this class is important",
"tags": [ "optional", "tags" ]
},
"myclass_defined_by_augments_in_def_json_3_18_0_v1": {
"regular_expressions": [ "linux.*", "cfengine.*" ],
"tags": [ "optional", "tags" ]
}
}
}
Note that augments is processed at the very beginning of agent evaluation. You can use any hard classes, persistent classes , or classes defined earlier in the augments list. Test carefully, custom soft classes may not be defined early enough for use. Thus:
{
"classes": {
"augments_class_from_regex_my_always": [ "any" ],
"augments_class_from_regex_my_other_apache": [ "server[34]", "debian.*" ],
"augments_class_from_regex_my_other_always": [ "augments_class_from_regex_my_always" ],
"augments_class_from_regex_when_MISSING_not_defined": [ "^(?!MISSING).*" ],
"augments_class_from_regex": [ "cfengine_\\d+" ],
"augments_class_from_single_class_as_regex": [ "cfengine" ],
"augments_class_from_single_class_as_expression": [ "cfengine::" ],
"augments_class_from_classexpression_and": [ "cfengine.cfengine_3::" ],
"augments_class_from_classexpression_not": [ "!MISSING::" ],
"augments_class_from_classexpression_or": [ "cfengine|cfengine_3::" ],
"augments_class_from_classexpression_complex": [ "(cfengine|cfengine_3).!MISSING::" ],
"myclass_defined_by_augments_in_def_json_3_18_0_v0": {
"class_expressions": [ "linux.redhat::", "cfengine|linux::" ],
"comment": "Optional description about why this class is important",
"tags": [ "optional", "tags" ]
},
"myclass_defined_by_augments_in_def_json_3_18_0_v1": {
"regular_expressions": [ "linux.*", "cfengine.*" ],
"tags": [ "optional", "tags" ]
}
}
}
results in
augments_class_from_rgex_my_alwaysbeing always defined.augments_class_from_regex_my_other_apachewill be defined if the classesserver3orserver4are defined, or if any class starting withdebianis defined.augments_class_from_regex_my_other_alwayswill be defined becauseaugments_class_from_regex_my_alwaysis listed first and always defined.augments_class_from_regex_when_MISSING_not_definedwill be defined if the classMISSINGis not defined.augments_class_from_single_class_as_regexwill be defined because the classcfengineis always defined.augments_class_from_single_class_as_expressionwill be defined becausecfengineis defined when interpreted as a class expression.augments_class_from_classexpression_andwill be defined because the classcfengineand the classcfengine_3are defined and the class expressioncfengine.cfengine_3::evaluates to true.augments_class_from_classexpression_notwill be defined because the class expression!MISSING::evaluates to false since the classMISSINGis not defined.augments_class_from_classexpression_orwill be defined because the class expressioncfengine|cfengine_3::evaluates to true since at least one ofcfengineorcfengine_3will always be defined by cfengine 3 agents.augments_class_from_classexpression_complexwill be defined because the class expression(cfengine|cfengine_3).!MISSING::evaluates to true since at least one ofcfengineorcfengine_3will always be defined by cfengine 3 agents andMISSINGis not defined.myclass_defined_by_augments_in_def_json_3_18_0_v0will be defined because the class expressioncfengine|linux::will always be true since there is always acfengineclass defined.myclass_defined_by_augments_in_def_json_3_18_0_v1will be defined because the expressioncfengine.**will match at least one defined class,cfengine
You can see the list of classes thus defined through def.json in the output
of cf-promises --show-classes (see Components). They
will be tagged with the tags source=augments_file. For instance:
% cf-promises --show-classes=my
Class name Meta tags Comment
augments_class_from_regex_my_always source=augments_file
augments_class_from_regex_my_other_always source=augments_file
augments_class_from_regex_my_other_apache source=augments_file
myclass_defined_by_augments_in_def_json_3_18_0_v0 optional,tags,source=augments_file Optional description about why this class is important
myclass_defined_by_augments_in_def_json_3_18_0_v1 optional,tags,source=augments_file
See also:
- Functions that use regular expressions with classes:
classesmatching(),classmatch(),countclassesmatching()
History:
- 3.18.0
- Support for dict structure for classes and support for metadata (
comment,tags) added. - Classes are defined as soft classes instead of hard classes.
- Support for dict structure for classes and support for metadata (
augments
This key is supported in def.json, def_preferred.json, and augments loaded by the augments key.
A list of file names that should be merged using mergedata() semantic
Example:
Here we merge a platform specific augments on to the def.json loaded next to
the policy entry and see what the resulting variable values will
be.
The def.json next to the policy entry:
{
"vars":{
"my_var": "defined in def.json",
"my_other_var": "Defined ONLY in def.json"
},
"augments": [
"/var/cfengine/augments/$(sys.flavor).json"
]
}
The platform specific augments on a CentOS 6 host:
/var/cfengine/augments/centos_6.json:
}
The expected values of the variables defined in the def bundle scope:
R: def.my_var == Overridden in centos_6.json
R: def.my_other_var == Defined ONLY in def.json
R: def.centos_6_var == Defined ONLY in centos_6.json
History
- 3.18.0
- Introduced
variableskey with support for metadata (comment,tags) and targeting the namespace and bundle. - Introduced ability for
varsto target namespace and bundlevariableskey with support for metadata (comment,tags). - Introduced metadata (
comment,tags) support forclasseskey. - Introduced
def_preferred.jsonand--ignore-preferred-augmentsto disable it. - Classes defined from augments are now soft classes and not hard classes.
- Introduced parsing of
$(sys.workdir)/data/host_specific.json
- Introduced
- 3.12.2, 3.14.0 introduced class expression interpretation (
::suffix) to classes key - 3.12.0 introduced the
augmentskey - 3.7.3 back port
def.jsonparsing in core agent and loaddef.jsonif present next to policy entry - 3.8.2 removed core support for
inputskey, loaddef.jsonif present next to policy entry - 3.8.1
def.jsonparsing moved from policy to core agent for resolution of classes and variables to be able to affect control bodies - 3.7.0 introduced augments concept into the Masterfiles Policy Framework