diff --git a/content/examples/tutorials/policy-writing/policy-style.markdown b/content/examples/tutorials/policy-writing/policy-style.markdown index 4717b609f..8a923730b 100644 --- a/content/examples/tutorials/policy-writing/policy-style.markdown +++ b/content/examples/tutorials/policy-writing/policy-style.markdown @@ -87,8 +87,8 @@ significantly easier for a novice to understand the desired state. Historically, it was important to remember that Normal ordering still applied and that the promises would not be actuated in the order they are written. However, as of CFEngine 3.27.0, you can use `evaluation_order => "top_down";` in -`body common control` or `body agent control` to make the execution order match -the written order. +`body common control`, `body agent control`, or `body file control` to make the +execution order match the written order. ```cf3 body common control diff --git a/content/reference/components/_index.markdown b/content/reference/components/_index.markdown index f19ed1486..646f875c8 100644 --- a/content/reference/components/_index.markdown +++ b/content/reference/components/_index.markdown @@ -245,7 +245,7 @@ body common control } ``` -**See also:** [`evaluation_order` in `body common control`][cf-agent#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering] +**See also:** [`evaluation_order` in `body agent control`][cf-agent#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering] **History:** diff --git a/content/reference/components/file_control_promises.markdown b/content/reference/components/file_control_promises.markdown index 82a319d2c..3a2ba0c41 100644 --- a/content/reference/components/file_control_promises.markdown +++ b/content/reference/components/file_control_promises.markdown @@ -26,6 +26,66 @@ outside of body and bundle definitions. Only [soft classes][Classes and decisions] from common bundles can be used in class decisions inside `file control bodies`. +### evaluation_order + +**Description:** `evaluation_order` in body file control sets the evaluation order for the subsequent bundles in the file. + +This setting allows you to change the order in which components execute policy within a given policy file. +By default, CFEngine uses a `classic` evaluation order, where promises are executed in a predefined order based on their type (e.g., `vars` before `files`, `files` before `packages`, etc.). +This is the historical behavior of CFEngine. + +By setting `evaluation_order` to `top_down`, you can force components to evaluate promises in the order they are written in the policy file, from top to bottom. +This can make policy evaluation more familiar and possibly easier to write and understand, especially for new users, as the execution flow follows the visual layout of the code. + +This attribute can also be set in `body common control` to affect all components and or `body agent control` to affect all files. +If set in multiple places, the value in `body agent control` takes precedence for `cf-agent`. + +**Type:** `string` + +**Allowed input range:** `(classic|top_down)` + +**Default value:** `classic` + +**Example:** + +```cf3 +body file control +{ + evaluation_order => "top_down"; +} + +bundle agent reports_top_down +{ + reports: "Hello world:"; + + commands: "/bin/echo hi"; + + reports: "bye:"; +} +bundle agent __main__ +{ + methods: "reports_top_down"; +} + +body agent control +{ + evaluation_order => "top_down"; +} +``` + +Executed would result in: + +```output +R: Hello world: + notice: Q: ".../bin/echo hi": hi +R: bye: +``` + +**See also:** [`evaluation_order` in `body agent control`](/reference/components/cf-agent/#evaluation_order), +[`evaluation_order` in `body common control`][Components#evaluation_order] + +**History:** Introduced in CFEngine 3.27.0 + ### inputs **Description:** The `inputs` slist contains additional filenames to parse for promises. diff --git a/content/reference/language-concepts/policy-evaluation.markdown b/content/reference/language-concepts/policy-evaluation.markdown index 7c54b23fe..db85318c0 100644 --- a/content/reference/language-concepts/policy-evaluation.markdown +++ b/content/reference/language-concepts/policy-evaluation.markdown @@ -33,6 +33,11 @@ as early as possible in your configuration. In order to make sure all global variables and classes are available early enough policy pre-evaluation step was introduced. +Note: Since CFEngine 3.27.0 it's possible to configure the evaluation order from +the pre-defined normal order to the written order, top down. + +**See also:** [`evaluation_order` in `body agent control`](/reference/components/cf-agent/#evaluation_order), [`evaluation_order` in `body common control`][Components#evaluation_order], [`evaluation_order` in `body file control`][file control#evaluation_order] + ### Policy evaluation overview CFEngine policy evaluation is done in several steps: