diff --git a/policies/rudderc/docs/src/SUMMARY.md b/policies/rudderc/docs/src/SUMMARY.md index 3848dcf4282..70346ee1669 100644 --- a/policies/rudderc/docs/src/SUMMARY.md +++ b/policies/rudderc/docs/src/SUMMARY.md @@ -5,7 +5,7 @@ --- # Get started - +- [Installation](./installation.md) - [Usage](./usage.md) - [Syntax](./syntax.md) - [Testing](./test.md) diff --git a/policies/rudderc/docs/src/installation.md b/policies/rudderc/docs/src/installation.md new file mode 100644 index 00000000000..01779b3a91f --- /dev/null +++ b/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. diff --git a/policies/rudderc/docs/src/syntax.md b/policies/rudderc/docs/src/syntax.md index 0870977de11..7249456618c 100644 --- a/policies/rudderc/docs/src/syntax.md +++ b/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: - ... - - ... + - ... ``` +
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.
+ ## 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 +``` diff --git a/policies/rudderc/docs/src/test.md b/policies/rudderc/docs/src/test.md index aedd697b0a5..ca0220ea426 100644 --- a/policies/rudderc/docs/src/test.md +++ b/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 [ diff --git a/policies/rudderc/docs/src/usage.md b/policies/rudderc/docs/src/usage.md index b0e9217be37..bc5ea5caa11 100644 --- a/policies/rudderc/docs/src/usage.md +++ b/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: