From a9f5d775932156e268bf60333f4f04c6796245bf Mon Sep 17 00:00:00 2001 From: Nick Anderson Date: Thu, 30 Oct 2025 18:46:32 -0500 Subject: [PATCH 1/2] Docs for evaulation_order => top_down Ticket: CFE-3299 --- .../policy-writing/policy-style.markdown | 30 +++++++++++------ content/reference/components/_index.markdown | 32 +++++++++++++++++++ .../reference/components/cf-agent.markdown | 31 ++++++++++++++++++ 3 files changed, 84 insertions(+), 9 deletions(-) diff --git a/content/examples/tutorials/policy-writing/policy-style.markdown b/content/examples/tutorials/policy-writing/policy-style.markdown index e6879d226..4717b609f 100644 --- a/content/examples/tutorials/policy-writing/policy-style.markdown +++ b/content/examples/tutorials/policy-writing/policy-style.markdown @@ -36,7 +36,7 @@ The other is reader optimized where promises are written in the order they make sense to the reader. Both styles have their merits, but there seems to be a trend toward the reader optimized style. -1. Normal Order +### Normal Order Here is an example of a policy written in the Normal Order. Note how `packages` are listed after `files`. This could confuse a novice who @@ -77,22 +77,27 @@ bundle agent main } ``` -2. Reader Optimized +### Reader Optimized Here is an example of a policy written to be optimized for the reader. Note how packages are listed before files in the order which users think about taking imperitive action. This style can make it -significantly easier for a novice to understand the desired state, but -it is important to remember that Normal ordering still applies and -that the promises will not be actuated in the order they are written. +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. ```cf3 -bundle agent main +body common control { - vars: + evaluation_order => "top_down"; +} - "sshd_config" - string => "/etc/ssh/sshd_config"; +bundle agent main +{ packages: @@ -100,6 +105,11 @@ bundle agent main policy => "present"; package_module => apt_get; + vars: + + "sshd_config" + string => "/etc/ssh/sshd_config"; + files: "$(sshd_config)" @@ -119,6 +129,8 @@ bundle agent main } ``` +When using `top_down` evaluation, the "Reader Optimized" style becomes the actual execution order. + ## Whitespace and line length Spaces are preferred to tab characters. diff --git a/content/reference/components/_index.markdown b/content/reference/components/_index.markdown index 348044cbb..80a6f5ddd 100644 --- a/content/reference/components/_index.markdown +++ b/content/reference/components/_index.markdown @@ -130,6 +130,37 @@ vars: you expect your policies to be run by older version, you'll need an explicit `bundlesequence`. +### evaluation_order + +**Description:** Controls the evaluation order of promises within a bundle. + +This setting allows you to change how `cf-agent` executes promises. 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 `cf-agent` to evaluate promises in the order they are written in the policy file, from top to bottom. This can make policy easier to write and understand, especially for new users, as the execution flow follows the visual layout of the code. + +This attribute can be set in `body common control` to affect all components, or in `body agent control` to affect only `cf-agent`. + +**Type:** `string` + +**Allowed input range:** `(classic|top_down)` + +**Default value:** `classic` + +**Example:** + +```cf3 +body common control +{ + evaluation_order => "top_down"; +} +``` + +**See also:** [`evaluation_order` in `body common control`][cf-agent#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering] + +**History:** + +- Introduced in CFEngine 3.27.0 + ### bwlimit **Description:** Coarse control of bandwidth any cf-serverd or cf-agent process @@ -216,6 +247,7 @@ domain => "example.org"; } ``` + ### goal_patterns **Description:** Contains regular expressions that match promisees/topics diff --git a/content/reference/components/cf-agent.markdown b/content/reference/components/cf-agent.markdown index 01a8f7f16..8902bcf0d 100644 --- a/content/reference/components/cf-agent.markdown +++ b/content/reference/components/cf-agent.markdown @@ -743,6 +743,37 @@ body action example **See also:** [`body action expireafter`][Promise types#expireafter], [`body contain exec_timeout`][commands#exec_timeout], [`body executor control agent_expireafter`][cf-execd#agent_expireafter] +### evaluation_order + +**Description:** Controls the evaluation order of promises within a bundle for `cf-agent`. + +This setting allows you to change how `cf-agent` executes promises. 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 `cf-agent` to evaluate promises in the order they are written in the policy file, from top to bottom. This can make policy 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. If set in both, 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 agent control +{ + evaluation_order => "top_down"; +} +``` + +**See also:** [`evaluation_order` in `body common control`][Components#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering] + +**History:** + +- Introduced in CFEngine 3.27.0 + ### files_auto_define **Description:** The `files_auto_define` slist contains a list of regular expressions matching filenames. When a file matching one of these regular expressions is **copied to** classes prefixed with `auto_` are defined. From f97bec9aa552418fd1125fc162d00e2b4876e839 Mon Sep 17 00:00:00 2001 From: Nick Anderson Date: Thu, 30 Oct 2025 18:49:53 -0500 Subject: [PATCH 2/2] fixup --- content/reference/components/_index.markdown | 1 - 1 file changed, 1 deletion(-) diff --git a/content/reference/components/_index.markdown b/content/reference/components/_index.markdown index 80a6f5ddd..921425465 100644 --- a/content/reference/components/_index.markdown +++ b/content/reference/components/_index.markdown @@ -247,7 +247,6 @@ domain => "example.org"; } ``` - ### goal_patterns **Description:** Contains regular expressions that match promisees/topics