Plugins¶

Plugins are the primary extension mechanism in Digital Rebar Provision. A plugin is a compiled binary (a plugin provider) that runs as a subprocess alongside the DRP server and extends DRP's capabilities with new actions, parameters, object types, and event handlers. Plugin instances are configured objects in DRP that activate a plugin provider with a specific set of parameters. One provider binary can have multiple instances, each configured differently.

Plugin Architecture¶

The DRP plugin system has two layers:

• Plugin Provider — the binary executable that implements the extension. It exposes a well-defined interface: DRP calls the binary's define command to discover its capabilities (available actions, parameters it provides, object types it manages), and then communicates with the running binary via a REST protocol over UNIX-domain socket.
• Plugin Instance — a DRP object that references a provider and supplies the provider-specific configuration (credentials, endpoints, connection strings, etc.). Creating a plugin instance starts the provider binary and makes the plugin's actions and parameters available in DRP.

DRP Server
  ├── PluginProvider: ipmi       (binary: /var/lib/dr-provision/plugins/ipmi)
  │     └── Plugin instance: ipmi  (auto-created; Config: ipmi scanning parameters)
  ├── PluginProvider: bios
  │     └── Plugin instance: bios  (auto-created)
  └── PluginProvider: callback
        ├── Plugin instance: callback-apac
        └── Plugin instance: callback-amea

What Plugins Can Do¶

Plugin providers can extend DRP with:

• Actions — callable operations on machines or other objects (e.g., ipmi:power-on, ipmi:set-boot-order, callback:send)
• Parameters — new parameter definitions that the plugin manages and validates
• Object sections — additional object types stored and served by DRP (e.g., some plugins add their own configuration objects)
• Event handlers — react to DRP events (machine state changes, job completions) to trigger external automation
• Content — bundled tasks, stages, bootenvs, and templates installed when the plugin instance is created

Installing a Plugin via Catalog¶

The RackN catalog is the standard distribution mechanism for plugin providers. Use drpcli catalog to browse and install:

# List available plugin providers in the catalog
drpcli catalog items list | jq -r '.[] | select(.ContentType == "PluginProvider") | .Name'

# Install a plugin provider (downloads the binary)
drpcli catalog install callback

# Verify the provider is installed
drpcli plugin_providers list | jq -r '.[].Name'

Most plugin providers automatically create a plugin instance on installation. If manual creation is needed:

# Create a plugin instance with provider-specific configuration
drpcli plugins create '{
  "Name": "callback-apac",
  "Provider": "callback",
  "Params": {
    "callback/url": "https://hooks.example.com/apac"
  }
}'

# Verify the plugin instance is running
drpcli plugins show callback-apac | jq '{Name:.Name,Available:.Available,Errors:.Errors}'

Plugin Lifecycle¶

1. Install — download the provider binary from the catalog or upload manually with drpcli files upload
2. Create instance — drpcli plugins create with provider name and configuration params
3. Active — DRP starts the binary, discovers its capabilities, and makes actions/params available
4. Update — drpcli plugins update to change configuration; DRP restarts the provider
5. Destroy — drpcli plugins destroy <name> to stop and remove the instance; the provider binary remains installed

Building Custom Plugins¶

Custom plugin providers must implement the DRP plugin protocol:

1. Respond to <binary> define with a JSON PluginProvider object describing capabilities
2. Accept a long-running <binary> serve invocation and communicate via REST protocol over UNIX-domain socket
3. Handle action calls, parameter requests, and event subscriptions as defined in the provider spec

The plugin protocol is documented in the DRP developer SDK. A minimal Go plugin can use the gitlab.com/rackn/provision/v4/plugin package which handles the RPC layer and lets you focus on implementing action handlers:

# List all actions provided by an installed plugin
drpcli plugin_providers show callback | jq '[.AvailableActions[].Command]'

# Call a plugin action on a machine
drpcli machines runaction <machine-uuid> callback:send

For complete plugin development documentation including the Go SDK, protocol specification, and example providers, see the RackN developer portal at https://docs.rackn.io.