A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://docs.cfengine.com/latest/reference-language-concepts-augments.html below:

Augments - CFEngine 3.26 Docs

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:

code

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:

code

$ 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:

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:

def.json

The file def.json is found based on the location of the policy entry (the first policy file read by the agent):

Notes:

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:

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:

code

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:

code

body file control
{
      namespace => "MyNamespace";
}
bundle agent my_bundle
{
  vars:
      "Variable"
        string => "value",
        meta => { "inventory", "attribute_name=My Inventory" };
}

Notes:

History:

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

code

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

code

"vars" : {
    "str1" : "string 1",
    "num1" : 5,
    "num2" : 3.5
    "slist1" : ["sliststr1", "sliststr2"]
    "array1" : {
        "idx1" : "val1",
        "idx2" : "val2"
    }
}

Notes:

History:

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:

code

{
    "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:

code

{
    "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

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:

code

% 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:

History:

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:

code

{
  "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:

code

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

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4