Fixes #23839: Document the policy_mode in yaml rudderc documentation (#…

…5235)

policies/rudderc/docs/src/SUMMARY.md

@@ -5,7 +5,7 @@
 ---
 
 # Get started
-
+- [Installation](./installation.md)
 - [Usage](./usage.md)
 - [Syntax](./syntax.md)
 - [Testing](./test.md)

policies/rudderc/docs/src/installation.md

@@ -0,0 +1,12 @@
+# Installation
+
+* `rudderc` is built into the Rudder server. The binary is available in `/opt/rudder/bin/rudderc`.
+* On other systems, like workstations, you can download a
+  [pre-built binary](https://repository.rudder.io/tools/rudderc/8.0/) for Linux or Windows x86_64 in the repository.
+
+To be able to check and compile techniques, the `rudderc` program
+needs access to the method library of the target systems.
+When running on a Rudder server, which has a built-in `rudderc` binary,
+the local library will be used.
+The standalone binary from the repository includes the default library.
+You can override the default library by passing a `--library` argument.

policies/rudderc/docs/src/syntax.md

@@ -109,11 +109,15 @@ Blocks contains:
 * `tags` (optional): Optional key-value tags.
 * `items`: A list of items (block or method call). Cannot be empty.
 * `condition` (optional): A condition expression for the whole block. `true` is an always defined (default), `false` is never defined.
-* `reporting` (optional)
+* `policy_mode` (optional):
+  * `default`(default): Inherit policy mode from parent container
+  * `enforce`: Force the policy mode of all items within the block in enforce mode.
+  * `audit`: Force the policy mode of all items within the block in audit mode.
+* `reporting` (optional):
   * `mode`
     * `weighted` (default)
-    * `worst-case-weighted-sum`: Take the worst outcome from the block and 
-    * `worst-case-weighted-one`: Take the worst outcome from as the block as if it was a singe method
+    * `worst-case-weighted-sum`: Take the worst outcome from all the method calls in the block
+    * `worst-case-weighted-one`: Take the worst outcome from as the block as if it was a single method
     * `focus`: Apply the outcome of one of the included methods to the whole block, requires passing the `id` value
     * `disabled`: No reporting
   * `id` (required with `focus` mode): id of the method to focus reporting on.
@@ -128,9 +132,12 @@ items:
       mode: worst-case-weighted-one
     items:
       - ...
-      - ... 
+      - ...
 ```
 
+<div class="warning">Policy mode effective value will always be taken from the latest override layer. Meaning that a forced policy mode on a method call
+will always prevail over directives and blocks ones.</div>
+
 ## Methods
 
 Methods contains:
@@ -141,8 +148,12 @@ Methods contains:
 * `tags` (optional): Optional key-value tags.
 * `params`: Key-Value dictionary of parameters for the method.
 * `condition` (optional): A condition expression for the method. `true` is an always defined (default), `false` is never defined.
+* `policy_mode` (optional):
+  * `default`(default): Inherit policy mode from parent container
+  * `enforce`: Force the policy mode to enforce mode.
+  * `audit`: Force the policy mode to audit mode.
 * `reporting` (optional)
-  * `mode` 
+  * `mode`
     * `enabled` (default): Normal reporting
     * `disabled`: No reporting
 
@@ -162,3 +173,19 @@ items:
     reporting:
       mode: disabled
 ```
+
+## Resources
+
+Files can be attached to a technique, they will automatically be deployed in the policies when used on a node.
+The absolute path of the folder containing the resource files is accessible from within a technique using the variable `${resources_dir}`.
+
+To add resources to a YAML technique, put the files under a `resources` folder in the technique directory.
+In the example below, the `file1.txt` will be available from within the technique using `${resources_dir}/file1.txt`.
+
+```bash
+my_technique
+├── resources
+│   └── file1.txt
+├── technique.yml
+└── tests
+```

policies/rudderc/docs/src/test.md

@@ -3,7 +3,7 @@
 ## Write technique tests
 
 **NOTE**: Not all methods can run successfully with this testing method.
-In particular all methods exchanging files with the Rudder server won't work. 
+In particular all methods exchanging files with the Rudder server won't work.
 
 The tests are placed in a `tests` folder in the technique directory.
 Each test case is defined by a YAML file in this folder.
@@ -18,11 +18,15 @@ The format of the test case file is:
 * `check`: Test steps, run sequentially. If one of them fails the test will be considered as a failure.
 * `cleanup` (optional): Steps to run sequentially after the test to clean the environment.
 
-The setup and check sections contain a list of commands to run. The only supported step type
-for now is `sh`, which runs commands in a shell (`/usr/bin/sh` on Linux target, PowerShell on Windows target).
-The outcome is based on the returned code, 0 is a success and other codes are failures.
+#### Supported steps:
 
-Example:
+Steps are usable in `setup`, `check` and `cleanup` stages:
+
+* `sh`:
+  * On Linux: executes commands in a shell (`/usr/bin/sh`), fails if the return code is not 0
+  * On Windows: executes commands in powershell, encapsulated in a script, fails if the exit code is not 0 or if an exception was thrown
+
+#### Example:
 
 ```yaml
 target: windows
@@ -39,7 +43,7 @@ check:
   # Linux target
   - sh: "test -f /my/file"
   # Windows target
-  - sh: "Test-Path -Path C:\\my\\file"
+  - sh: "if (Test-Path -Path C:\\my\\file) { exit 0 } else { exit 1 }"
 cleanup:
   - sh: "rm -f /my/file"
 ```
@@ -95,7 +99,7 @@ It is written before running check steps, so you can use it to assess reporting
 For convenience, *check* steps have an environment variable `REPORTS_FILE` pointing to the current reports
 JSON.
 
-The JSON file contains an array of entries: 
+The JSON file contains an array of entries:
 
 ```json
 [

policies/rudderc/docs/src/usage.md

@@ -14,19 +14,6 @@ There are currently two possible targets, which are the platforms Rudder has age
 These platforms use different agent technology, but the YAML policies
 unify them.
 
-### Installation
-
-* `rudderc` is built into the Rudder server. The binary is available in `/opt/rudder/bin/rudderc`.
-* On other systems, like workstations, you can download a
-  [pre-built binary](https://repository.rudder.io/tools/rudderc/8.0/) for Linux x86_64 in the repository.
-
-To be able to check and compile techniques, the `rudderc` program
-needs access to the method library of the target systems.
-When running on a Rudder server, which has a built-in `rudderc` binary,
-the local library will be used.
-The standalone binary from the repository includes the default library.
-You can override the default library by passing a `--library` argument.
-
 ### Create a technique
 
 To setup the technique structure: