All Rudder public plugins in one repository. Licenses are by-plugin.
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
api-authorizations Fixes #13724: Fix plugins doc Oct 25, 2018
auth-backends next version 1.3 of plugin auth-backends Nov 7, 2018
branding next version 1.4 of plugin branding Oct 11, 2018
centreon next version 1.2 of plugin centreon Oct 29, 2018
change-validation next version 1.3 of plugin change-validation Nov 26, 2018
datasources Merge branch 'branches/rudder/4.3' into branches/rudder/5.0 Dec 7, 2018
glpi next version 1.2 of plugin glpi Oct 29, 2018
helloworld Fixes #13578: pom.xml template on helloworld was not modified Sep 25, 2018
makefiles Fixes #13749: Allow to build no license plugin with licensed target Oct 29, 2018
node-external-reports next version 1.7 of plugin node-external-reports Oct 3, 2018
notify next version 1.1 of plugin notify Nov 30, 2018
plugins-common-private Merge branch 'branches/rudder/4.1' into branches/rudder/4.3 Aug 31, 2018
scale-out-relay next version 1.2 of plugin scale-out-relay Oct 11, 2018
src/main/g8 Fixe: 13322 Update build so that licensed binaries don't embed key li… Aug 31, 2018
user-management next version 1.3 of plugin user-management Nov 7, 2018
vault Merge branch 'branches/rudder/5.0' Oct 29, 2018
.gitignore Merge branch 'branches/rudder/4.1' into branches/rudder/4.3 Aug 24, 2018
Makefile Add notify to Makefile' Nov 30, 2018
README.md Fixes #12912: Use giter8 for plugin template Jul 7, 2018
how-to-run-mvn-here.txt Fixes #12251: lib version is not parametrized in submodules Mar 21, 2018
main-build.conf Merge branch 'branches/rudder/4.3' into branches/rudder/5.0 Dec 7, 2018
pom-template.xml Fixes #13631: Plugins with elm don't get elm (again) Oct 10, 2018
qa-test Fixes #13580: Use parameter that speak for themselves in centreon plugin Sep 28, 2018

README.md

rudder-plugins

This is the repository for plugins for Rudder: Continuous configuration for effective compliance.

https://www.rudder-project.org/site/documentation/

Creating a new plugin

If you want to create a new plugin, you can use giter8 (http://www.foundweekends.org/giter8/) on that repository or directly from the file system.

Once g8 command is installed (see http://www.foundweekends.org/giter8/setup.html), use:

% g8 file://.                                                                                                     [18-07-06 18:47:53]

You can alos use the github resolution:

% g8 normation/rudder-plugins

And answer the questions. Only the name is mandatory: use the plugin short name, with space and capital if you want (see convetion below). Juste hitting choose the default value (the one between []).

name [My Plugin]: Node External Reports <ENTER>
version [1.0 ]: <ENTER>
title_description [One line description of plugin]: Add external reports in node details
web_description [<p>HTML description of plugin</p>]: <p>Add external reports in node details</p>
you_should_not_change_following_variables [just hit enter]: <ENTER>
plugin_name [node-external-reports]: <ENTER>
plugin_pkg [nodeexternalreports]: <ENTER>
plugin_class [NodeExternalReports]: <ENTER>

If you don't want to use giter8, you can replace by hand the placeholders $plugin_name$, $plugin_pkg$ and $plugin_class$ using the same convention as the previous example. Be careful to replace them in both file (with sed for example) and in path (with mv).

Repository structure

The repository is organized with one directory for each plugin under repository root directory.

Each plugin's root directory is named with the plugin "shortname identifier", i.e the plugin name minus 'rudder-plugin-" prefix.

Each plugin build information are grouped in file build.conf in plugin root directory.

Branch versionning and compability with Rudder versions

Plugins are linked to Rudder main version, so we retrieve in rudder-plugins the same branch structure than in rudder. Moreover, one needs to always compile and use a plugin for the corresponding Rudder version:

- master (plugin compatible with Rudder next version, i.e developing branch)
- branches/rudder/3.1 (plugins compatible with Rudder 3.1)
- branches/rudder/4.1 (plugins compatible with Rudder 4.1)
- etc

This branch scheme allows to accomodate API changes between main Rudder versions.

Most of the time, there is no need to recompile a plugin for the corresponding Rudder minor version, so that plugins compiled on branch branches/rudder/4.1 should be compatible with all Rudder 4.1.x versions.

It may happens that at some point in the Rudder maintenance cycle, a Rudder minor version introduces a breaking change in a plugin API or a binary incompability in a plugin ABI. In such a case, we will explain which plugin versions are compatible with which Rudder versions in plugin readme file.

Plugin version and Tag convention

Plugin versions are composed in two parts separated by a -:

  • the Rudder corresponding version (without the minor number),
  • the plugin own version in format X.Y(.Z) where the Z part is optionnal.

For example, the datasources plugin, in own version 1.1, for Rudder 4.1 will get version: 4.1-1.1.

This version is used to postfix plugin package name.

Each plugin follow his own development pace, and so there is no release cycle for plugins. Each time a plugin reaches a new step, a version for it is published by changing version information in its build.conf file. The related commit is tagged with the convention: pluginShortName-pluginVersion.

You can get all the versions for a given plugins with the git tag --list command. For example, for the datasources plugin:

$ git tag --list 'datasources-*'

# results
datasources-4.1-0.1
datasources-4.1-0.2
datasources-4.1-1.0
datasources-4.1-1.1
datasources-4.2-1.1

Building and Java stack requirements

All plugins share the same build infrastructure based on Make.

You will need:

  • standard make tool chain,
  • ar, and for any plugin with scala code (i.e most of them),
  • maven in version 3.2 or up,
  • `Java 8 JDK tools (javac, jar, etc).

For information, this the list of package that need to be installed on a minimal linux distribution:

openjdk-8-jdk maven binutils make git-core xz-utils

For the branding plugin, you need to have elm-install present on the system

npm install -g  elm

To build a plugin package, do:

git checkout tag-corresponding-to-plugin-vesion
make clean && make generate-all-pom && make plugin-name

After compilation, you will find in plugin root directory (i.e at the same level than the Makefile file) the plugin package: pluginShortName-pluginVersion.rpkg.

This package can then be transfered to a Rudder server and installed with the command:

/opt/rudder/bin/rudder-pkg install-file /path/to/pluginShortName-pluginVersion.rpkg

Building licensed / limited plugin version

As of Rudder 4.1, plugins can have a license and adapt there behavior based on runtime license information. The licensing framework is not open source, and such plugin need access to Rudder private repositories.

The common API can be build and installed in user local maven repository with the following command line when on rudder-plugins directory (for example for datasources, use the same -licensed naming convention for other):

make datasources-licensed SIGNED_LICENSE_PATH="./license.sign"  PUBLIC_KEY_PATH=/path/to/the/public/key.pub

The file license.sign is a license information file signed with the private key matching the public one used in the command line. The path of license.sign is relative to the plugin directory, so in our example, it will be located at: ./datasources/license.sign

Licensing

License are by-plugin and the license for a given plugin is specified in the LICENSE file in its plugin directory.