Nomad plugin authoring guide

Nomad implements a plugin framework that lets you extend the functionality of some components within Nomad. The design of the plugin system is inspired by the lessons learned from plugin systems implemented in other HashiCorp products such as Terraform and Vault.

The following components are currently pluggable within Nomad:

• Device: Extend workload functionality with a custom hardware device.
• Host volume: Extend workload storage functionality with a plugin specific to your local storage environment.
• Secret provider: Extend task execution functionality with a custom secret provider.
• Task driver: Extend task execution functionality with a custom task driver.

Architecture

Go-plugin

The Nomad task driver and device plugin framework uses the go-plugin project to expose a language-independent plugin interface. Plugins implement a set of gRPC services and methods that Nomad manages by running the plugin and calling the implemented RPCs. As a result, plugins are free to be implemented in the author's language of choice. To facilitate plugin development, a set of Go interfaces and structs exist for each plugin type that abstracts away go-plugin and the gRPC interface. The guides in this documentation reference these abstractions for ease of use.

Common plugin interface

The Nomad secret provider formalized a pattern first introduced with dynamic host volume plugins into a common plugin interface. These plugins differ from Go-plugins in that they generally perform a simple task and exit, not needing to run for extended periods of time or needing to manage other resources similar to task and device drivers. Common plugins must implement a fingerprint command and implementation-specific commands.

The parent directory of all common plugin implementations is managed via the common_plugin_dir, with each implementation residing in a specific subdirectory. Check the specific plugin's documentation for directory details.