Advanced configuration management

Directory /var/rudder/policy-generation-info contains information about the last policy generation(s) in the following files:

Each file starts with a comment describing what policy generation generated it. Two version of each of these files is conserved: the oldest one has a .old suffix.

Rudder web application logs located in /var/log/rudder/webapp/yyyy_MM_dd.stderrout.log contains information about policy generation process. All policy generation logs are gathered under policy.generation namespace (with optionally more precise namespace, like policy.generation.timing for timing information, or policy.generation.update for updated nodes, etc). By default, policy generation logs when it starts with generic information about system:

How many nodes were updated:

Timing information about generation steps (they are always logged to allow checking general performance evolution):

End finally summary of generation: success or failure, total time:

Much more information can be logged about policy generation (hook execution and timing, much more precise timing, updated nodes, files written, etc). All corresponding logs and verbosity levels are documented and controlled in /opt/rudder/etc/logback.xml.

This directory contains hooks executed after an inventory was received for an already accepted node and the node information were successfully updated.

Typically, these hooks triggers action on other systems, like updating info on an external CMDB, or send notification.

Hooks parameters are passed by environment variable:

This directory contains hooks executed after a node inventory was received but its processing failed.

Typically, these hooks triggers action on other system, or to send notification.

Hooks parameters are passed by environment variable:

This directory contains hooks executed after an inventory was successfully processed for a node in pending state (never seen, or already pending).

Typically, these hooks triggers action on other system, like registering the node into a monitoring system or into an external CMDB, or to send notification.

Hooks parameters are passed by environment variable:

This directory contains hooks executed after a node was successfully accepted.

Typically, these hooks triggers action on other system, like registering the node into a monitoring system or into an external CMDB, or to send notification.

Hooks parameters are passed by environment variable:

This directory contains hooks executed after a node was successfully deleted.

Typically, these hooks clean resources related to that node and notify external services that the node was deleted from Rudder.

Hooks parameters are passed by environment variable:

This directory contains hooks executed before a node is deleted.

Typically, these hooks interact with external services using knowledge to validate if the node should actually be deleted.

Hooks parameters are passed by environment variable:

This directory contains hooks executed when a policy generation failed.

Hooks parameters are passed by environment variable:

This directory contains hooks executed after policies are fully generated for all nodes, and these new policies are available for download for the node.

Typically, these hooks are used to log information about the generation which just happened or notify third parties that new policies are available (for ex: cf-serverd SIGHUP)

Hooks parameters are passed by environment variable:

This directory contains hooks executed after policies are fully generated for node and made available for the node to download.

Typically, these hooks interact with external services using knowledge from the generated policies (ex: send node-properties JSON file to a third party service).

Hooks parameters are passed by environment variable:

Technically, you could infer RUDDER_POLICIES_DIRECTORY_NEW, from RUDDER_NODE_ID, but it’s tedious for nodes behind a relay, and it is just simpler not to have to track what are the Rudder internal names, which may change without notice.

This directory contains hooks executed after policies are fully generated for node, but before these new policies replace the old ones (technically, before we move /var/rudder/share/$NODEID/rules.new to /var/rudder/share/$NODEID/rules).

Typically, these hooks proceed to sanity checks on the new policies (ex: cf-promises), update permission on files, or interact with external services using information from the generated policies (ex: send node-properties JSON file to a third party service).

Hooks parameters are passed by environment variable:

Technically, you could infer RUDDER_POLICIES_DIRECTORY_NEW, from RUDDER_NODE_ID, but it’s tedious for nodes behind a relay, and it is just simpler not to have to track what are the Rudder internal names, which may change without notice.

This directory contains hooks executed before policy generation.

Typically, these hooks are used to check the integrity of techniques.

An error during the execution in one of them will stop policy generation, preventing deployment of new policies until the hook succeeds.

Hooks parameters are passed by environment variable:

This directory contains hooks executed when a policy generation starts.

Typically, these hooks are used to log information about the generation which just started or notify third parties that shared information to node should be updated (shared-folder, etc).

Hooks parameters are passed by environment variable:

Once you have found the rule’s ID (for example, in the rule details page), you just need to call the export API with that parameter: all dependencies up to techniques are resolved and included by default. This is equivalent to using the parameter include=all as shown in the command below.

Now, we will take a quick look at the content of an archive.

We see that the archive has a standard directory layout looking like the one in /var/rudder/configuration-repository. In each directory, you find serialisation of the corresponding configuration items. For rules, directives, and groups, the file has the item name normalized. The content is the same as the one you get when you query the item details on REST API. For techniques, the subdirectory layout and technique content is exactly the same as the one in have in /var/rudder/configuration-repository/techniques.

You can update content in that archive, create a new ZIP with the following command, and import it back into rudder to update policies. For example:

And see next chapter for importing it.

Another common use case is when you need several rules with specific directive to achieve a configuration need on several OS - typically, you want to enforce some security checks on Debian and Redhat, but these checks vary. So you develop things in QA, and when it’s ok, you import them prod - but not the groups, which are different. For that, you will restrict the scope of what dependencies are included in the archive (rule1 and rule2 are used in place of UUIDs for readability):

And if you still need a specific group, directive or technique, or directive added in the archive, just add them in the query:

Finally, you can obtain an archive with configuration from a past revision. Just append the revision to the item id after a URL-encoded + (ie %2B) and its dependencies will be resolved for the same revision.

For example, for getting a rule and its dependencies from revision with commit ID 5962a856684ab8ce2363f302ed4ee9455786fd03, use the command: