Usage

The `rudderc` CLI

Rudder comes with a tool dedicated to the techniques development and usage. It is especially important as techniques are not run as YAML, but compiled into an executable policy file depending on the target platform. There are currently two possible targets, which are the platforms Rudder has agents for:

Linux/AIX
Windows

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 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:

$ rudderc new my_technique
       Wrote ./my_technique/technique.yml

$ cd my_technique

This will create the base structure of your new technique:

my_technique/
  ├── technique.yml
  ├── resources/
  └── tests/

The technique.yml is the technique content, and the resources directory can be used to include external files (configuration files, templates, etc.). The tests directory will contain your technique's tests. All files produced by rudderc will be placed in the target directory.

Check a technique

You can check the current technique syntax with:

$ rudderc check
        Read 179 methods (/path/to/methods/lib)
   Compiling my_technique v0.1 [Linux]
   Compiling my_technique v0.1 [Windows]
     Checked technique.yml

This will check the technique schema and check the compilation to the target platforms.

Compile for the target platforms

$ rudderc build
        Read 179 methods (/path/to/methods/lib)
   Compiling my_technique v0.1 [Linux]
       Wrote target/technique.cf
   Compiling my_technique v0.1 [Windows]
       Wrote target/technique.ps1
  Generating my_technique v0.1 [Metadata]
       Wrote target/metadata.xml
      Copied resources

Clean files

The clean command allows removing all generated files.

$ rudderc clean
     Cleaned target

Build the documentation

You can build this documentation directly using rudderc. This can be specially useful if you use custom methods not present in the public documentation.

$ rudderc lib
        Read 179 methods (/.../ncf/tree/30_generic_methods/)
Book building has started
Running the html backend
       Wrote target/doc/book/index.html

To open the documentation in your browser after build, pass the --open option.

Import a technique into Rudder

As normal techniques

To add a YAML technique as a "normal" technique, which gives access to the full power of parameter types, you need to run these commands on your server:

rudderc build
cd /var/rudder/configuration-repository/techniques/
mkdir -p CATEGORY/MY_TECHNIQUE/1.0/
cp -r /path/to/technique/target/* CATEGORY/MY_TECHNIQUE/1.0/
git add CATEGORY/MY_TECHNIQUE/
git commit -m "Add my technique"
rudder server reload-techniques

Warning: rudder server reload-techniques is an asynchronous command. It returns immediately with a success, and you need to check web application logs for errors (/var/log/rudder/webapp/) afterwards.

Once imported, the technique will be available like built-in ones, in the directives' page. To update the technique, repeat the import steps.

In the technique editor

The technique editor is able to directly use the YAML format (but does not support technique parameter types for now, and does not display tags).

cd /var/rudder/configuration-repository/
mkdir -p CATEGORY/MY_TECHNIQUE/1.0/
cp /path/to/technique.yml  CATEGORY/MY_TECHNIQUE/1.0/
git add CATEGORY/MY_TECHNIQUE/
git commit -m "Add my technique"
rudder server reload-techniques

Editor/IDE integration

We provide a JSON schema for Rudder YAML techniques. Depending on the editor, it provides various handy features, like property name completion, or technique structure linting. You need to import the schema in you editor (Visual Studio Code, JetBrains Editor, vim, etc. ).

Rudder techniques